diff --git a/.claude/agents/arch-reviewer.md b/.claude/agents/arch-reviewer.md new file mode 100644 index 00000000..85bf8637 --- /dev/null +++ b/.claude/agents/arch-reviewer.md @@ -0,0 +1,29 @@ +--- +name: arch-reviewer +description: 바뀐 TypeScript·규칙 파일이 이 프론트 repo의 경계 규칙(AGENTS.md 꼭 지킬 것 1~3, .dependency-cruiser.json, adapter 배럴·kernel 예외, 기능·context 경계)을 지키는지 읽기만 하고 판정을 돌려준다. 구현이나 수정 묶음을 끝내고 커밋이나 PR 전에, 또는 사용자가 "구조 리뷰", "경계 확인", "레이어 위반 없나", "import 규칙 확인"이라고 할 때 쓴다. 파일을 고치지 않는다. +tools: Read, Grep, Glob, Bash +model: inherit +--- + +# arch-reviewer — 경계 규칙 리뷰(읽기 전용) + +맡긴 쪽이 준 범위(기준 커밋, diff, 경로)만 본다. 결과만 돌려주고 파일을 쓰거나 고치지 않는다. Bash는 `git diff`, `git log`, `git grep`, `python3 scripts/check-work-docs.py` 같은 읽기 명령에만 쓴다. pnpm·node·게이트는 돌리지 않는다(판정의 정본인 `check:architecture`는 맡긴 쪽이 desktop에서 돌린다). + +## 순서 + +1. 루트 `AGENTS.md`의 꼭 지킬 것과 지도, `docs/work/reference/structure.md` 2·3절을 읽는다. +2. 바뀐 파일마다 `.dependency-cruiser.json`의 `forbidden` 규칙 중 `from.path`가 그 파일에 맞는 것을 고른다. +3. 그 파일의 import(정적·type-only·re-export·리터럴 dynamic import)를 해석한 경로로 보고, 고른 규칙의 `to.path`·`pathNot`(`$1`은 `from`의 첫 그룹)에 걸리는지 본다. 특히 배럴 밖 import, kernel 셋 밖 adapter 간 import, 기능·context 간 import, presentation의 adapter 직접 import. +4. 새 파일 단위 예외(`pathNot`에 파일 하나를 더함)나 넓어진 예외가 있으면 위반으로 적는다. 예외에는 `comment`(이유·담당·재검토 조건)가 있어야 한다. +5. adapter 파일을 더하거나 옮겼으면 `docs/reviews/adapters/INVENTORY.md`가 같은 diff에서 바뀌었는지 본다. 최상위 `src/` 폴더가 바뀌었으면 `docs/architecture/layers.md` 표와 세 문서의 같은 문장이 바뀌었는지 본다. +6. 판정 규칙이 갈라진 사본으로 생기지 않았는지 본다(같은 판정 표를 두 곳에 두기, kernel이 아닌 곳의 공용 로직). + +## 돌려줄 것 + +```text +판정: 통과 / 위반 있음 / 판단 못 함 +발견: (위반마다) 꼭 지킬 것 번호 또는 규칙 이름 · 파일:줄 · 무엇이 무엇을 import하나 · 근거(문서 경로) +확인 못 한 것: (읽지 못한 파일, 게이트로만 판정할 것 — 예: 사이클, check:architecture) +``` + +발견이 없으면 "발견 0"과 본 파일 수를 적는다. 추측은 발견에 넣지 않고 「확인 못 한 것」에 넣는다. diff --git a/.claude/agents/code-simplifier.md b/.claude/agents/code-simplifier.md new file mode 100644 index 00000000..72156e2b --- /dev/null +++ b/.claude/agents/code-simplifier.md @@ -0,0 +1,27 @@ +--- +name: code-simplifier +description: 지정한 파일·diff에서 동작을 바꾸지 않고 줄일 수 있는 곳(중복, 죽은 분기, 불필요한 래퍼·상태, 더 단순한 표준 API·React 패턴)을 찾아 제안만 돌려준다. 구현을 마친 뒤 "단순하게", "정리할 곳", "중복 없나"라고 할 때나 리뷰 전에 쓴다. 파일을 고치지 않는다. 고치는 일은 맡긴 세션이 한다. +tools: Read, Grep, Glob +model: inherit +--- + +# code-simplifier — 단순화 제안(읽기 전용) + +맡긴 범위만 본다. 제안만 돌려주고 파일을 쓰지 않는다. + +## 지킬 것 + +- 동작을 바꾸는 제안을 하지 않는다. 공개 계약(adapter 배럴 표면, 공개 포트·hook 시그니처, 런타임 설정 키, 오류 code, 짝 백엔드 wire 모양)을 바꾸는 제안은 하지 않는다. +- 경계 규칙(루트 `AGENTS.md` 꼭 지킬 것 1~3)을 어기게 만드는 제안을 하지 않는다. 예: 배럴을 건너뛰어 내부 파일을 바로 import하기, kernel 예외에 파일 하나 더하기. +- 소비자 없는 확장 지점과 빈 레지스트리는 죽은 코드가 아니다. 지우자고 제안하지 않는다. 갈라진 복사본을 하나로 합치는 제안은 한다(합칠 곳은 `src/adapters/platform/`이나 `src/contracts/`). +- 테스트를 줄이는 제안은 단언이 약해지지 않을 때만 한다(`.claude/rules/tests.md`). 예산·기준선·skip을 건드리는 제안은 하지 않는다. +- 요청 범위 밖의 큰 리팩터링은 제안하지 않고 「범위 밖에서 본 것」에 한 줄로 적는다. + +## 돌려줄 것 + +```text +제안: (하나마다) 파일:줄 · 지금 모양 · 바꿀 모양(짧은 코드) · 왜 동작이 같은가 · 그것을 보일 테스트 +범위 밖에서 본 것: (있으면) +``` + +제안이 없으면 "제안 0"과 본 파일 수를 적는다. diff --git a/.claude/agents/verify-app.md b/.claude/agents/verify-app.md new file mode 100644 index 00000000..a25cdc8d --- /dev/null +++ b/.claude/agents/verify-app.md @@ -0,0 +1,31 @@ +--- +name: verify-app +description: 지정한 브랜치·커밋 또는 지금 작업 트리의 앱을 desktop에서 실제로 빌드해 preview로 띄우고, 지정한 라우트를 브라우저(Playwright)로 열어 화면·콘솔 오류·HTTP 응답만 돌려준다. 화면이나 라우트 동작을 바꾼 변경을 끝내고 "직접 돌려 봐", "화면 떠?", "앱 확인", "라우트 열어 봐"라고 할 때나 PR 전 확인으로 쓴다. 노트북에서 pnpm·브라우저를 돌리지 않고, 노트북 checkout의 파일을 고치지 않는다. +tools: Bash, Read, Grep, Glob +model: inherit +--- + +# verify-app — desktop에서 앱을 띄워 확인 + +pnpm·브라우저는 desktop에서만 돈다. 실행 위치의 정본은 `docs/work/operate.md` 4.1절이고, 이 문서는 그 안에서 앱을 띄우는 순서만 적는다. 노트북 checkout은 읽기만 한다. + +## 받을 것 + +- 확인할 트리(push된 브랜치, 또는 지금 작업 트리)와 작업 이름. +- 열 라우트 목록과 기대(보여야 할 제목·텍스트, 없어야 할 콘솔 오류). 없으면 `/`만 본다. + +## 순서 + +1. 앱이 뜨는지는 desktop의 build 게이트로 먼저 본다: `scripts/verify.sh gate FE-GATE-011 --log <작업 이름>-app`. rc와 로그 경로를 적는다. +2. 화면 확인은 같은 트리의 브라우저 게이트로 한다: `scripts/verify.sh gate FE-GATE-008 --log <작업 이름>-app`(e2e, 세 엔진). 특정 라우트만 보려면 desktop에서 `scripts/verify.sh`가 남긴 방식대로 새 worktree를 만들고 그 안에서 `flock /tmp/claude-gates/heavy.lock` 아래 `corepack pnpm build`와 `corepack pnpm exec playwright test `을 돌린다. 기존 checkout `~/workspace/clean-architecture-frontend-template`의 브랜치와 `stash@{0}`는 건드리지 않는다. +3. 받은 라우트마다 화면 텍스트와 콘솔 오류를 확인한다. 브라우저 테스트를 한 checkout에서 둘 이상 돌리면 실행마다 다른 `TEST_RUN_ID`를 준다(`ci:gate`에는 주지 않는다). +4. 끝나면 만든 worktree를 지우고 desktop checkout의 `git status`가 비었는지 본다. + +## 돌려줄 것 + +```text +결과: 떴다 / 안 떴다(멈춘 단계) +라우트: (라우트마다) 경로 · 보인 제목 · 기대와 같은가 · 콘솔 오류 수와 첫 줄 +증거: desktop 로그 경로, summary.txt 첫 줄(트리 해시) +남은 것: 지우지 못한 worktree, 확인 못 한 라우트·엔진 +``` diff --git a/.claude/rules/adapters.md b/.claude/rules/adapters.md new file mode 100644 index 00000000..bd743efb --- /dev/null +++ b/.claude/rules/adapters.md @@ -0,0 +1,13 @@ +--- +paths: + - "src/adapters/**" + - ".dependency-cruiser.json" + - "docs/reviews/adapters/INVENTORY.md" +--- + +# adapter와 import 규칙을 고칠 때 + +규칙의 정본은 `src/adapters/AGENTS.md`(그 폴더의 지역 규칙)와 `.dependency-cruiser.json`이다. 이 파일은 다시 쓰지 않고 가리킨다. + +- import 규칙을 더하거나 이름을 바꾸면 `docs/architecture/layers.md` 규칙 표도 고친다. 예외는 `pathNot`과 `comment`(이유·담당·재검토 조건)를 함께 쓴다. 규칙·예외 변경은 크기가 큼이다(`docs/work/README.md` 2절). +- 편집 훅(N3)은 편집한 파일의 import를 규칙 파일에 대 보고 의심 줄을 알린다. 그래프 전체(사이클)는 `check:architecture`만 본다. diff --git a/.claude/rules/docs.md b/.claude/rules/docs.md new file mode 100644 index 00000000..8c4205ec --- /dev/null +++ b/.claude/rules/docs.md @@ -0,0 +1,15 @@ +--- +paths: + - "**/*.md" +--- + +# 문서를 고칠 때 + +- 문서 위치·묶음·언어 규칙은 `docs/README.md`, 쓰는 절차는 `docs/work/docs-writing.md`다. +- 기록 문서(`docs/reviews/`, `docs/history/`, `docs/superpowers/`, 결정 기록)는 머리 블록만 고친다. 리뷰 영역 문서를 리뷰 뒤에 고치지 않는다. 예외는 그 라운드를 맡은 총괄이 리뷰 README에 「조치」 절(과 그 아래 diff 리뷰 절)을 더하는 것이다. +- 진입 문서(루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/` 아래 문서) 본문에는 지난 리뷰 ID·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 `docs/work/evidence.md`로 옮긴다. 편집 훅이 `scripts/check-work-docs.py`의 실패 줄을 먼저 알려 준다. +- `docs/README.md` 1절이 링크한 문서(루트 `AGENTS.md`, `docs/work/` 포함)는 `verify:documentation`이 백틱 경로·명령 경로·마크다운 링크·package script·FE-GATE ID를 본다. 있는 것만 쓴다. 검사를 피하려고 백틱을 빼지 않는다. 기능 제거 드릴의 문서 사본은 `scripts/lib/removal-fixture.ts`의 목록만 복사하니, 그 목록 밖 루트 파일을 마크다운 링크로 가리키지 않는다. +- repo 밖 문서(design-docs 등)는 링크가 아니라 코드 표기로 쓴다. +- 숫자(예산, 기준선, 테스트 수)를 옮겨 적지 않는다. 정본을 가리킨다. +- 그 문서를 읽는 테스트를 `git grep -n '<파일 이름>' -- tests scripts`로 찾는다. 있으면 desktop에서 돌린다. +- 고친 뒤: 작업 매뉴얼이면 `scripts/verify.sh docs`(노트북), 1절 묶음이면 desktop `scripts/verify.sh script verify:documentation`. diff --git a/.claude/rules/features.md b/.claude/rules/features.md new file mode 100644 index 00000000..2c11e697 --- /dev/null +++ b/.claude/rules/features.md @@ -0,0 +1,10 @@ +--- +paths: + - "src/features/**" + - "src/contexts/**" + - "tests/features/**" +--- + +# 기능 폴더를 고칠 때 + +규칙의 정본은 `src/features/AGENTS.md`·`src/contexts/AGENTS.md`(지역 규칙), 절차는 `docs/work/new-feature.md`와 `docs/manual/`이다. 새 기능은 스킬 `new-feature`로 시작한다. 이 파일은 다시 쓰지 않고 가리킨다. diff --git a/.claude/rules/gates-and-budgets.md b/.claude/rules/gates-and-budgets.md new file mode 100644 index 00000000..0e2d6018 --- /dev/null +++ b/.claude/rules/gates-and-budgets.md @@ -0,0 +1,23 @@ +--- +paths: + - "config/ci/**" + - "config/performance/**" + - "config/scale/**" + - "config/testing/**" + - ".gitea/**" + - "scripts/run-ci-gate.ts" + - "scripts/contracts/**" + - "scripts/check-*.ts" +--- + +# 게이트·예산·기준선을 고칠 때 + +정본은 `config/ci/gates.json`(게이트 ID·단계·명령), `config/performance/budgets.json`(예산), `docs/work/reference/gates.md`(언제 무엇을, 거짓 통과 막기)다. + +- 게이트 기준(문턱, 예산, 기준선, skip·only, ungated 목록)을 낮춰 통과시키지 않는다(꼭 지킬 것 4). 올리거나 넓혀야 하면 결정이다: 이유·대안·재검토 조건을 적고 소유자 결정을 받는다(`docs/work/reference/decisions.md` 3절). +- `config/ci/ungated-scripts.json`·`config/ci/ungated-tests.json`에 줄을 더하는 것은 그 script·테스트를 어느 게이트도 돌리지 않게 하는 일이다. 이유 없이 더하지 않는다. +- 기준선 기록(초기 JS, 기능 모양)은 손으로 고치지 않는다. 측정 스크립트를 `--initial-baseline --write`로 돌린 결과를 같은 변경에 넣는다. +- workflow는 생성기로 만든다. `.gitea/workflows/`만 손으로 고치지 않는다(`check:ci`가 대조한다). +- 새 검사에는 통과 fixture와 거절 fixture를 함께 둔다. 실패 메시지는 넘은 항목·잰 값·고칠 파일을 말한다. 사전 점검은 본 단계와 같은 방법으로 한 번 실행해 본다. +- 바꾼 뒤 desktop에서 `scripts/verify.sh merge`. stage·게이트 목록이 바뀌어도 `scripts/verify.sh`는 계약 파일에서 읽어 따라간다. +- 편집 훅(N6)이 이 파일들의 편집을 알린다. 알림은 막지 않는다. 의도한 변경이면 커밋 본문에 이유와 결정 출처를 적는다. diff --git a/.claude/rules/tests.md b/.claude/rules/tests.md new file mode 100644 index 00000000..70cea1e7 --- /dev/null +++ b/.claude/rules/tests.md @@ -0,0 +1,25 @@ +--- +paths: + - "tests/**" + - "**/*.spec.ts" + - "vitest.config.ts" + - "playwright*.config.ts" +--- + +# 테스트를 쓰거나 고칠 때 + +정본은 `docs/testing/taxonomy.md`(층·명령·실행 환경)와 `docs/work/reference/testing.md`(결함을 막는지 확인하는 법)다. + +1. 층은 프레임워크가 아니라 필요한 실행 환경으로 정한다: Node만 `tests/unit`, React·hook `tests/component`, HTTP/MSW·IndexedDB·조립된 경계 `tests/integration`, 실제 브라우저 `tests/e2e` 등, 한 기능의 테스트 `tests/features//`. +2. 동작을 바꾸면 재현 테스트가 먼저 실패하고(RED) 고친 뒤 통과한다(GREEN). 검출력이 문제였으면 보호 규칙을 지우는 변이를 넣어 새 테스트가 실패하는지 본다. +3. 템플릿 원래 상태 밖에서도 돈다: 기능을 더한 상태, 확장 지점을 채운 상태, 입력·객체가 셋 이상. +4. 단언이 대상에 닿는지 본다: fixture가 비어 첫 줄에서 return하지 않는가, 로딩·오류 화면이나 fixture 자신을 검사하지 않는가. +5. `.only`를 두지 않는다. `.skip`·`fixme`는 Playwright spec에만, owner·defect·route·만료일이 있는 quarantine으로만 둔다(`scripts/check-test-evidence.ts`). 빠른 계층에는 quarantine이 없다. 편집 훅이 마지막 커밋보다 늘어난 skip·only·fixme·todo를 알린다. +6. 가끔 떨어지는 테스트를 재시도·timeout 늘리기·worker 줄이기·`force` 클릭으로 덮지 않는다. 반복 실행 → 실패 기록 → 결정적 재현 → 수정 → 변이 순서로 원인을 찾는다. +7. 환경에 기대지 않는다: gitignore된 생성물, 작성자 PC의 글꼴·CPU, 바깥 env(`CI=true`, 빌드 식별값). 테스트가 띄우는 빌드·서버의 env는 테스트가 정한다. +8. 플랫폼 테스트를 기능·스타터 화면에 묶지 않는다(테스트 전용 라우트, `tests/mocks/`). 테스트가 지워도 되는 문서(`docs/reviews/` 등)를 읽지 않는다. +9. 자식 프로세스를 띄우는 suite는 자기 timeout을 선언한다. 전역 timeout을 올리지 않는다. + +## 돌리는 법 + +- 노트북에서는 돌리지 않는다. 한 파일도 desktop에서: `scripts/verify.sh script test:unit`, 또는 `ssh desktop`으로 `node scripts/run-vitest.ts run `(이 runner가 생성물을 먼저 만든다. `pnpm exec vitest run `은 import 오류로 실패한다). diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000..af316bde --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,52 @@ +{ + "permissions": { + "deny": [ + "Read(**/.env)", + "Read(**/.env.local)", + "Read(**/.env.*.local)", + "Read(**/.env.development)", + "Read(**/.env.staging)", + "Read(**/.env.production)", + "Edit(**/.env)", + "Edit(**/.env.local)", + "Edit(**/.env.*.local)", + "Edit(**/.env.development)", + "Edit(**/.env.staging)", + "Edit(**/.env.production)" + ] + }, + "hooks": { + "PostToolUse": [ + { + "matcher": "Edit|Write|MultiEdit", + "hooks": [ + {"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/hooks.py post-edit", "timeout": 30} + ] + }, + { + "matcher": "Bash", + "hooks": [ + {"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/hooks.py post-bash", "timeout": 10} + ] + } + ], + "Stop": [ + { + "hooks": [ + {"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/hooks.py stop", "timeout": 10} + ] + } + ] + }, + "extraKnownMarketplaces": { + "claude-harness": { + "source": { + "source": "git", + "url": "https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git" + } + } + }, + "enabledPlugins": { + "harness@claude-harness": true + } +} diff --git a/.claude/skills/desktop-gates/SKILL.md b/.claude/skills/desktop-gates/SKILL.md new file mode 100644 index 00000000..9a9ca150 --- /dev/null +++ b/.claude/skills/desktop-gates/SKILL.md @@ -0,0 +1,24 @@ +--- +name: desktop-gates +description: 이 프론트 repo에서 pnpm·게이트·테스트·빌드·브라우저(Playwright)·성능 측정을 돌려야 할 때 쓴다. 노트북에서는 돌리지 않고 scripts/verify.sh로 desktop에 옮겨 공유 잠금 아래 돌린다. 사용자가 "테스트 돌려", "게이트", "검증해", "merge 게이트", "ci:gate", "FE-GATE", "lint 돌려", "타입 검사"라고 하거나, 편집 훅이 턴 끝에 desktop 검증이 없다고 알렸을 때, merge 가능을 말하기 전에 부른다. 지금 트리를 패치로 보내 같은 트리에서 돌리는 법, CI env, FE-GATE-013 기록법, 로그·rc 남기기를 준다. +--- + +# desktop에서 게이트 돌리기 + +정본은 `docs/work/operate.md` 4.1절(실행 위치)·4.2절(기록)과 `docs/work/reference/gates.md`(무엇을 돌릴지)다. 이 스킬은 실행 순서표다. 둘이 다르면 정본이 맞다. + +1. 무엇을 돌릴지 고른다(`gates.md` 2절). merge 가능을 말하려면 `merge` 단계 전부다. 고른 스크립트 목록으로 merge 가능을 말하지 않는다. +2. `ssh desktop uptime`으로 부하를 적는다. +3. 돌린다. 오래 걸리면 background로 띄우고 끝나기를 한 번 기다린다. + - 단계: `scripts/verify.sh merge --log <작업 이름>` + - 게이트 하나: `scripts/verify.sh gate FE-GATE-005 --log <작업 이름>` + - 게이트의 명령을 끝까지: `scripts/verify.sh parts FE-GATE-013 --log <작업 이름>` + - package script: `scripts/verify.sh script verify:documentation test:unit --log <작업 이름>`, 인자는 `--` 뒤에(script 하나일 때만) + - 명령 하나·한 테스트 파일: `scripts/verify.sh exec -- node scripts/run-vitest.ts run <파일>` + - 파일을 만드는 명령이면 `--apply-back`으로 결과를 노트북 작업 트리에 받는다. 리뷰용 산출물 사본은 `VERIFY_SNAPSHOT=1`. + - 먼저 무엇을 돌릴지만 보려면 `--dry-run`. +4. 스크립트가 하는 일: 지금 트리를 패치로 보내고, desktop 공유 checkout에서 새 worktree를 만들어 같은 트리인지 해시로 보고, 깨끗한 커밋 하나로 만들어 오프라인 설치 뒤 `flock /tmp/claude-gates/heavy.lock` 아래 CI env(`CI=true` 등)로 돌린다. 공유 checkout의 브랜치와 stash는 건드리지 않는다. push하지 않는다. +5. 결과를 읽는다: desktop `/tmp/claude-gates/<작업 이름>/summary.txt`(첫 줄이 트리 해시), 게이트별 로그, `gate-artifacts/`, `status-after.txt`(비어 있어야 한다). +6. FE-GATE-013은 desktop에서 호스트 제약(user namespace)으로 실패한다. "호스트 제약 실패"로 적고 `parts`로 뒤 명령 결과를 함께 적는다. +7. 실패하면 기준 커밋에서도 돌려 이번 변경 몫인지 가린다. 다시 돌려 통과한 결과를 "통과"로 쓰지 않는다. +8. 보고에는 단계·게이트, rc, 시간, 핵심 숫자, 직전 부하, 트리 해시, 로그 경로를 적는다(`operate.md` 8절 표). diff --git a/.claude/skills/new-feature/SKILL.md b/.claude/skills/new-feature/SKILL.md new file mode 100644 index 00000000..7c22c6be --- /dev/null +++ b/.claude/skills/new-feature/SKILL.md @@ -0,0 +1,19 @@ +--- +name: new-feature +description: 이 프론트 템플릿(또는 복사한 프로젝트)에 새 기능(화면과 그 화면이 쓰는 API 호출, src/features//)을 더할 때 쓴다. 사용자가 "기능 추가", "새 화면", "새 페이지", "create:feature", "/new-feature ", "백엔드 API에 화면 붙이기"라고 하거나, brief의 작업 종류가 docs/work/new-feature.md일 때 부른다. corepack pnpm create:feature로 뼈대를 만들고 docs/manual 0~11단계로 채운 뒤 desktop에서 merge 단계를 돌리는 순서를 준다. 있는 기능을 고치는 일은 이 스킬이 아니라 docs/work/improve.md다. +--- + +# 새 기능 만들기 + +정본은 `docs/work/new-feature.md`(크기·받을 것·완료 기준)와 `docs/manual/`(만드는 순서와 판단 기준)이다. 이 스킬은 실행 순서표다. 둘이 다르면 정본이 맞다. + +1. `docs/work/README.md`, `docs/work/new-feature.md`, `docs/manual/README.md`를 읽고 크기를 정한다. 새 context, 기능 폴더 밖 파일 수정, 짝 백엔드와 새 계약, 예산 상향은 큼이다. 큼이면 만들기 전에 `docs/work/research-design.md`대로 소유자 검토를 받는다. +2. 받을 것을 확인한다: 기능 ID(케밥, 40자 이하), context, 짝 백엔드 경로와 작성 API 유무(`--with-create`), 재전송될 수 있는 쓰기인지(`--keyed`), 계약 패키지 신원. 백엔드 쪽 사실이 brief에 없으면 묻는다. +3. 뼈대: desktop에서 만들고 파일을 돌려받는다: `scripts/verify.sh script create:feature --apply-back -- [--context ] [--with-create [--keyed]]`. 출력(로그 폴더의 `create_feature.log`)의 `Next:` 목록을 보고에 옮긴다. 매뉴얼 예시 이름이 기능 ID로 오면 묻는다. +4. `docs/manual/01-add-a-feature.md` 2~10단계로 채운다. 막히면 02 결정표, 폴더 밖 파일은 03, 짝 백엔드 인증은 04, 오류 메시지는 `docs/manual/reference/errors.md`. +5. 동작은 테스트를 먼저 쓴다(`tests/features//`, 규칙은 `.claude/rules/tests.md`). 결과 불명 쓰기와 재전송 입구는 02 결정표 3·4절. +6. 편집 훅의 경계 알림(N3)이 나오면 그 자리에서 고친다. 기능끼리 import하지 않는다. +7. 초기 JS 기록은 `Next:`의 명령을 desktop에서 돌려 받는다(`scripts/verify.sh exec --apply-back -- node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`). 같은 커밋에 넣는다. 예산을 넘으면 올리지 말고 멈추고 묻는다. +8. desktop에서 `scripts/verify.sh merge --log <기능 id>`(스킬 `desktop-gates`), `scripts/verify.sh gate FE-GATE-026`, 그리고 이 기능의 제거 드릴 `scripts/verify.sh script test:sample-removal -- --feature=`. +9. 결과를 보고 싶으면 서브에이전트 `arch-reviewer`(경계 리뷰)와 `verify-app`(desktop에서 앱을 띄워 그 라우트를 연다)에 맡긴다. +10. `docs/work/new-feature.md` 8절 형식으로 보고한다. diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..e977fa64 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +docs/ledger/estimates.jsonl merge=union diff --git a/.gitignore b/.gitignore index 34cdbac7..7347b810 100644 --- a/.gitignore +++ b/.gitignore @@ -35,3 +35,13 @@ artifacts/tests/a11y-manual/* # graphify knowledge-graph output (local analysis, not part of the product). graphify-out/ + +# Claude Code: the project settings, path rules, skills and subagents are the +# template's (AGENTS.md, scripts/hooks/README.md). Session worktrees, the hook +# state and a developer's settings.local.json stay out. +.claude/* +!.claude/settings.json +!.claude/rules/ +!.claude/agents/ +!.claude/skills/ +__pycache__/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..b714275f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,35 @@ +# AGENTS.md — 프론트 템플릿의 정본 + +도메인 로직을 뺀 공통 기능을 갖춘 React + Vite 프론트 출발점이다(`PRODUCT.md`). 브라우저 SPA + 정적 호스팅 + Service Worker이고 SSR은 없다. 서비스는 복사해 기능 폴더를 채운다. 방향과 문제 정의는 `docs/vision.md`·`docs/problem-statement.md`(소유자가 채우는 빈 양식)다. 개발 compose는 짝 백엔드의 `compose.yaml`을 쓴다. 소비자 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이고, 갈라진 중복 복사본은 결함이다. + +## 꼭 지킬 것 — 하나라도 어기면 동작해도 완료가 아니다 + +1. adapter 그룹 밖에서는 배럴(`src/adapters/*/index.ts`)로만 들어간다. 배럴이 공개 경계다. +2. adapter끼리 import하는 예외는 `.dependency-cruiser.json`의 kernel 셋(`src/adapters/platform/` 폴더 전체, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`)뿐이다. 새 파일 단위 예외를 만들지 않는다. 공용 로직은 `src/adapters/platform/`이나 `src/contracts/`에 둔다. +3. import 규칙의 정본은 `.dependency-cruiser.json`, 판정은 `check:architecture`다. dependency-cruiser CLI는 TypeScript 7을 못 읽어 쓰지 않는다. +4. 게이트 기준(문턱, 예산, 기준선, skip·only)을 낮춰 통과시키지 않는다. +5. 관련 검증 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말하지 않는다. + +## 지도 + +- 계층·import 방향과 최상위 `src/` 폴더의 역할은 `docs/architecture/layers.md`다. +- 새 기능은 `corepack pnpm create:feature `로 만들고 `docs/manual/` 순서로 채운다. +- 게이트 ID·단계·명령의 정본은 `config/ci/gates.json`이다(설명 `docs/operations/ci-quality-gates.md`). +- adapter 파일을 더하거나 옮기면 `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다. +- 지역 규칙은 작업 파일과 가장 가까운 `src/<계층>/AGENTS.md`다. 폴더를 가로지르는 규칙(테스트·문서·게이트 기준)은 `.claude/rules/`, 문서 위치 규칙은 `docs/README.md`다. + +## 맡은 일 + +먼저 `docs/work/README.md`, 그다음 playbook 하나를 끝까지 읽는다(모두 `docs/work/`): 새 기능 `new-feature.md` · 리뷰·수정·리팩터링·성능 `improve.md` · 대안 비교와 소유자 결정 `research-design.md` · 문서 `docs-writing.md` · 게이트·릴리스·파생 프로젝트 `operate.md` · 일 나누기 `delegate.md`. brief가 있으면 brief의 범위·크기·완료 기준이 먼저다. + +## 검증 + +- 진입점은 `scripts/verify.sh <단계>`다. 단계는 `config/ci/gates.json`의 stage id(`merge` 등), 게이트 하나는 `scripts/verify.sh gate FE-GATE-005`(안에서 `corepack pnpm ci:gate FE-GATE-005`). pnpm 단계는 desktop으로 옮겨 돈다. +- "merge 가능"은 merge 단계 게이트 전부를 `CI=true`로 돌려 통과한 것이다. 골라 돌린 결과로 말하지 않는다. desktop의 FE-GATE-013은 `docs/work/reference/gates.md` 3절 문구로 적는다. +- 문서·지침을 고쳤으면 `scripts/verify.sh docs`(노트북). + +## 일하는 방식 + +- 커밋·push는 brief가 허용한 것만 자기 브랜치에 한다. main 병합·force push·PR 병합은 소유자가 한다. +- 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 git 명령을 하지 않는다. +- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. pnpm·게이트·브라우저는 누가 돌려도 desktop에서다(`docs/work/delegate.md`). diff --git a/CHANGELOG.md b/CHANGELOG.md index b74de10f..299b049c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,36 @@ - 괄호 안 ID는 리뷰 발견 ID다. `MMDD/NN-MM`으로 적는다. `MMDD`는 리뷰 폴더 `docs/reviews/YYYY-MM-DD-maturity-review/`의 월일이고, 근거와 재현 조건은 그 폴더의 영역 문서에 있다. 복사한 프로젝트가 README대로 `docs/reviews/`를 지웠다면 이 폴더와 `PRODUCT.md`는 원본 템플릿 repo에서 찾는다. 라운드마다 `NN-MM`을 새로 매기므로 같은 `14-02`라도 라운드가 다르면 다른 결함이다. `F-N`은 그 라운드 `FOLLOW-UP.md`의 ID다. 리뷰 README의 절은 `MMDD README N.N`으로 적고 다시 돌린 항목은 그 뒤에 `X2`처럼 번호를 붙인다. 영역 문서가 따로 매긴 ID는 `MMDD NN 영역 P-NN-NN`, 짝 백엔드 리뷰의 ID는 `백엔드 리뷰 MMDD/NN-MM`으로 적는다. `tests/unit/changelog-review-ids.test.ts`가 라운드 없는 ID와 이 꼴을 벗어난 참조를 막는다. - 0.2.0의 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25`에서 만들었고, `main`에서도 같은 해시로 찾을 수 있다(2026-11-03에 52개 모두 확인). 그 뒤 절은 절 머리에 범위(기준 커밋과 브랜치)를 적고, 그 절의 해시는 모두 그 범위에 있다. 통합에서 해시를 다시 쓴 뒤(fixup 접기, rebase)에는 절의 해시와 범위 커밋 본문의 해시를 `git merge-base --is-ancestor <해시> <브랜치 끝>`으로 하나씩 대조하고, 결과를 그 라운드 리뷰 README의 조치 절에 적는다. 1105 통합은 이 대조를 하지 않아, 올린 커밋 `287dc6f`의 본문이 다시 짓기 전 해시 둘을 가리킨다. 맞는 해시는 그 라운드 리뷰 README의 D7 행에 있다 (1106/14-02, 1105 README 16.2). 0.2.0의 커밋 제목은 라운드 없이 ID만 적었다(`git log --grep '03-03'`). +## 미출시 — `8327e221` → 하네스와 작업 매뉴얼 + +2026-11-07 소유자가 정한 Claude Code 작업 환경(하네스)을 백엔드 템플릿과 같은 방식으로 둔다(design-docs `harness/01-harness-design.md` 13절). 루트 지침 `AGENTS.md`(정본)와 `CLAUDE.md`(가져오기), `.claude/`(규칙·스킬·서브에이전트·권한·훅), 작업 매뉴얼 `docs/work/`, 검증 진입점 `scripts/verify.sh`, 장부 `docs/ledger/`다. 제품 코드와 게이트 동작은 바뀌지 않는다. + +### 먼저 할 일 + +- 루트 `CLAUDE.md`를 더 이상 걸러 내지 않는다. `AGENTS.md`·`CLAUDE.md`, `.claude/settings.json`·`rules/`·`skills/`·`agents/`, `docs/work/`, `scripts/hooks/`, `scripts/verify.sh`, `scripts/check-work-docs.py`, `scripts/tests/`는 템플릿 계약이라 받는다. 자기 환경에 맞게 바꿀 곳은 `docs/work/operate.md` 4.1절, `docs/work/delegate.md` 4.3절, `scripts/verify.sh`의 환경 변수(호스트, 원격 checkout, 잠금, 로그 폴더)다. +- `.gitignore`가 `.claude/`를 넷만 남기고 무시한다. 자기 `.claude/` 파일을 추적하고 있었으면 그 줄에 `!` 예외를 더한다. +- `docs/ledger/estimates.jsonl`은 줄을 비우고 받는다. `.gitattributes`의 `merge=union` 한 줄도 받는다. + +### 보안·계약 변경 + +| 표시 | 변경 | 영향 경로 | 커밋 | +| --- | --- | --- | --- | +| [계약] | 제거 드릴의 문서 사본(`REMOVAL_FIXTURE_DOCUMENT_TARGETS`)에 `AGENTS.md`가 들어간다. `docs/README.md` 1절이 `../AGENTS.md`, `work/`, `work/reference/`를 링크해 `verify:documentation`(FE-GATE-017, FE-GATE-005·020 안의 같은 검사) 범위에 든다. 이 문서들의 경로·script·게이트 ID가 틀리면 merge가 막힌다 | `scripts/lib/removal-fixture.ts`, `docs/README.md`, `tests/unit/template-contract-documents.test.ts` | `98f5c6e7`, `4a21bc79` | +| [계약] | README 지워도 되는 파일 표에서 `CLAUDE.md` 행이 빠지고 `docs/ledger/estimates.jsonl`(줄을 비운다)이 들어간다. `tests/unit/deletable-history-documents.test.ts`는 `CLAUDE.md`를 더 보지 않는다 | `README.md`, `tests/unit/deletable-history-documents.test.ts` | `98f5c6e7` | + +### 그 밖의 수정 + +- 작업 매뉴얼 `docs/work/`: README, playbook 여섯, reference 일곱, 근거 `evidence.md`. 개선 매뉴얼 초안(PR #6, main에 없음)과 옛 `CLAUDE.md`의 리뷰 기준을 흡수했다. `SPEC.md`의 공통 완료 기준은 `docs/work/improve.md` 5절로 옮겼다. 처음 읽는 세션으로 시험해 막힌 곳을 고쳤다(`3524d6b0`, `8721be47`, `18ea5e93`). +- 루트 `AGENTS.md`(꼭 지킬 것 5·지도·검증·라우터)와 `@AGENTS.md`를 가져오는 `CLAUDE.md`, 검사기 `scripts/check-work-docs.py`(`6e8cc963`). +- `src/`의 계층 폴더마다 지역 규칙 `AGENTS.md`(그 폴더의 할 일·import 금지·게이트)와 그것을 가져오는 `CLAUDE.md`. `docs/reviews/adapters/INVENTORY.md`에 두 행이 생겼다. 소유자가 채우는 빈 양식 `docs/vision.md`·`docs/problem-statement.md`(`93e3c7b1`, `f117a5af`). +- `.claude/rules/` 다섯, 스킬 `desktop-gates`·`new-feature`, 읽기 전용 서브에이전트 `arch-reviewer`·`verify-app`·`code-simplifier`, 하네스 플러그인 켜기와 실제 `.env` 읽기 차단(`9f859628`). +- repo 훅 `scripts/hooks/hooks.py`: 편집 직후 경계(`.dependency-cruiser.json` 규칙)·게이트 기준·문서 알림과 턴 끝 desktop 검증 알림. 막지 않는다(`9961ecb1`). +- `scripts/verify.sh <단계>`: stage·게이트·명령을 `config/ci/gates.json`에서 읽어 desktop에서 CI env로 돈다. `script <이름> -- <인자>`, `exec -- <명령>`, 원격에서 바뀐 파일을 받는 `--apply-back`, 리뷰용 사본 `VERIFY_SNAPSHOT=1`(`c6e42528`, `c50da347`). 장부 `docs/ledger/`(`9d65a41d`). + +### 알려진 제한 + +- 훅·검사기·`verify.sh` 시험(`python3 -m unittest discover -s scripts/tests`)은 아직 CI workflow가 부르지 않는다. 노트북 `scripts/verify.sh hooks`로 돈다. + ## 미출시 — `48c7695b` → 정리 단계 2026-11-07 소유자가 지시한 저장소 정리다(design-docs `repo-structure/04-frontend-layout.md` 9.2절, 결정은 `repo-structure/README.md` 3.4절). 범위는 `main` `48c7695b`(PR #9 병합) 다음부터다. 1단계(PR #11, `85f941c4`~`121e1125`, `main` `f33e4778`에 합침)와 2단계(브랜치 `chore/layout-2-sample-removal`, `c7e80f2f`부터 브랜치 끝까지)를 담는다. 3단계(합치기)는 아직 없다. 기준점 `48c7695b`를 빼면 이 절의 해시는 모두 이 범위에 있다. diff --git a/CLAUDE.md b/CLAUDE.md index 6c9a9ac2..6b51607b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,26 +1,10 @@ -# CLAUDE.md +@AGENTS.md -## 리뷰 기준 (모든 리뷰에 적용) +## Claude Code에서만 -이 repo를 리뷰할 때는 전체 리뷰든 모듈·PR·diff 리뷰든 [`docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`](docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md)를 기준으로 한다. - -- 발견 사항은 가이드의 28개 관점 번호로 분류한다. 결함 하나는 항목 하나로 적고 관련 관점 번호를 모두 붙인다(0.3절). 같은 결함을 여러 번 세지 않는다. -- 성격(확인된 결함 / 구조적 위험 / 미검증 / 개선 제안), 심각도(Critical~Low), 우선순위(P0~P3), 통제 수준(M0~M4), 증거(E0~E4)를 따로 적는다(35절). 확인하지 못한 것은 M0가 아니라 `미확인`이다. -- 발견 사항은 36.3절 양식, 최종 요약은 36.5절 양식, 관점별 판정은 36.2절 표를 쓴다. -- README와 설계 문서는 주장이다. 근거는 현재 커밋의 코드·설정·실행 결과에서 찾는다(34.1절). 이전 리뷰의 실행 결과를 현재 증거로 재사용하지 않는다. -- 리뷰에서는 코드를 고치지 않는다. 고치는 작업은 리뷰 문서를 근거로 별도로 진행한다. - -### 이 repo의 리뷰 전제 - -- 이 repo는 템플릿(reference implementation)이다. repo 안에 소비자가 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이지 죽은 코드가 아니다. 다만 갈라진 중복 복사본은 문제로 본다. -- adapter 배럴(`src/adapters/*/index.ts`)이 공개 경계다. -- adapter끼리 import할 수 있는 예외는 `.dependency-cruiser.json`의 kernel 예외(`src/adapters/platform/` 폴더 전체, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`)뿐이다. 새 파일 단위 예외를 제안하지 않는다. -- 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker다. SSR은 없다. - -### 전체 리뷰 절차 - -1. 기준 커밋과 가이드 0.1절 전제 표를 먼저 고정한다. -2. 게이트를 직접 실행하고 결과를 기록한다: `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema`, `verify:documentation`, `check:adapter-inventory`, `check:ci`. -3. 영역별로 서브에이전트를 병렬로 띄운다. 영역 분할은 가장 최근 `docs/reviews/*-maturity-review/README.md`의 영역 표를 재사용한다. -4. 각 에이전트는 `docs/reviews/-maturity-review/NN-<영역>.md`에 결과를 쓴다. -5. 오케스트레이터는 High 이상 발견을 코드에서 직접 재확인한 뒤 같은 폴더의 `README.md`에 범위(36.1), 28개 관점 판정표(36.2), 최종 요약(36.5), 발견 색인을 쓴다. +- 권한·훅은 `.claude/settings.json`, 훅마다 하는 일과 시험은 `scripts/hooks/README.md`다. 편집 직후 훅은 노트북 정적 검사만 하고 알리기만 한다. +- 공통 훅·스킬(위험 명령 차단, 비밀 값 알림, 장부, `estimate`·`retro`·`techdebt`)은 플러그인 `harness@claude-harness`다. 비대화형(`claude -p`)은 자동 설치하지 않으니 이 폴더에서 한 번 돌린다: + `claude plugin marketplace add https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git --scope project` + `claude plugin install harness@claude-harness --scope project` +- 경로별 규칙은 `.claude/rules/`, 스킬은 `.claude/skills/`, 서브에이전트(읽기 전용)는 `.claude/agents/`다. +- 리뷰 기준은 `docs/work/reference/review-criteria.md`, 절차는 `docs/work/improve.md` 4.1절이다. 세션 규칙은 `docs/work/delegate.md` 4.3절이다. 보고 칸은 `docs/work/README.md` 6절, 말투와 길이는 소유자 전역 설정을 따른다. diff --git a/README.md b/README.md index 8b0d536b..17a661f1 100644 --- a/README.md +++ b/README.md @@ -215,6 +215,9 @@ and executable gates pass. target designs and work history. [`docs/manual/`](docs/manual/README.md) is the step-by-step guide (Korean) for adding a feature, starting from `corepack pnpm create:feature `. +[`AGENTS.md`](AGENTS.md) is the rule book and map that people and coding agents +start from, and [`docs/work/`](docs/work/README.md) is the work manual: one +playbook per kind of task (Korean). Both are part of the template a copy keeps. ### Files you can delete after copying @@ -227,7 +230,7 @@ reads them, except the one file noted below | `docs/superpowers/` | past plans and specs | | `docs/reviews/` | reviews and the review guide. Keep `docs/reviews/adapters/`: `check:adapter-inventory` (FE-GATE-010) reads its `INVENTORY.md`, whose rows link to the adapter reviews beside it, and `docs/operations/adapter-remediation-ledger.md` cites those reviews | | `SPEC.md`, `docs/history/` | requirements of the 2026-09-25 review fix round (`SPEC.md`), and the plans and evidence of finished work, that round's task list included | -| `CLAUDE.md` | review instructions for the template repository itself; replace it with your own | +| `docs/ledger/estimates.jsonl` | the template's own task estimates and measurements; empty it and add your project's lines (`docs/ledger/README.md`) | | `PRODUCT.md` | product context of the template itself (users, purpose, principles) for design tools; replace it with your product's | A feature is not in this list: deleting its directory alone leaves tests, diff --git a/docs/README.md b/docs/README.md index fc22ea81..e9af868a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,6 +30,7 @@ README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어 입구 문서가 가리키는 세부 규칙: - 새 기능 추가 매뉴얼(작업 순서, 단계별 판단 기준, `create:feature`): [`manual/`](manual/), [`manual/reference/`](manual/reference/). 한국어다 +- 루트 지침과 작업 매뉴얼(꼭 지킬 것·지도·검증 진입점 `scripts/verify.sh`, 맡은 일마다의 playbook과 기준): [`../AGENTS.md`](../AGENTS.md), [`work/`](work/), [`work/reference/`](work/reference/). 한국어다 - 규모 설계(구조·소유·실행·트래픽·오류·검증·텔레메트리·릴리스 일관성)와 코드 주석 `scale-architecture.md §N`의 근거: [`architecture/scale-architecture.md`](architecture/scale-architecture.md). 절마다 현재 계약인지 기록만인지 머리말 표에 적었다 - 계약 소유와 호환성: [`architecture/contract-ownership.md`](architecture/contract-ownership.md), [`contracts/compatibility.md`](contracts/compatibility.md) - 짝 백엔드 Envelope 판정과 쓰기 전 거절 표(지금 실행 규칙, `src/adapters/http/backend-envelope.ts`의 근거): [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md) 4.1·6·6.1절. 기준 커밋은 [`../config/contracts/backend-contract-pin.json`](../config/contracts/backend-contract-pin.json). 같은 문서의 나머지 절은 목표 설계다 diff --git a/docs/ledger/README.md b/docs/ledger/README.md new file mode 100644 index 00000000..f6e01776 --- /dev/null +++ b/docs/ledger/README.md @@ -0,0 +1,49 @@ +# 예측·실측 장부 + +작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)를 고칠 곳을 찾는 것이 목적이다. 질타가 아니라 측정이다(소유자 결정 2026-11-07). + +```text +착수(첫 5분) ──> estimate 줄: p30·p50·p80 예측과 근거 +끝 보고 직전 ──> actual 줄: 세션 기록에서 뽑은 실측 +회고(주 1회) ──> retro 줄: 틀린 이유와 고칠 단계 +``` + +- 파일은 `docs/ledger/estimates.jsonl` 하나다. 한 줄이 JSON 하나다(JSON Lines). 줄을 고치거나 지우지 않고 더하기만 한다. 고칠 일이 있으면 같은 `task`로 `"correction": true` 줄을 더한다. +- 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게 `.gitattributes`가 이 파일에 `merge=union`을 준다. +- p30·p50·p80은 그 값 안에 끝날 확률이 30%·50%·80%라고 보는 세 값이다. p30이 도전값, p80이 안전값이다. +- 시간의 기준은 작업 중 시간이다. 끝 보고 뒤 다음 지시를 기다린 시간은 넣지 않는다. 배수는 근거(바꿀 파일 수, 검증 대기)가 있을 때만 쓴다. +- 위임 대조용 장부(design-docs `delegation-loop/ledger.jsonl`)는 그대로 둔다. 그 줄의 예측·실측 칸은 이 파일의 `task`를 가리킨다. + +## 줄의 칸 + +모든 줄: + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `schema` | 정수 | 이 형식의 판. 지금 1 | +| `kind` | `estimate` · `actual` · `retro` | 줄의 종류 | +| `task` | 문자열 | 작업 이름. 세 종류의 줄을 묶는 키다(예: 세션 이름) | +| `recorded_at` | ISO 8601 | 이 줄을 쓴 시각 | +| `transcript` | 문자열 | Claude Code 세션 기록 파일 이름(`~/.claude/projects//<이 값>.jsonl`). 실측을 다시 셀 때 쓴다 | + +`estimate`: + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `started_at` | ISO 8601 | 세션 첫 기록 시각 | +| `base` | 문자열 | 기준 커밋 | +| `task_kind`, `size` | 문자열 | `docs/work/` playbook 이름, 작음·중간·큼(`small`·`medium`·`large`) | +| `minutes`, `calls`, `output_tokens` | `{"p30","p50","p80"}` 정수 | 작업 중 시간(분), 모델 호출 수, 출력 토큰 | +| `basis` | 문자열 | 근거: 비교한 선례와 그 실측, 바꿀 파일 수, 검증 대기 | + +`actual`: + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `minutes`, `active_minutes` | 정수 | 벽시계 시간, 작업 중 시간(세션 기록 사이 빈틈을 5분까지만 더한 시간. 긴 대기와 다음 지시를 기다린 시간이 빠진다) | +| `calls`, `output_tokens`, `cache_read_tokens`, `max_context` | 정수 | 세션 기록 assistant 줄의 `message.usage`. 같은 `message.id`는 한 번만 센다 | +| `within` | 문자열 | `p30`·`p50`·`p80`·`over`: 시간 실측이 들어간 가장 작은 예측 | +| `result`, `commits` | 문자열, 배열 | 완료·부분·못 함, 만든 커밋 | +| `why` | 문자열 | 예측이 틀렸으면 이유 한 줄 | + +`retro`: `cause`(지시 모호 · 착수 전 조사 부족 · 아키텍처 경직 · 검증 대기 · 외부 대기 · 범위 변경 · 예측 근거 없음), `level`(`architecture` · `gate` · `instructions` · `user`), `note`, `ref`(고친 커밋이나 문서). diff --git a/docs/ledger/estimates.jsonl b/docs/ledger/estimates.jsonl new file mode 100644 index 00000000..23a0baa9 --- /dev/null +++ b/docs/ledger/estimates.jsonl @@ -0,0 +1,3 @@ +{"schema": 1, "kind": "estimate", "task": "fe-c-harness", "recorded_at": "2026-11-08T16:55+09:00", "transcript": "710988b0-b66b-4749-9bee-e0a2de8282e3", "started_at": "2026-11-08T16:47:38+09:00", "base": "ad3a071f", "task_kind": "docs-writing+improve", "size": "large", "minutes": {"p30": 80, "p50": 115, "p80": 170}, "calls": {"p30": 180, "p50": 260, "p80": 380}, "output_tokens": {"p30": 250000, "p50": 350000, "p80": 500000}, "basis": "착수 노트(공유 노트 fe-c-harness.md, 16:55)에 쓴 값을 옮겼다. 선례 h3-backend-harness 작업 중 68분·호출 270·출력 34.6만(손 판단 결정 약 25, desktop 실행 3회). 이번 결정 약 22(훅 언어와 범위, verify.sh 운반부, 템플릿 계약 분류, PR #6 11개를 playbook 6개와 reference로 나누기, 테스트 영향 셋)와 새로 쓰는 문서가 h3보다 많다(약 1,500줄 출력). desktop은 merge 단계 1~2회(한 번 약 25분, 잠금 대기는 시간에서 뺌). h3의 교훈대로 파일 수가 아니라 결정 수와 desktop 실행 횟수로 잡았다"} +{"schema": 1, "kind": "actual", "task": "fe-c-harness", "recorded_at": "2026-11-08T22:41+09:00", "transcript": "710988b0-b66b-4749-9bee-e0a2de8282e3", "minutes": 352, "active_minutes": 124, "calls": 247, "output_tokens": 347752, "cache_read_tokens": 134943937, "max_context": 844410, "within": "p80", "result": "done", "commits": ["3524d6b0", "6e8cc963", "9f859628", "9961ecb1", "c6e42528", "9d65a41d", "98f5c6e7", "7b565ea0", "8721be47", "4a21bc79", "c50da347", "18ea5e93", "8faec86d"], "why": "시간은 p50을 넘고 p80 안이다. 예측 근거(결정 약 22, 문서 약 1,500줄)는 맞았지만 셋이 더 들었다: 처음 읽는 서브에이전트 시험이 찾은 빈틈 21개를 고치는 일(약 25분, verify.sh 인자 전달·돌려받기 포함), 노트북에서 못 돌리는 node 시험의 결함을 desktop merge 단계에서야 찾아 다시 돌린 일, 공유 잠금 대기 중 네트워크가 끊겨 돌던 실행 셋을 다시 돌린 일. 벽시계 352분의 대부분은 잠금 대기와 네트워크 단절이다. 다음 예측은 desktop 실행 횟수에 '노트북에서 못 보는 검사의 재실행 1회'를 기본으로 넣는다. 실측은 22:40까지의 세션 기록이고 뒤의 보고는 들어 있지 않다"} +{"schema": 1, "kind": "actual", "task": "fe-c-harness", "recorded_at": "2026-11-09T00:50+09:00", "correction": true, "transcript": "710988b0-b66b-4749-9bee-e0a2de8282e3", "minutes": 482, "active_minutes": 192, "calls": 310, "output_tokens": 404844, "cache_read_tokens": 191539759, "max_context": 943733, "within": "over", "result": "done", "commits": ["93e3c7b1", "f117a5af", "48dc9f5b", "23df3203", "5fab0e46"], "why": "22:40 줄을 고친다. 그 뒤 총괄 대조로 계층 폴더 AGENTS.md 9개와 비전·문제 정의 양식이 범위에 더해졌다(약 45분). 새 트리 게이트가 INVENTORY 합계 줄과 parts의 SOURCE_DATE_EPOCH로 한 번 더 실패해 다시 돌렸다. 예측 근거에 없던 범위 추가와 desktop 재실행 둘이 p80을 넘긴 이유다. 다음 예측은 총괄 대조 뒤 추가 범위를 위해 p80에 한 묶음을 더 둔다"} diff --git a/docs/problem-statement.md b/docs/problem-statement.md new file mode 100644 index 00000000..be7ada58 --- /dev/null +++ b/docs/problem-statement.md @@ -0,0 +1,37 @@ +# 문제 정의 + +> 아이디어가 아니라 고객의 문제에서 출발한다. 좋은 스펙은 헷갈리지 않게 하는 스펙이다. +> 바뀌면 고친다(살아 있는 문서). 왜 바꿨는지는 커밋 본문이나 결정 기록(`docs/architecture/decisions/`)에 남긴다. +> 소유자가 채우는 빈 양식이다. 이 템플릿을 복사한 프로젝트는 자기 문제로 채운다. + +## 고객의 말 그대로 + +- (채울 것: 고객이 실제로 한 말을 따옴표로. 해석하지 않는다) + +## 지금은 어떻게 버티나 + +- (채울 것: 고객이 지금 쓰는 우회 방법과 그 비용) + +## 하지 않는 것 + +- (채울 것: 이번에 일부러 풀지 않는 문제, 만들지 않는 기능) + +## 성공 기준 + +구체적이고, 잴 수 있고, 이룰 수 있고, 목적에 맞고, 기한이 있게(SMART) 쓴다. + +| 기준 | 구체적으로 | 어떻게 재나 | 목표 값 | 기한 | +|---|---|---|---|---| +| (채울 것) | | | | | + +## 세 관점 점검 + +| 관점 | 묻는 것 | 답 | +|---|---|---| +| 비즈니스 | 돈이 되나, 누가 대가를 치르나 | (채울 것) | +| 기술 | 만들 수 있나, 가장 위험한 가정은 | (채울 것) | +| 고객 | 쓸모 있나, 지금 방법보다 나은가 | (채울 것) | + +## 되돌릴 수 없는 결정 + +- (채울 것: 되돌리기 비싼 결정만 여기 적고 결정 기록을 남긴다. 되돌릴 수 있는 결정은 빨리 한다) diff --git a/docs/reviews/adapters/INVENTORY.md b/docs/reviews/adapters/INVENTORY.md index 7531aafe..83ae86ae 100644 --- a/docs/reviews/adapters/INVENTORY.md +++ b/docs/reviews/adapters/INVENTORY.md @@ -149,6 +149,8 @@ | 139 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) | | 140 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) | | 141 | `src/adapters/http/fileserver-upload.ts` | [Network/state](./01-network-and-state.md) | +| 142 | `src/adapters/AGENTS.md` | 계층 규칙 문서(코드 아님, 리뷰 대상 아님) | +| 143 | `src/adapters/CLAUDE.md` | 위 문서를 가져오는 한 줄(`@AGENTS.md`) | -합계: **141/141**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다. +합계: **143/143**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다. diff --git a/docs/vision.md b/docs/vision.md new file mode 100644 index 00000000..ce198591 --- /dev/null +++ b/docs/vision.md @@ -0,0 +1,10 @@ +# 비전 + +> 소유자가 직접 쓴다. AI에게 맡기지 않는다. 방향·목적·철학만, 길어야 세 문장이다. +> 에이전트는 이 문서를 읽기만 한다. 고칠 일이 보이면 제안만 한다. 이 템플릿을 복사한 프로젝트는 자기 비전으로 채운다. + +1. 누구의 어떤 문제를 푸는가: (채울 것) +2. 성공하면 무엇이 달라지나(잴 수 있게): (채울 것) +3. 속도보다 먼저 지킬 것: (채울 것) + +점검 질문: 이 목표를 다 이뤘는데도 실패한다면 무엇 때문일까? 그 답이 빠진 목표다. diff --git a/docs/work/README.md b/docs/work/README.md new file mode 100644 index 00000000..4a8af6a3 --- /dev/null +++ b/docs/work/README.md @@ -0,0 +1,75 @@ +# 작업 매뉴얼 + +이 폴더는 이 repo에서 하는 모든 일의 절차서다. 사람과 AI 세션이 같은 절차를 쓴다. +읽는 순서는 하나다: 루트 `AGENTS.md`(지도) → 이 README → 맡은 일의 playbook 하나. Claude Code 세션에서는 루트 `CLAUDE.md`가 `AGENTS.md`를 가져온다. +규칙의 정본은 `AGENTS.md`, `.dependency-cruiser.json`, `config/ci/gates.json`이다. 이 폴더는 규칙을 다시 쓰지 않고, 일하는 순서를 정한다. + +## 1. 어떤 playbook인가 + +| 맡은 일 | playbook | +| --- | --- | +| 새 기능을 만든다(`create:feature`) | [new-feature.md](new-feature.md) | +| 있는 코드를 리뷰·수정·리팩터링·최적화한다. 구조·테스트 구조를 바꾼다 | [improve.md](improve.md) | +| 바꾸기 전에 대안을 비교하고 소유자 결정을 받는다 | [research-design.md](research-design.md) | +| 매뉴얼·안내 문서를 쓰거나 고친다 | [docs-writing.md](docs-writing.md) | +| 게이트를 돌린다, 릴리스한다, 파생 프로젝트에 템플릿 변경을 넘긴다 | [operate.md](operate.md) | +| 큰 일을 나눠 다른 세션에 맡긴다 | [delegate.md](delegate.md) | + +둘에 걸리면 이렇게 고른다. 결정이 먼저 필요하면 research-design이다. 동작이 바뀌는 코드가 있으면 new-feature나 improve다. 문서만 바뀌면 docs-writing이다. + +## 2. 크기 정하기 + +- 크기는 작음·중간·큼 셋이다. 정의와 크기별로 할 단계는 design-docs(이 repo 옆 checkout `desktop-server-git/design-docs`) `conventions/work-thinking-order.md` 2절이 정본이다. +- 요약: 작음은 파일 몇 개·새 결정 없음·되돌리기 쉬움, 중간은 경계 하나(adapter 그룹, 기능 폴더, 문서 폴더) 안의 여러 파일이나 소유자 없이 정할 작은 결정 하나, 큼은 새 체계·아키텍처·공개 계약·소유자 결정이 필요한 일이다. +- brief(작업 지시문)에 크기가 있으면 그대로 한다. 올릴 수는 있고 내릴 수는 없다. 올리면 이유를 보고에 쓴다. brief가 없으면 스스로 정한다. 망설여지면 큰 쪽이다. +- 아래는 파일이 하나여도 큼이다: import 규칙(`.dependency-cruiser.json`), 최상위 `src/` 폴더, adapter 배럴의 공개 표면, 게이트 단계·기준(`config/ci/gates.json`, `config/performance/budgets.json`), 짝 백엔드와 맞춘 계약(`config/contracts/`), 런타임 설정 키, 파생 프로젝트가 따라 고쳐야 하는 변경, 보안 정책. +- 큰 일은 만들기 전에 멈추고 소유자 검토를 받는다([research-design.md](research-design.md)). 소유자가 그 변경을 이미 정했으면(결정 색인 행, 소유자 원문) 그 결정이 소유자 검토다. 출처와 시각을 보고에 적고 만든다. 결정이 다루지 않은 범위만 멈추고 묻는다. + +## 3. 모든 작업의 공통 단계 + +1. 기준 커밋을 고정한다. `git rev-parse HEAD`를 산출물과 보고에 적는다. +2. 이미 정한 것을 읽는다: [reference/decisions.md](reference/decisions.md), `docs/reviews/`에서 가장 최근 리뷰 README의 「결정이 필요한 것」「조치」「미검증」 절. 정한 것은 다시 묻지 않는다. +3. 바뀌는 경계를 찾고 가장 가까운 `src/<계층>/AGENTS.md`를 읽는다. 위험은 파일 수가 아니라 경계로 정한다: 사용자 데이터(결과 불명 쓰기, 브라우저 저장소), 공개 포트·배럴, merge 게이트, 짝 백엔드 계약을 건드리면 높다. +4. 스킬을 고른다. playbook 3절에 작업별 스킬이 있고, 이 repo의 스킬은 `.claude/skills/`다(`new-feature`, `desktop-gates`). 파일을 바꾸는 일은 직접 하거나 하위 세션에 맡기고, 결과만 받는 일은 서브에이전트에 맡겨도 된다([delegate.md](delegate.md) 4.3절). +5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다. +6. 무거운 실행(pnpm, 게이트, 브라우저, 빌드)은 [operate.md](operate.md) 「실행 위치」대로 `scripts/verify.sh`로 한다. +7. 일이 다른 경계나 brief 범위를 넘어야 하면 거기서 멈추고 묻는다(5절). +8. 완료를 말하기 전에 검증한다(`superpowers:verification-before-completion`). 돌리지 못한 검증은 못 돌렸다고, 이유와 함께 쓴다(꼭 지킬 것 5). + +## 4. 커밋 + +- 커밋·push는 brief가 허용한 것만 그 작업의 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 커밋만 허용됐으면 push하지 않는다(desktop 검증은 `scripts/verify.sh`가 패치로 옮긴다). +- main 병합, main·다른 브랜치 push, force push, PR 병합은 하지 않는다. 그것은 소유자(또는 소유자가 정한 총괄)가 한다. +- 메시지 형식은 design-docs `conventions/commit-and-pr.md`를 따른다. AI 꼬리말과 자리표시자(`TBD`, `TODO`, 채우지 않은 칸)를 넣지 않는다. 결함 수정은 꼬리말 `Refs:`에 발견 ID를 적는다(형식은 [reference/review-criteria.md](reference/review-criteria.md) 11절). +- 커밋 하나에 논리 변경 하나다. 동작 변경을 위한 리팩터링은 앞 커밋으로 나눈다. 그 작업이 바꾼 파일만 stage한다. + +## 5. 막혔을 때 + +- 소유자만 정할 수 있는 것(공개 계약, 파생 프로젝트 동작, 보안 정책, 게이트 기준, 되돌리기 비싼 선택)은 근거와 권하는 안을 붙여 한 번 묻고, 그 항목만 멈춘다. +- brief를 준 쪽이 있으면 그쪽에 묻는다. 없으면 소유자에게 묻는다. 형식: 항목 · 선택지 · 권하는 안과 이유 · 정할 사람. + +## 6. 보고 + +- 맨 앞에 결과(완료 / 부분 / 못 함)와 브랜치·커밋을 쓴다. 그다음 변경, 확인(명령 · 실행 위치 · rc · 로그 경로), 범위 밖에서 본 것(고치지 않음), 남은 문제를 쓴다. 남은 문제를 숨기지 않는다. +- 보고는 쉬운 한국어로 쓴다. 코드·명령·로그 인용만 원문 그대로 둔다. 숫자(테스트 수, 실패 수, 시간)는 로그에서 옮긴다. +- 착수할 때 예측(p30·p50·p80과 근거)을, 끝 보고 직전에 실측을 `docs/ledger/estimates.jsonl`에 한 줄씩 더한다(형식 `docs/ledger/README.md`). +- 사고 순서 흔적 칸(목적·선행 사례·방법·필요한 정보·격차·만들고 시험 여섯 줄, 생략한 단계는 이유)을 둔다(design-docs `conventions/work-thinking-order.md` 5절). 다른 세션이 맡긴 일이면 design-docs `conventions/delegation-loop.md` 5절 양식을 쓴다. + +## 7. 필요할 때만 읽는 문서 + +| 문서 | 내용 | +| --- | --- | +| [reference/gates.md](reference/gates.md) | `scripts/verify.sh`, 언제 무엇을 돌리나, merge 가능 판정, CI env, 문서 검사 범위 | +| [reference/review-criteria.md](reference/review-criteria.md) | 결함 정의, 등급, 증거, 28개 관점마다 볼 곳, 리뷰 문서 양식 | +| [reference/structure.md](reference/structure.md) | 폴더·모듈·코드 구조 기준, 바꿀 때 같이 고칠 것 | +| [reference/testing.md](reference/testing.md) | 테스트 위치, 검출력 확인, 가끔 떨어지는 테스트 | +| [reference/performance.md](reference/performance.md) | 예산 세 맥락, 측정 조건, 숫자를 고칠 때 | +| [reference/defect-patterns.md](reference/defect-patterns.md) | 반복해서 나온 결함의 모양과 막는 기준 | +| [reference/decisions.md](reference/decisions.md) | 이미 정한 결정의 색인, 결정 대기 쓰는 법 | +| [evidence.md](evidence.md) | 이 매뉴얼의 규칙이 나온 사건과 지난 리뷰 ID | + +## 8. 이 폴더를 고칠 때 + +- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 15줄, 폴더 지역 규칙(`src/**/AGENTS.md`, 옆에 `@AGENTS.md` 한 줄 `CLAUDE.md`) 200줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다. +- 본문에 지난 리뷰 ID·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서도 같다. `reference/decisions.md`·`reference/defect-patterns.md`와 리뷰 문서는 ID를 둔다. +- 고친 뒤 `scripts/verify.sh docs`(노트북)와 desktop `scripts/verify.sh script verify:documentation`이 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다. diff --git a/docs/work/delegate.md b/docs/work/delegate.md new file mode 100644 index 00000000..dc1cf465 --- /dev/null +++ b/docs/work/delegate.md @@ -0,0 +1,124 @@ +# 총괄 — 큰 일을 나눠 다른 세션에 맡긴다 + +총괄 세션이 일을 나누고, brief를 쓰고, 결과를 대조하고, 합치는 절차다. 공용 절차(brief 양식, 보고 양식, 대조, 교훈 정리, 장부, 지표)의 정본은 design-docs `conventions/delegation-loop.md`다. 이 playbook은 그것을 다시 쓰지 않고, 이 repo의 일을 나누는 법만 더한다. + +```text +총괄 + ├─ 리뷰 라운드: 게이트 1회 → 사본 공유 → 영역 리뷰어 → 실험 목록 → 일괄 실행 → README + ├─ 수정 라운드: 영역별 수정 세션(자기 worktree·브랜치) → 통합 브랜치 → merge 단계 + └─ 멈춤 판정 → 마지막 Medium·Low 수정 → 보고 +``` + +## 1. 언제 쓰나 + +- 일이 커서 여러 세션으로 나눠야 할 때: 전체 리뷰, 영역별 수정 묶음, 리뷰와 수정의 반복, 여러 playbook에 걸친 일. +- 세션 하나가 끝까지 할 수 있는 일이면 이 playbook이 아니다. 그 일의 playbook을 쓴다. +- 맡은 쪽(하위 세션)은 이 playbook이 아니라 brief가 가리킨 playbook을 따른다. + +## 2. 받아야 할 것 + +- 소유자의 목표와 이미 정한 결정. 큰 일이면 소유자가 계획을 검토한 시각. +- 결과가 올라갈 브랜치와 그 최신 커밋(기준 커밋). +- 커밋 허용과 자기 브랜치 push 허용(따로 적는다). push 없이도 desktop 검증은 된다(`scripts/verify.sh`가 패치로 옮긴다). main 병합·main push는 소유자가 한다. +- 마감과 보고 받을 방법. + +## 3. 크기와 사고 순서 + +- 크기는 총괄이 정해 brief에 적는다. 정의는 design-docs `conventions/work-thinking-order.md` 2절이다. 큰 일은 하위 세션이 1~5단계와 대안 비교까지만 하고 멈추게 쓴다. 소유자 검토 뒤 만들기를 다시 맡긴다. +- 총괄 자신의 선행 사례는 지난 라운드의 나누는 법이다: 가장 최근 리뷰 README의 영역 표, 「조치」 절, 「오케스트레이터 자신의 실수」 절. +- 스킬: `delegate`(소유자 환경의 실행판)가 있으면 쓴다. 정본과 다르면 정본이 맞다. + +## 4. 절차 + +### 4.1 맡기고 닫는 순서 + +design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 → 나누기(4.2절) → 기준 커밋 → brief → 하위 세션 띄우기 → 보고 대조 → 합치기 → 교훈 정리 → 장부 한 줄 → 소유자 보고. + +이 repo에서 더할 것: + +- 하위 세션은 착수 보고(이해한 것, 모호한 점과 고른 가정, 예측)를 공유 노트에 쓰고 기다리지 않는다. 예측과 실측은 그 세션이 `docs/ledger/estimates.jsonl`에 한 줄씩 더한다. +- brief에 넣을 것: 목표 한 문장과 끝났다고 볼 조건, 기준 커밋·브랜치·worktree, 읽을 정본과 지난 기록의 위치, 하지 말 것(리뷰면 코드 수정, 수정이면 범위 밖 파일·push·PR, 공통으로 짝 백엔드 쓰기), 실행 위치(`scripts/verify.sh`, [operate.md](operate.md) 4.1절), 보고 형식. +- 「이미 아는 것」에는 [reference/decisions.md](reference/decisions.md)의 결정을 **내용으로** 옮긴다. 번호만 쓰지 않는다. +- 결론을 미리 주지 않는다. 총괄이 만든 변경을 리뷰시킬 때는 코드만 주고 결론은 주지 않는다. +- 수정 묶음 brief에는 공통 지시를 넣는다: RED 먼저, 논리 변경 하나에 커밋 하나, 커밋 규칙, AI 꼬리말 금지, `corepack pnpm`, 무거운 실행은 desktop 공유 잠금 아래. 보고의 「새로 가정하는 것」 칸을 요구한다. +- 하위 세션이 결정이 필요한 것을 만나면 총괄에 한 번 묻고 기다린다. 스스로 정하지 않는다. +- 대조할 때: 보고의 명령·테스트 수를 desktop 로그(`/tmp/claude-gates/<로그 이름>/summary.txt`)에서 찾는다. High 이상과 새 P1은 총괄이 코드에서 직접 다시 확인한다. +- 수정 결과의 "고침"을 그대로 믿지 않는다. 다음 리뷰가 ID별로 다시 판정한다. +- 교훈을 보낼 곳: 그 playbook의 「자주 하는 실수」, 코드 결함 모양은 [reference/defect-patterns.md](reference/defect-patterns.md), 거짓 통과는 [reference/gates.md](reference/gates.md) 6절, 근거는 [evidence.md](evidence.md). + +### 4.2 나누는 법 — 이 repo + +영역은 가장 최근 리뷰 README의 영역 표(16개)를 다시 쓴다. 영역 하나에 리뷰어 하나다. + +| 영역 묶음 | 경로 | +| --- | --- | +| adapters(6개 영역) | `src/adapters/<그룹>/`: browser-transfer, browser-files·cache·cross-context, http·state, realtime, storage·kernel, service worker·push | +| contracts, presentation, app core | `src/contracts/`, `src/presentation/`, `src/bootstrap/`·`src/features/`·`src/platform/` | +| 테스트(2개 영역) | `tests/` 빠른 계층, 브라우저·릴리스·규모 | +| guardrails·CI, build·release | `scripts/`, `config/ci/`, `.gitea/`, 공급망·release 경로 | +| 문서, 성능, 구조 | `docs/`·`README.md`, 예산과 실측, 폴더 구조·기능 개발 패턴 | + +**리뷰 중 실행 — 한 번 돌리고 함께 읽는다**(소유자 결정 2026-11-05). + +- 게이트는 총괄이 `VERIFY_SNAPSHOT=1 scripts/verify.sh merge`로 한 번 돌리고, 리뷰어에게 desktop 로그 폴더와 `snapshot/` 경로를 준다. 리뷰어마다 같은 빌드·테스트를 다시 돌리지 않는다. 영역 리뷰어 16개가 각자 desktop에서 돌려 잠금 줄에 30여 건이 서고 32건을 취소한 일이 있다. +- 추가 실험은 목록으로 모은다. 항목마다 ID, 명령, env, 시간 상한, 필요하면 변이 패치. 같은 명령은 한 번만 돌리고 결과를 함께 쓴다. +- 실험마다 작업 폴더를 되돌린다. 항목 앞뒤로 추적 파일을 기준 커밋으로 되돌리고 추적 안 된 파일을 지운다(`node_modules`는 둔다). +- 작업 폴더 복제본을 늘려 해결하지 않는다. 한 checkout에서 두 실행이 부딪히는 원인은 고정 출력 경로·고정 포트라는 템플릿 결함이다. 복제본은 그 결함을 가린다. + +두 세션이 동시에 만지면 손으로 풀어야 하는 파일이다. 한 세션만 맡기거나, 총괄이 합칠 때 직접 고친다. + +| 파일 | 왜 | +| --- | --- | +| `CHANGELOG.md` | 묶음마다 미출시 절의 같은 줄 근처를 고친다. 마지막에 한 세션이 다시 쓴다 | +| `docs/reviews/<폴더>/README.md` | 범위·판정표·요약·색인·조치는 총괄이 쓴다 | +| `docs/reviews/adapters/INVENTORY.md`, `.dependency-cruiser.json` | adapter·규칙 하나가 모든 그룹에 걸린다 | +| `config/ci/gates.json`, `.gitea/workflows/*`, `package.json`, `pnpm-lock.yaml` | 단계 검사·생성 workflow·lockfile 전체가 바뀐다 | +| `config/performance/budgets.json`, 초기 JS 기준선 기록 | 묶음마다 맞아도 합친 트리에서 낡는다. 합친 끝에서 다시 잰다 | +| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/`, `scripts/hooks/`, `scripts/verify.sh` | 모든 세션이 읽거나 모든 세션에 걸린다 | + +나눌 때 지킬 것: 두 묶음이 같은 파일을 건드리지 않게 나눈다. 묶음마다 그 시점 최신 기준에서 시작한다. 같은 결함을 두 영역이 보면 한 묶음에만 배정한다. 합칠 때 충돌 해결 밖에서 새로 고칠 것이 생기면 병합 커밋에 넣지 않고 따로 커밋한다. + +### 4.3 소유자 환경 + +하위 세션을 띄우는 법, 보고가 총괄에게 전달되는 길, 공유 노트 폴더, 짝 백엔드 일의 경로 같은 규칙은 design-docs `conventions/delegation-loop.md` 11절 한 곳에 있다. 이 repo에서 더할 것: + +- 나누는 기준(소유자 결정 2026-11-07): + - 파일을 바꾸는 위임, 소유자가 열어 보고 멈출 수 있어야 하는 일은 하위 세션(이 playbook)이다. + - 결과만 받는 일(넓은 검색, 구조 리뷰 `arch-reviewer`, desktop에서 앱을 띄워 보는 확인 `verify-app`, 단순화 제안 `code-simplifier`, 영역 리뷰처럼 문서를 커밋하지 않는 리뷰)은 서브에이전트(정의 `.claude/agents/`)다. 서브에이전트는 파일을 고치지 않는다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다. + - pnpm·게이트·브라우저는 누가 돌려도 desktop에서다(`scripts/verify.sh`). +- 짝 백엔드 repo는 읽기만 한다. stage·commit·push하지 않는다. +- 공유 노트: 같은 세션 그룹은 repo 밖 공유 노트 폴더에 큰 발견과 인계 메모를 남긴다. 메시지에 길게 붙이지 않는다. 하위 세션은 다른 노트를 먼저 읽는다. +- 이 절은 소유자의 도구에 묶인 규칙이다. 복사한 프로젝트는 이 절과 [operate.md](operate.md) 4.1절만 자기 환경으로 바꾼다. + +## 5. 완료 기준 + +- 하위 세션마다 brief가 양식대로이고 자리표시자가 없다. +- 보고를 diff·커밋·로그와 대조했고 불일치를 셌다. +- 합친 트리에서 merge 단계가 통과했다(desktop 로그). +- 리뷰·수정 반복이면 [improve.md](improve.md) 4.5절 멈춤 기준이 모두 참이다. +- 교훈 정리와 장부 한 줄을 끝냈다. 소유자 보고에 변경 / 확인(명령·결과·커밋) / 남은 문제가 있다. + +## 6. 하지 말 것 + +- 하위 세션의 일을 대신 하지 않는다. 대조에 필요한 읽기와 확인만 직접 한다. +- 보고를 그대로 믿지 않는다. 같은 파일을 두 세션에 맡기지 않는다. +- 하위 세션에 main 병합·main push, force push, 다른 브랜치 push를 허용하지 않는다. +- 영역 리뷰어마다 desktop에서 게이트를 돌리게 하지 않는다(4.2절). + +## 7. 막혔을 때 + +- 소유자만 정할 수 있는 것은 근거와 권하는 안을 붙여 소유자에게 한 번 묻는다. 그 결정에 기대는 묶음만 멈추고 나머지는 계속한다. +- 하위 세션이 묻는 질문에는 답하고, 질문 원문과 "답이 매뉴얼에 있었나"를 적어 둔다. + +## 8. 보고 형식 + +소유자에게는 변경 / 확인 / 남은 문제 세 칸으로 쓴다. 하위 세션 보고 양식과 대조표는 design-docs `conventions/delegation-loop.md` 5·6절이다. 소유자가 이미 아는 외부 일(PR 병합, CI runner 켜기)은 남은 문제와 섞지 않는다. + +## 9. 자주 하는 실수 + +- 게이트 목록을 지난 라운드 목록에서 가져와 merge 게이트를 놓친다. `scripts/verify.sh merge`로 stage 전부를 돌린다. +- 판정 표를 짝 백엔드 문서만으로 정한다. 코드까지 따라간다. +- 다운스트림 파일을 열지 않고 이름으로 추정해 이행 안내를 쓴다. 확인하지 않은 것은 "미확인"으로 쓴다. +- `verify:documentation`을 옆 checkout 없는 임시 worktree에서 그냥 `pnpm`으로 돌려 재설치 대기로 멈춘다. `scripts/verify.sh script verify:documentation`으로 돌린다(설치를 먼저 한다). +- 제거 드릴을 `npm run`으로 돌려 모든 검사가 `Unknown command`로 실패한다. `corepack pnpm`만 쓴다. +- PR을 만들기 전에 그 head 브랜치의 열린·닫힌 PR과 base 상태를 보지 않아 이미 병합된 커밋으로 PR을 또 만든다. Gitea API(`/api/v1/repos///pulls?state=all`)로 먼저 본다. diff --git a/docs/work/docs-writing.md b/docs/work/docs-writing.md new file mode 100644 index 00000000..9a4394d3 --- /dev/null +++ b/docs/work/docs-writing.md @@ -0,0 +1,74 @@ +# 문서 작성 — 매뉴얼과 안내 문서를 쓰고 고친다 + +이 repo의 문서(매뉴얼, 안내, 운영 문서, 이 작업 매뉴얼)를 쓰거나 고치는 일의 절차다. 문서 체계(위치, 묶음, 언어, 머리 블록)의 정본은 `docs/README.md`와 design-docs `conventions/docs-system.md`다. 이 playbook은 그것을 다시 쓰지 않고 쓰는 순서와 검사만 정한다. + +## 1. 언제 쓰나 + +- 매뉴얼(`docs/manual/`), 운영 문서(`docs/operations/`, `docs/runbooks/`), 계약 문서(`docs/architecture/` 등 `docs/README.md` 1절 묶음), 루트 `README.md`·`CHANGELOG.md`를 쓰거나 고친다. +- 이 작업 매뉴얼(루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/` 아래 규칙·스킬·서브에이전트 문서)을 고친다. +- 코드 동작이 바뀐 변경의 문서 몫은 이 playbook이 아니라 그 변경의 playbook 안에서 같은 커밋으로 한다. 이 playbook의 검사는 그때도 쓴다. + +## 2. 받아야 할 것 + +- 독자(누가 이 문서만 읽고 무엇을 끝내나)와 목적. +- 바꿀 문서와 그 문서의 묶음(현재 계약 / 목표 설계 / 작업 이력, `docs/README.md`). +- 문서만 바꾸는지, 코드도 바꾸는지. + +## 3. 크기와 사고 순서 + +- 오타·깨진 링크·한 문장 정정은 작음이다: 목적 한 줄, 대상 확인, 검증. +- 새 안내 문서나 playbook 하나는 중간이다. 문서 체계(묶음, 언어, 진입 경로)를 바꾸는 일은 큼이다. 소유자 검토가 먼저다. +- 선행 사례: 같은 독자를 둔 이 repo의 문서(`docs/manual/`, `docs/work/`)와, 그 문서를 읽고 일한 기록(보고, cold-read 시험 기록). +- 스킬: `technical-writing-best-practices`, `documentation-and-adrs`. 사람이 터미널에서 따라 하는 절차서면 `writing-practitioner-guides`. + +## 4. 절차 + +1. 독자와 목적을 한 문장으로 쓴다: "<누가> 이 문서만 읽고 <무엇을> 끝낸다". +2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, `.dependency-cruiser.json`, `config/ci/gates.json`, `config/performance/budgets.json`, 계약 문서에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞고, 문서를 고친다. +3. 위치를 정한다. 문서 위치 규칙은 `docs/README.md`다. 지금 코드가 지키는 규칙은 1절 묶음(링크하면 `verify:documentation` 범위에 든다), 앞으로의 설계는 2절, 리뷰·계획·작업 추적은 3절(복사한 프로젝트가 지울 수 있다). 여러 repo나 소유자 운영에 걸친 내용은 design-docs에 둔다. +4. 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다. 문체는 「~한다」다. +5. 절차는 한 줄에 한 단계, 동사로 시작한다. 명령·경로·package script·게이트 ID는 실제로 있는 것만 쓴다(`package.json`, `config/ci/gates.json`, `ls`로 확인). +6. 지난 일을 근거로 쓸 때는 날짜, 무엇이 일어났나, 숫자를 한 줄로 쓴다. 작업 매뉴얼(1절 둘째 줄의 문서) 본문에는 리뷰 ID·번호만 쓴 결정을 쓰지 않는다. 걷어낸 ID 중 근거로 남길 것은 [evidence.md](evidence.md)에 모은다. 다른 문서는 리뷰 ID를 출처로 둘 수 있다(꼴은 `MMDD/NN-MM`). +7. 링크: repo 안 문서는 상대 링크로 쓴다. repo 밖 문서(design-docs 등)는 링크가 아니라 코드 표기로 쓴다. `verify:documentation`이 repo 밖 링크를 옆 checkout에서 찾아 기계마다 결과가 달라진다. +8. 숫자를 복제하지 않는다. 예산·기준선·테스트 수처럼 코드가 정하는 값은 쓰는 순간 낡는다. 정본을 가리킨다. 측정값을 꼭 적으면 커밋과 측정일을 붙인다. +9. `verify:documentation` 범위(`docs/README.md`와 그 1절이 링크한 문서, 폴더 링크는 그 폴더 바로 아래 `.md`)의 문서라면: + - 백틱 안 repo 경로, 셸 코드 블록과 백틱 안 명령의 경로 인자, 마크다운 링크, `corepack pnpm