Initial Commit
This commit is contained in:
@@ -0,0 +1,131 @@
|
||||
# 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`).
|
||||
|
||||
### 세션 부트스트랩 & 기억 문서 (하이퍼워터폴 접목)
|
||||
|
||||
새 세션은 이 순서로 읽고 시작:
|
||||
1. `docs/orders/` 최신 파일 — 오늘 뭐 하는지 + 진행 중 feature
|
||||
2. 그 feature 의 `specs/<feature>/tasks.md` + 최신 `stage-N.md` — 어디까지 했는지
|
||||
3. 필요하면 `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는 참고하지 않는다**
|
||||
Reference in New Issue
Block a user