20260807_OPENCODE_TEMP/CODE_ASSISTANT

Fork 0

Files

T

leehc991028 858ee9e9da Initial Commit

2026-09-16 17:22:14 +09:00

10 KiB

Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

code-assistant v2 — Rust + Tauri 기준 Windows 데스크톱 앱(4_rust_tauri/) + React SPA 화면(2_frontend/, Vite + TS + shadcn/ui + react-query). 기존 .NET 앱(3_windowsApp/)은 참고용 legacy. 백엔드(FastAPI)는 별도 repo에서 연동.

여긴 이 코드베이스만 아는 것과 워크플로우 툴(spec-kit 앞단 + superpowers 뒷단)을 어떻게 붙이는지만 적는다. 일반 방법론은 그 툴들이 담당.

Tradeoff: 신중함 > 속도. 사소한 작업은 판단으로.

재사용 우선: 신규 기능도 기존 컴포넌트·훅·util·패턴을 최대한 먼저 찾아 재사용하고, 없을 때만 새로 만든다. 새로 만들 땐 왜 기존 걸 못 쓰는지 한 줄 먼저 말함. (구체 카논·컨벤션은 4번.)

작업 모드: ponytail(게으른 최소구현 — YAGNI·기존 재사용·최소 diff) + caveman(핵심만 압축해서 말함) 을 기본으로 한다. 스킬/플러그인 설치 여부와 무관하게 이 규칙을 적용 — 전역 설정은 git 밖이라 PC 바뀌면 조용히 꺼지므로, repo에 박아두는 게 진실원천. 단 caveman 은 0번 톤(한글 친구 반말)을 유지한 채 길이만 압축 — 영어 caveman체로 바꾸지 말 것.

0. 응답 톤 및 사전 규칙

친구 반말로 답함. "~입니다 / ~합니다 / ~세요" 금지. "~임 / ~함 / ~야 / ~지 / ~거든 / ~해봐 / ~잖아" 형태로. 고등학생도 알아들을 쉬운 단어 사용. 어려운 한자어·전문 용어는 풀어 쓰고, 모던 기술 용어(API, deploy, cache, refactor 등)는 그대로.

"추상화 계층을 도입한다" → "한 번 감싸서 따로 분리함" "멱등성이 보장된다" → "여러 번 실행해도 결과가 같음" "정합성을 검증한다" → "값이 맞는지 확인" "선언적으로 기술한다" → "어떻게 할지 말고 무엇을 원하는지만 적음"

문서 작성 언어: spec·plan·tasks·회의록·진행상황 등 프로젝트 MD 문서 전부 한글. 코드 식별자·기술 용어는 영어 그대로. 코드 주석도 한글 우선.

1. 워크플로우 = spec-kit(앞단) + superpowers(뒷단)

역할 분담: spec-kit 이 "뭘/왜"를 문서로 뽑고(spec/plan/tasks), superpowers 가 그걸 규율 있게 실행한다(TDD·리뷰·검증). 경계선은 tasks.md 완성 시점 — 여기서 핸드오프.

spec-kit 미설치면 먼저 uvx --from git+https://github.com/github/spec-kit.git specify init --here --integration claude --script ps 실행 (구버전 --ai 옵션은 폐기됨). 설치되면 /speckit-* 스킬이 .claude/skills/ 아래에 생김 (gitignore 대상 — 머신마다 다시 설치).

feature 파이프라인

1. (아이디어 흐릿하면) superpowers:brainstorming 으로 의도 정리
2. /speckit-specify   → spec.md   (뭘 만들지·유저스토리)
3. /speckit-clarify   → 애매함 제거 (선택)
4. /speckit-plan      → plan.md   (이때 3번 docs-lib 먼저 참조)
5. /speckit-tasks     → tasks.md
6. /speckit-analyze   → 문서 정합성 (선택)
──────── 여기서 spec-kit → superpowers 핸드오프 ────────
7. superpowers:executing-plans (또는 subagent-driven-development)
      로 tasks.md 실행. 각 task 는 superpowers:test-driven-development (RED→GREEN)
      task 묶음(단계) 하나 끝날 때마다 specs/<feature>/stage-N.md 기록 — 승인 대기 없이 계속
8. 완료 전 superpowers:verification-before-completion + /code-review
9. specs/<feature>/report.md (계획 vs 결과 비교) 작성 → 사용자 최종 승인 → merge

곁가지

병렬: 독립 task(파일 disjoint + 시그니처 서로 안 import)는 superpowers:dispatching-parallel-agents 로 한 번에 여러 개 dispatch.
버그: 반드시 superpowers:systematic-debugging 먼저 — 재현 테스트부터. 끝나면 docs/troubleshootings/yyyy-mm-dd-<keyword>.md 로 사건 기록 (1 사건 = 1 파일).
리뷰: implementer → spec → code 3-stage 그대로 (superpowers:requesting-code-review).

세션 부트스트랩 & 기억 문서 (하이퍼워터폴 접목)

새 세션은 이 순서로 읽고 시작:

docs/orders/ 최신 파일 — 오늘 뭐 하는지 + 진행 중 feature
그 feature 의 specs/<feature>/tasks.md + 최신 stage-N.md — 어디까지 했는지
필요하면 docs/feedback/·docs/tech/ — 왜 그렇게 하기로 했는지

기록은 시키지 않아도 자발적으로 (양식은 각 폴더 README):

오늘 할 일: docs/orders/YYYYMMDD.md — 하루 1파일. ztodo.md 는 여기로 승격돼 폐기
단계 보고: specs/<feature>/stage-N.md — 한 일 / 검증 결과 / 다음
완료 보고: specs/<feature>/report.md — 계획 vs 결과 비교, 최종 승인용
피드백: 사용자가 방향 교정해주면 즉시 docs/feedback/yyyy-mm-dd-<keyword>.md — 원문 + 왜 틀렸는지 + 앞으로 어떻게
기술 사실: docs/tech/<topic>.md — topic 당 1파일 갱신형. plan 짤 때 docs-lib 와 같이 참조

겹침 방지 (spec-kit ↔ superpowers ↔ 이 파일)

plan 집은 하나 — spec-kit specs/<feature>/ 가 유일. superpowers:writing-plans 로 또 딴 plan 문서 만들지 마(그 역할은 /speckit-plan·/speckit-tasks 가 함).
backlog·미착수 작업도 specs/ 안에 — 따로 docs/*-TODO.md 만들지 마. "결정했지만 안 만든" 일 = specs/NNN-*/ 폴더가 spec/plan 까진 있고 tasks.md 체크박스가 안 채워진 상태. tasks.md 가 살아있는 상태판(진실원천), 메모리는 "다음에 이거 이어서" 포인터 정도로만.
constitution 은 이 파일 참조만 — /speckit-constitution 은 얇게, 규칙은 "CLAUDE.md 따른다"고 가리키기만. 톤(0)·컨벤션(4) 복붙 금지 — 두 군데 관리되면 어긋남. 이 파일이 캐논.
의도 수집 한 번만 — brainstorming(흐릿)→specify→clarify 중 겹치게 두 번 심문 X. 명확하면 brainstorming 건너뛰고 specify 부터.

2. 일반 방법론은 스킬이 담당 (여기 중복 X)

신중히 생각(가정 명시·트레이드오프)·단순하게(YAGNI·최소 코드)·최소 변경(surgical)·검증 루프(성공기준→TDD) — ponytail·superpowers 스킬 + 시스템 프롬프트가 이미 이걸 함. CLAUDE.md 에 또 적으면 같은 말 2~3번 → 어느 걸 따를지 판단만 헷갈림(context engineering 안티패턴).

그래서 이 파일은 툴 배선(1번) + 이 코드베이스 gotcha(3·4번) 만 담는다. 방법론은 그 스킬들이 캐논.

3. 라이브러리 문서 참조 (docs-lib)

각 모듈에는 그 모듈이 쓰는 라이브러리 문서(llm.txt 류 전문)를 모아둔 docs-lib/ 가 있다. 구현 전 반드시 먼저 참조한다.

위치: 모듈 루트의 docs-lib/ (예: 2_frontend/docs-lib/). 카탈로그·갱신법은 그 안의 README.md.
구현 트리거: 작업이 어떤 라이브러리(react-query, SSE streaming, tiptap, dnd-kit 등)에 닿으면, 코드 짜기 전에 해당 docs-lib/<lib>.md 를 먼저 본다. 기억·추측으로 API 쓰지 말 것.
읽는 법: 파일이 크니(수 MB) 통째로 읽지 말고 Grep 으로 필요한 부분만 꺼내 쓴다.
폴더가 없으면 만든다: 작업 모듈에 docs-lib/ 가 없으면 디렉토리 + README.md(카탈로그) 만들고, 참조 문서를 거기 떨어뜨린 뒤 그걸 보고 구현.

사용자가 시키지 않아도 자발적으로 수행할 것.

4. 코드 컨벤션 (이 코드베이스 준용)

먼저 카논 파일을 열어 그대로 베낀다 (진실원천): feature 모듈 2_frontend/src/features/memos/ (api·hooks·components·pages). → feature 구조, api 객체 패턴(memosApi 식), react-query hook 패턴, 테스트 스타일(memos.api.test.ts 의 axios-mock-adapter) 은 여기 열어보면 다 보임 — 표에 다시 안 적음.

아래는 파일만 봐선 확신 못 하는(추측하면 틀리는) 것만 명문화:

항목	따를 패턴
API 호출	axios 직접 호출 금지. `@/lib/api/client` 의 `apiGet/apiPost/apiPatch/apiDelete/apiList` 만 사용, feature 의 `api/<도메인>.api.ts` 에 `<도메인>Api` 객체로 모음
서버 상태	react-query 만. queryKey 는 `<도메인s>_KEY` 상수로 export, mutation 성공 시 `invalidateQueries` + `sonner` toast(한글 메시지), 에러는 `ApiError`(`@/lib/api/errors`) instanceof 분기
서버 DTO 타입	`src/types/api` 에만 정의(camelCase). feature 안에 서버 타입 새로 만들지 말 것
클라 상태	zustand. 전역은 `shared/store`, feature 전용 store 는 그 feature 안에
주석·문서	한글·반말 톤(0번 규칙)
포매팅·검증	편집 후 `npm run format`. 완료 선언 전 `npm run lint` + `npm run test` + `npm run build` 통과

기존 패턴과 다르게 짜야 할 이유가 있으면 먼저 말하고 확인받는다.

5. 작업로그 (worklog)

작업하면서 커밋보다 작은 스텝을 그때그때 한 줄씩 남긴다. 사람이 읽는 로그라, 사람 어투로 핵심만.

위치: z-my-docs/work-log/ — 월별 폴더(2026-07/) 아래 날짜별 md 하나. 표(| 시간 | 내용 |)로 쌓임. 이게 원본이자 결과물 — 따로 렌더/생성 단계 없음(에디터·GitHub 어디서나 바로 표로 보임).

남기는 법: python z-my-docs/work-log/gen_worklog.py add "<한 일 한 줄>" — 지금 시각 찍어 오늘 md 표에 행 append. 파일 없으면 제목+헤더까지 만듦.
언제: 의미 있는 스텝 하나 끝날 때마다(재현·수정·검증 등). 커밋 단위 아님 — 그보다 잘게.
git 작업은 로그에 남기지 마 — commit·push·branch·merge·add·renormalize 등 형상관리 자체는 worklog 대상 아님(git 히스토리가 이미 기록). "무엇을 만들었나"만 남기고 "그걸 커밋했다"는 빼.
안 적고 넘어가려 하면 Stop hook(worklog_guard.py)이 딱 한 번 붙잡음 — 그때 위 명령으로 한 줄 남기면 됨. 진짜 남길 것 없으면 그냥 다시 멈추면 통과.
톤: 0번 규칙(친구 반말)·"핵심만"·짧게. 파일명·기술용어 빼면 한글.

99. 기타

zmemo.txt는 참고하지 않는다

10 KiB Raw Permalink Blame History