chore(merge): 하네스 PR #13이 들어간 main을 받는다
frontend-quality-gates / FE-GATE-001 / manifest-lockfile (pull_request) Successful in 1m20s
frontend-quality-gates / FE-GATE-002 / lint (pull_request) Successful in 1m13s
frontend-quality-gates / FE-GATE-003 / typecheck (pull_request) Successful in 1m2s
frontend-quality-gates / FE-GATE-004 / runtime-schema (pull_request) Successful in 1m4s
frontend-quality-gates / FE-GATE-005 / unit (pull_request) Failing after 2m13s
frontend-quality-gates / FE-GATE-006 / component (pull_request) Successful in 1m12s
frontend-quality-gates / FE-GATE-007 / integration (pull_request) Successful in 1m17s
frontend-quality-gates / FE-GATE-010 / architecture (pull_request) Successful in 1m38s
frontend-quality-gates / FE-GATE-011 / build (pull_request) Successful in 57s
frontend-quality-gates / FE-GATE-012 / bundle (pull_request) Successful in 53s
frontend-quality-gates / FE-GATE-013 / security (pull_request) Failing after 36s
frontend-quality-gates / FE-GATE-020 / removability (pull_request) Failing after 12m49s
frontend-quality-gates / FE-GATE-008 / e2e (pull_request) Successful in 9m9s
frontend-quality-gates / FE-GATE-009 / accessibility (pull_request) Failing after 6m43s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / FE-GATE-001 / manifest-lockfile (pull_request) Successful in 1m20s
frontend-quality-gates / FE-GATE-002 / lint (pull_request) Successful in 1m13s
frontend-quality-gates / FE-GATE-003 / typecheck (pull_request) Successful in 1m2s
frontend-quality-gates / FE-GATE-004 / runtime-schema (pull_request) Successful in 1m4s
frontend-quality-gates / FE-GATE-005 / unit (pull_request) Failing after 2m13s
frontend-quality-gates / FE-GATE-006 / component (pull_request) Successful in 1m12s
frontend-quality-gates / FE-GATE-007 / integration (pull_request) Successful in 1m17s
frontend-quality-gates / FE-GATE-010 / architecture (pull_request) Successful in 1m38s
frontend-quality-gates / FE-GATE-011 / build (pull_request) Successful in 57s
frontend-quality-gates / FE-GATE-012 / bundle (pull_request) Successful in 53s
frontend-quality-gates / FE-GATE-013 / security (pull_request) Failing after 36s
frontend-quality-gates / FE-GATE-020 / removability (pull_request) Failing after 12m49s
frontend-quality-gates / FE-GATE-008 / e2e (pull_request) Successful in 9m9s
frontend-quality-gates / FE-GATE-009 / accessibility (pull_request) Failing after 6m43s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
main(d1b9c087)에 하네스 PR #13이 들어가 루트에 `AGENTS.md`, `.claude/`,
`.gitattributes`가 생겼다. 이 브랜치는 그 셋을 루트 등록부에 optional로
미리 적어 두었다.
충돌 둘을 풀었다.
- `scripts/lib/removal-fixture.ts`: main은 문서 복사 목록에 `AGENTS.md`를
더했고 이 브랜치는 그 목록을 등록부의 `fixture-documents` 집합으로
바꿨다. 등록부의 `AGENTS.md` 항목에 그 집합을 적었다.
- `tests/unit/template-feature-removal-documents.test.ts`: main은 문서
목록에 `AGENTS.md`와 옛 a11y 기록 폴더를 더했다. a11y 기록은 이
브랜치에서 `docs/`로 옮겼으므로 `AGENTS.md`만 남겼다.
등록부의 `AGENTS.md`·`.claude`·`.gitattributes`는 이제 추적되는 항목이라
optional을 빼고 역할을 실제 내용으로 고쳤다. 추적되는 루트 항목과
등록부 항목이 서로 남는 것 없이 같다.
검증(desktop): 커밋별 5검사와 merge 게이트 14개, verify:documentation.
This commit is contained in:
@@ -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"과 본 파일 수를 적는다. 추측은 발견에 넣지 않고 「확인 못 한 것」에 넣는다.
|
||||
@@ -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"과 본 파일 수를 적는다.
|
||||
@@ -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 <spec>`을 돌린다. 기존 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, 확인 못 한 라우트·엔진
|
||||
```
|
||||
@@ -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`만 본다.
|
||||
@@ -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`.
|
||||
@@ -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`로 시작한다. 이 파일은 다시 쓰지 않고 가리킨다.
|
||||
@@ -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)이 이 파일들의 편집을 알린다. 알림은 막지 않는다. 의도한 변경이면 커밋 본문에 이유와 결정 출처를 적는다.
|
||||
@@ -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/<id>/`.
|
||||
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 <file>`(이 runner가 생성물을 먼저 만든다. `pnpm exec vitest run <file>`은 import 오류로 실패한다).
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
@@ -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절 표).
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
name: new-feature
|
||||
description: 이 프론트 템플릿(또는 복사한 프로젝트)에 새 기능(화면과 그 화면이 쓰는 API 호출, src/features/<id>/)을 더할 때 쓴다. 사용자가 "기능 추가", "새 화면", "새 페이지", "create:feature", "/new-feature <id>", "백엔드 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 -- <id> [--context <id>] [--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/<id>/`, 규칙은 `.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=<id>`.
|
||||
9. 결과를 보고 싶으면 서브에이전트 `arch-reviewer`(경계 리뷰)와 `verify-app`(desktop에서 앱을 띄워 그 라우트를 연다)에 맡긴다.
|
||||
10. `docs/work/new-feature.md` 8절 형식으로 보고한다.
|
||||
@@ -0,0 +1 @@
|
||||
docs/ledger/estimates.jsonl merge=union
|
||||
+10
@@ -32,3 +32,13 @@ artifacts/tests/*
|
||||
|
||||
# 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__/
|
||||
|
||||
@@ -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 <id>`로 만들고 `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`).
|
||||
@@ -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`~`ad3a071f`), 3단계(합치기)와 4단계(배치 규칙 검사)(브랜치 `chore/layout-3-merge`, `bf485f44`부터 브랜치 끝까지)를 담는다. 기준점 `48c7695b`를 빼면 이 절의 해시는 모두 이 범위에 있다.
|
||||
|
||||
@@ -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/<YYYY-MM-DD>-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절, 말투와 길이는 소유자 전역 설정을 따른다.
|
||||
|
||||
@@ -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 <id>`.
|
||||
[`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,
|
||||
|
||||
@@ -21,9 +21,8 @@
|
||||
{
|
||||
"path": ".claude",
|
||||
"kind": "tool-convention",
|
||||
"role": "Claude Code 설정·규칙·스킬. 하네스 작업(fe-c)이 더한다",
|
||||
"readBy": "Claude Code",
|
||||
"optional": true
|
||||
"role": "Claude Code 설정·규칙·스킬·서브에이전트",
|
||||
"readBy": "Claude Code"
|
||||
},
|
||||
{
|
||||
"path": ".dependency-cruiser.json",
|
||||
@@ -41,9 +40,8 @@
|
||||
{
|
||||
"path": ".gitattributes",
|
||||
"kind": "tool-convention",
|
||||
"role": "git 병합 규칙. 하네스 작업(fe-c)이 더한다",
|
||||
"readBy": "git",
|
||||
"optional": true
|
||||
"role": "git 병합 규칙(작업 장부 docs/ledger/estimates.jsonl을 union으로 합친다)",
|
||||
"readBy": "git"
|
||||
},
|
||||
{
|
||||
"path": ".gitea",
|
||||
@@ -86,9 +84,9 @@
|
||||
{
|
||||
"path": "AGENTS.md",
|
||||
"kind": "tool-convention",
|
||||
"role": "에이전트 진입 문서. 하네스 작업(fe-c)이 더한다",
|
||||
"readBy": "코딩 에이전트",
|
||||
"optional": true
|
||||
"role": "에이전트 진입 문서(꼭 지킬 것·지도·검증). docs/README.md 1절이 가리키는 현재 계약 문서",
|
||||
"readBy": "코딩 에이전트, verify:documentation (FE-GATE-017)",
|
||||
"sets": ["fixture-documents"]
|
||||
},
|
||||
{
|
||||
"path": "CHANGELOG.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). 같은 문서의 나머지 절은 목표 설계다
|
||||
|
||||
@@ -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/<cwd>/<이 값>.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`(고친 커밋이나 문서).
|
||||
@@ -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에 한 묶음을 더 둔다"}
|
||||
@@ -0,0 +1,37 @@
|
||||
# 문제 정의
|
||||
|
||||
> 아이디어가 아니라 고객의 문제에서 출발한다. 좋은 스펙은 헷갈리지 않게 하는 스펙이다.
|
||||
> 바뀌면 고친다(살아 있는 문서). 왜 바꿨는지는 커밋 본문이나 결정 기록(`docs/architecture/decisions/`)에 남긴다.
|
||||
> 소유자가 채우는 빈 양식이다. 이 템플릿을 복사한 프로젝트는 자기 문제로 채운다.
|
||||
|
||||
## 고객의 말 그대로
|
||||
|
||||
- (채울 것: 고객이 실제로 한 말을 따옴표로. 해석하지 않는다)
|
||||
|
||||
## 지금은 어떻게 버티나
|
||||
|
||||
- (채울 것: 고객이 지금 쓰는 우회 방법과 그 비용)
|
||||
|
||||
## 하지 않는 것
|
||||
|
||||
- (채울 것: 이번에 일부러 풀지 않는 문제, 만들지 않는 기능)
|
||||
|
||||
## 성공 기준
|
||||
|
||||
구체적이고, 잴 수 있고, 이룰 수 있고, 목적에 맞고, 기한이 있게(SMART) 쓴다.
|
||||
|
||||
| 기준 | 구체적으로 | 어떻게 재나 | 목표 값 | 기한 |
|
||||
|---|---|---|---|---|
|
||||
| (채울 것) | | | | |
|
||||
|
||||
## 세 관점 점검
|
||||
|
||||
| 관점 | 묻는 것 | 답 |
|
||||
|---|---|---|
|
||||
| 비즈니스 | 돈이 되나, 누가 대가를 치르나 | (채울 것) |
|
||||
| 기술 | 만들 수 있나, 가장 위험한 가정은 | (채울 것) |
|
||||
| 고객 | 쓸모 있나, 지금 방법보다 나은가 | (채울 것) |
|
||||
|
||||
## 되돌릴 수 없는 결정
|
||||
|
||||
- (채울 것: 되돌리기 비싼 결정만 여기 적고 결정 기록을 남긴다. 되돌릴 수 있는 결정은 빨리 한다)
|
||||
@@ -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를 같은 변경에서 갱신한다.
|
||||
|
||||
|
||||
@@ -0,0 +1,10 @@
|
||||
# 비전
|
||||
|
||||
> 소유자가 직접 쓴다. AI에게 맡기지 않는다. 방향·목적·철학만, 길어야 세 문장이다.
|
||||
> 에이전트는 이 문서를 읽기만 한다. 고칠 일이 보이면 제안만 한다. 이 템플릿을 복사한 프로젝트는 자기 비전으로 채운다.
|
||||
|
||||
1. 누구의 어떤 문제를 푸는가: (채울 것)
|
||||
2. 성공하면 무엇이 달라지나(잴 수 있게): (채울 것)
|
||||
3. 속도보다 먼저 지킬 것: (채울 것)
|
||||
|
||||
점검 질문: 이 목표를 다 이뤘는데도 실패한다면 무엇 때문일까? 그 답이 빠진 목표다.
|
||||
@@ -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)다.
|
||||
@@ -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/<owner>/<repo>/pulls?state=all`)로 먼저 본다.
|
||||
@@ -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 <script>`와 백틱 안 `<prefix>:<name>` 꼴의 script, `FE-GATE-0NN` ID가 실제로 있어야 한다.
|
||||
- 기능 제거 드릴(FE-GATE-020)이 문서를 복사한 사본에서도 같은 검사를 돈다. 사본은 `scripts/lib/removal-fixture.ts`의 목록만 복사한다. 그 목록에 없는 루트 파일을 마크다운 링크로 가리키면 드릴이 실패한다.
|
||||
- 검사를 피하려고 경로를 백틱 밖으로 옮기지 않는다. 검사 약화로 기록된 일이 있다.
|
||||
10. 그 문서를 읽는 테스트를 찾는다: `git grep -n '<파일 이름>' -- tests scripts`. 있으면 그 테스트가 기대하는 문장을 지키고 desktop에서 돌린다. 문서 관련 단위 테스트는 `tests/unit/documentation-readiness.test.ts`, `tests/unit/deletable-history-documents.test.ts`, `tests/unit/changelog-review-ids.test.ts`다.
|
||||
11. 검사를 돌린다.
|
||||
- 작업 매뉴얼을 바꿨으면 노트북에서 `scripts/verify.sh docs`(분량 상한, 본문 이력 ID 0, playbook 뼈대, 상대 링크). 편집 훅이 실패 줄을 먼저 알려 준다.
|
||||
- 1절 묶음 문서를 바꿨으면 desktop에서 `scripts/verify.sh script verify:documentation`. 짝 백엔드 참조가 "확인 못 함"으로 남으면 그 참조뿐인지 적는다.
|
||||
- 다른 문서의 이력 ID·상대 링크는 `python3 scripts/check-work-docs.py --history <경로>`, `--links <경로>`로 본다.
|
||||
12. 매뉴얼·playbook·진입 경로를 새로 만들거나 크게 바꿨으면 cold-read 시험을 한다(정본 design-docs `conventions/delegation-loop.md` 10절). 혼자 하는 일이면 최소한 자가 점검을 한다: 지도부터 읽어 그 문서만으로 실제 일 하나의 brief를 써 보고, 막힌 곳을 고친다.
|
||||
|
||||
**playbook을 새로 만들 때의 뼈대**(모든 playbook이 같은 제목을 쓴다. 검사 스크립트가 본다): `1. 언제 쓰나` · `2. 받아야 할 것` · `3. 크기와 사고 순서` · `4. 절차` · `5. 완료 기준` · `6. 하지 말 것` · `7. 막혔을 때` · `8. 보고 형식` · `9. 자주 하는 실수`(10줄 이하)
|
||||
|
||||
## 5. 완료 기준
|
||||
|
||||
- 독자 한 문장이 있고, 문서가 그 독자의 일을 처음부터 끝까지 다룬다.
|
||||
- 문서의 명령·경로·script·게이트 ID가 기준 커밋에 실제로 있다. 정본을 복사한 문장이 없다.
|
||||
- 작업 매뉴얼을 바꿨으면 `scripts/verify.sh docs`가 rc=0이다. 1절 묶음 문서를 바꿨으면 desktop `verify:documentation`이 통과했다(로그 경로).
|
||||
- 매뉴얼을 새로 만들었거나 진입 경로를 바꿨으면 cold-read 시험이나 자가 점검 결과가 보고에 있다.
|
||||
|
||||
## 6. 하지 말 것
|
||||
|
||||
- 정본의 규칙을 문서에 다시 쓰지 않는다. 갈라진 복사본이 된다.
|
||||
- 리뷰 영역 문서를 리뷰 뒤에 고치지 않는다. 처리 결과는 리뷰 README에 쓴다. 기록 문서(리뷰, 계획)는 머리 블록만 고친다.
|
||||
- 소유자 환경 규칙(실행 위치, 세션 도구)을 여러 곳에 쓰지 않는다. [operate.md](operate.md) 4.1절과 [delegate.md](delegate.md) 4.3절에만 둔다.
|
||||
- 현재 계약 문서가 작업 이력 문서(복사한 프로젝트가 지울 수 있는 것)에 기대게 하지 않는다.
|
||||
|
||||
## 7. 막혔을 때
|
||||
|
||||
- 정본끼리 다르게 말하면 어느 쪽도 고르지 않는다. 양쪽 근거를 붙여 [README](README.md) 5절 형식으로 묻는다.
|
||||
- 같은 시간에 문서 체계를 바꾸는 다른 세션이 있으면 그 세션이 맡은 파일을 고치지 않는다. 필요한 줄은 그 세션에 넘긴다.
|
||||
|
||||
## 8. 보고 형식
|
||||
|
||||
[README](README.md) 6절에 더해 적는다: 독자 한 문장, 바꾼 문서와 묶음, 검사(명령 · 실행 위치 · rc), 문서를 읽는 테스트를 찾은 명령과 결과, cold-read나 자가 점검에서 막힌 곳과 고친 것.
|
||||
|
||||
## 9. 자주 하는 실수
|
||||
|
||||
- 노트북에 없는 경로(다른 브랜치에만 있는 파일)를 백틱으로 써서 `verify:documentation`이 실패한다. 기준 커밋에서 `ls`로 확인한다.
|
||||
- 숫자를 문서에 옮겨 적고 다음 변경에서 낡는다. 정본을 가리킨다.
|
||||
- 지운 기능·스크립트의 이름이 문서에 남는다. 지우는 커밋에서 `git grep`으로 문서를 같이 고친다.
|
||||
@@ -0,0 +1,99 @@
|
||||
# 근거와 이력
|
||||
|
||||
이 매뉴얼의 규칙이 나온 사건과 지난 리뷰 ID를 모은다. 진입 문서(루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`의 README·playbook·reference, `.claude/` 아래 문서)는 ID 없이 내용과 날짜로 쓰고, ID는 여기에 둔다(`scripts/check-work-docs.py`가 본다).
|
||||
|
||||
**표기.** 리뷰 ID는 리뷰 가이드 36.3절의 라운드 밖 표기 `MMDD/NN-MM`이다. `1103/11-07`은 `docs/reviews/2026-11-03-maturity-review/`의 발견 11-07이다. 「1105 README」는 `docs/reviews/2026-11-05-maturity-review/README.md`다. 라운드: 0925·0929·1101·1103·1105(네 번째)·1106(다섯 번째). 0924는 `docs/reviews/2026-09-24-src-full-review.md`다.
|
||||
|
||||
## 1. 이 매뉴얼이 나온 곳
|
||||
|
||||
- 개선 작업 매뉴얼 초안(docs/improvement 폴더 11개 파일, 2026-11-05, 브랜치 docs/improvement-manual, PR #6. main에 없다)을 백엔드 `docs/work/`와 같은 모양으로 옮겼다(2026-11-08). 초안은 main에 들어가지 않았고, 이 폴더가 그것을 대신한다.
|
||||
- 하네스 설계: design-docs `harness/01-harness-design.md`(2026-11-07, 13절 소유자 결정). 루트 지침·훅·스킬·서브에이전트·검증 진입점·장부의 근거다.
|
||||
- 옛 루트 `CLAUDE.md`(리뷰 기준과 전체 리뷰 절차 26줄)의 내용은 [reference/review-criteria.md](reference/review-criteria.md) 1절과 [improve.md](improve.md) 4.1절로 옮겼다. 옛 3단계의 "영역별로 서브에이전트를 병렬로"는 소유자 결정 2026-11-07에 맞춰 「결과만 받는 리뷰는 서브에이전트, 문서를 커밋하는 리뷰·파일을 바꾸는 위임은 하위 세션」으로 고쳤다. 옛 2단계의 손으로 적은 게이트 목록은 merge 단계 전부로 바꿨다(1105/12-03).
|
||||
- `SPEC.md` 「공통 완료 기준」 9개를 [improve.md](improve.md) 5절로 옮겼다. 문서 체계 정리가 `SPEC.md`를 이력으로 옮길 수 있게 하려는 것이다(프론트 정리 프로그램의 총괄 결정, 2026-11-07).
|
||||
|
||||
### 1.1 초안 장 → 이 폴더
|
||||
|
||||
| 초안 | 옮긴 곳 | 바꾼 것 |
|
||||
| --- | --- | --- |
|
||||
| `README.md`(정본 표, 읽는 순서, 결정 M-1~M-10) | [README.md](README.md), 결정은 [reference/decisions.md](reference/decisions.md) | M-1(위치 docs/improvement)은 `docs/work/`로 대체. M-3(§1 링크로 검사 범위에 넣음), M-4(지워도 되는 목록에 넣지 않음), M-8(repo 밖 문서는 코드 표기)은 그대로 규칙이 됐다. M-10(`AGENTS.md`는 추적하지 않는 사본)은 소유자 결정 2026-11-07로 뒤집혔다: `AGENTS.md`가 정본이다 |
|
||||
| `01-procedures.md` | [improve.md](improve.md) 3·4절 | 스킬 표, 여섯 작업 종류의 단계와 완료 기준 |
|
||||
| `02-review-criteria.md` | [reference/review-criteria.md](reference/review-criteria.md) | 28개 관점 표의 대표 발견 열은 이 문서 3절로 |
|
||||
| `03-folder-module-structure.md`, `04-code-structure.md` | [reference/structure.md](reference/structure.md) | 한 문서로 합침 |
|
||||
| `05-test-structure.md` | [reference/testing.md](reference/testing.md) | |
|
||||
| `06-performance.md` | [reference/performance.md](reference/performance.md) | 1106 D9(예산 206,848 B)를 더함 |
|
||||
| `07-verification-gates.md` | [reference/gates.md](reference/gates.md), [operate.md](operate.md) 4.1·4.2절 | 7절 소유자 환경의 손 절차는 `scripts/verify.sh`로 바뀌었다. desktop runner(`/tmp/claude-gates/run-merge-stage.sh`)는 스크립트가 대신한다 |
|
||||
| `08-decisions-records.md` | [reference/decisions.md](reference/decisions.md) | 열린 결정 대기를 1106 기준으로 갱신(D8·D11 더함, D4·D5는 1106 README 7절에 없음) |
|
||||
| `09-working-method.md` | [delegate.md](delegate.md), 멈춤 기준은 [improve.md](improve.md) 4.5절 | 「총괄이 자주 한 실수」는 delegate·improve 「자주 하는 실수」로 |
|
||||
| `appendix-defect-patterns.md` | [reference/defect-patterns.md](reference/defect-patterns.md) | 번호를 다시 매김(4절). 1106 대표 발견을 더함 |
|
||||
|
||||
## 2. 규칙과 사건
|
||||
|
||||
| 규칙(이 매뉴얼) | 사건 | 출처 |
|
||||
| --- | --- | --- |
|
||||
| merge 판정은 stage 전부를 CI env로(`gates.md` 3절) | 고른 스크립트 23개 통과라고 보고했지만 merge 게이트 셋이 실패. `CI=true` 없이 14개 통과 뒤 넣자 005·008·020 실패 | 1103 README 10.5·14.5절, 1103/11-08, 1105/12-03 |
|
||||
| 리뷰 중 실행은 한 번(`delegate.md` 4.2절) | 영역 리뷰어 16개가 각자 desktop에서 실행해 잠금 줄 30여 건, 32건 취소 | 1105 README 11.4·11.5절 |
|
||||
| 다시 돌려 통과한 것은 통과가 아니다(`gates.md` 3절) | FE-GATE-008 "세 번째 실행에서 통과"의 두 실패가 모두 테스트 결함 | 1103/11-09, 1103/11-10, 1103 README 14.5절 12~14회차 |
|
||||
| 부하 탓으로 닫지 않는다(`testing.md` 5절) | 부하 탓으로 적었던 두 실패가 모두 테스트 결함 | 1103 README 14.7절 정정 두 줄 |
|
||||
| "고침"을 믿지 않는다(`improve.md` 4.5절) | 1103 조치의 "고침" 13건이 다음 라운드에서 "일부"로 정정 | 1105 README 3.1절 |
|
||||
| 수정이 새로 가정하는 것(`structure.md` 11절) | 1105 새 발견 48건 중 22건이 지난 수정에서 나옴. 1106 diff 리뷰의 Medium 2건도 그 라운드 수정이 만든 회귀 | 1105 README 4절 끝, 1105 README 6절 원인 5, 1106 README 16.7절 |
|
||||
| 템플릿 원래 상태 밖에서도(`improve.md` 4.2절 6단계) | 기능 추가·확장 지점 채움·객체 셋 이상에서 다시 결함 | 1105 README 6절 원인 1, 1103/12-01, 1105/09-01, 1105/14-01, 1103/05-01, 1105/16-04 |
|
||||
| release 단계 게이트도 돌린다(`gates.md` 2절) | lab 게이트 회귀가 147커밋 동안 아무 게이트에도 안 걸림 | 1103/15-01, 1103 README 5절 원인 2 |
|
||||
| 짝 사실은 코드까지(`structure.md` 8절) | 판정 표를 백엔드 계약 문서만으로 정해 High | 1103/03-01, 1103 README 10.5절 |
|
||||
| 지울 때 지키던 것을 찾는다(`structure.md` 9절) | V2 삭제 때 지운 검사·테스트가 지키던 동작을 놓침 | 1103/07-01, 1103/10-04 |
|
||||
| 지워도 되는 문서를 코드가 읽지 않는다(`structure.md` 4절) | 테스트가 리뷰 문서를 열어 제거 드릴 셋을 깨뜨림 | `tests/unit/deletable-history-documents.test.ts` 머리말 |
|
||||
| 드릴 복사 목록은 하나(`structure.md` 12절) | 복사 목록에 `README.md`·`CHANGELOG.md`가 없어 드릴 넷 중 셋이 항상 실패 | 1103/02-06 |
|
||||
| 경로를 백틱 밖으로 옮기지 않는다(`docs-writing.md` 4절) | 참조 기능 경로 26줄을 백틱 밖으로 옮긴 것이 검사 약화로 기록 | 1105/14-03 |
|
||||
| `npm run` 금지(`gates.md` 2절) | 제거 드릴을 `npm run`으로 돌려 모든 검사가 `Unknown command` | 1103 README 10.4절 |
|
||||
| 임시 worktree의 `pnpm verify:documentation`(`delegate.md` 9절) | pnpm이 재설치를 시도하다 TTY 없음으로 멈춰 결과 무효 | 1105 README 11.5절 |
|
||||
| FE-GATE-013 desktop 기록법(`gates.md` 3절) | ssh 셸에서 user namespace가 막혀 provider 테스트 18건 실패 | 1105/12-01, 1105 README 11.1절, 1106 README 1절 |
|
||||
| 대조 허용치 < 여유(`performance.md` 5절) | 허용 1%(약 2 KB) > 남은 여유 1,873 B | 1105/15-02 |
|
||||
| 예산을 올리는 것은 결정(`performance.md` 5절) | 초기 파일 수 26 → 32, 초기 JS 204,800 → 206,848 B | 1103 README 14.6절 #4, 1105 README 16.2절 D7, 1106 README 16.2절 D9 |
|
||||
| 기준선은 합친 끝에서 다시 잰다(`delegate.md` 4.2절) | 브랜치마다 맞던 초기 JS 기록이 합친 빌드에서 허용치를 넘음 | 1106 README 16.3절 |
|
||||
| 빠른 계층 quarantine 없음(`testing.md` 5절) | 소유자 결정 2026-11-03 | 1101 README 14절 |
|
||||
|
||||
## 3. 28개 관점의 지난 대표 발견
|
||||
|
||||
[reference/review-criteria.md](reference/review-criteria.md) 5절 표의 관점마다 대표 발견이다.
|
||||
|
||||
| # | 대표 발견 | # | 대표 발견 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 1103/03-01 | 15 | 1103/13-03 |
|
||||
| 2 | 0929/12-03 | 16 | 1103/13-03 |
|
||||
| 3 | 1103/12-01, 1105/09-01 | 17 | 1105/07-01, 1105/16-02 |
|
||||
| 4 | 1103 README 14.6절(매뉴얼만으로 기능 추가 재실험) | 18 | 1105/13-02 |
|
||||
| 5 | 1105/13-01, 1105/12-01 | 19 | 1103/11-07, 1103/11-08 |
|
||||
| 6 | 1105/01-01 | 20 | 1105/16-04 |
|
||||
| 7 | 1105/13-01 | 21 | 1105/12-01, 1105/09-01 |
|
||||
| 8 | 1105/12-01 | 22 | 1103/04-01 |
|
||||
| 9 | 1103/14-01, 1105/14-01 | 23 | 1105/01-02 |
|
||||
| 10 | 1103/10-02, 1103/05-01 | 24 | 1105/04-02 |
|
||||
| 11 | 1103/05-01 | 25 | 1105/16-01 |
|
||||
| 12 | 1103/05-01, 1105/12-04 | 26 | 1105/13-02 |
|
||||
| 13 | 1105/15-02 | 27 | 1105/14-01 |
|
||||
| 14 | 1103/15-01 | 28 | 1105/02-02 |
|
||||
|
||||
등급 판정 예(review-criteria.md 3절)의 출처: High·P1은 0929/03-03(상향), 1103/03-01, 1103/01-01. Medium·P1은 1103/02-06, 1103/12-01, 1103/15-01, 1105/09-01, 1105/12-01, 1105/13-01. Medium·P2는 0929/03-03 남은 부분. 헷갈리는 경우 표의 출처: 게이트가 항상 실패(1103/02-06, 1105/12-01, 1105/13-01), PASS 뒤 실패(1105/12-01, 1103/11-04), 문서가 코드와 다름(1103/14-02), 손 사본이 아직 같음(1103 README 5절 원인 4), 이미 다름(1105/01-02), 원래 상태에서만 맞음(1105/09-01).
|
||||
|
||||
## 4. 결함 패턴의 옛 번호
|
||||
|
||||
초안 부록의 `P-NN` → 지금 ID. 초안 장을 인용한 리뷰 문서·커밋이 있으면 이 표로 찾는다.
|
||||
|
||||
| 옛 | 지금 | 옛 | 지금 | 옛 | 지금 | 옛 | 지금 |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| P-01 | G1 | P-13 | T1 | P-25 | G12 | P-37 | C10 |
|
||||
| P-02 | G2 | P-14 | S3 | P-26 | G13 | P-38 | C11 |
|
||||
| P-03 | S1 | P-15 | T2 | P-27 | G14 | P-39 | S4 |
|
||||
| P-04 | S2 | P-16 | T3 | P-28 | C1 | P-40 | S5 |
|
||||
| P-05 | G3 | P-17 | T4 | P-29 | C2 | P-41 | S6 |
|
||||
| P-06 | G4 | P-18 | T5 | P-30 | C3 | P-42 | W1 |
|
||||
| P-07 | G5 | P-19 | T6 | P-31 | C4 | P-43 | W2 |
|
||||
| P-08 | G6 | P-20 | T7 | P-32 | C5 | P-44 | W3 |
|
||||
| P-09 | G7 | P-21 | T8 | P-33 | C6 | P-45 | W4 |
|
||||
| P-10 | G8 | P-22 | T9 | P-34 | C7 | P-46 | B1 |
|
||||
| P-11 | G9 | P-23 | T10 | P-35 | C8 | P-47 | B2 |
|
||||
| P-12 | G10 | P-24 | G11 | P-36 | C9 | P-48, P-49 | B3, B4 |
|
||||
|
||||
## 5. 하네스 적용 기록 (2026-11-08)
|
||||
|
||||
- 새 세션이 처음 읽는 지침(루트 `AGENTS.md` + `CLAUDE.md`)의 전후 크기와 장부 줄은 `docs/ledger/estimates.jsonl`의 task `fe-c-harness`와 그 PR 본문에 있다.
|
||||
- 편집 훅의 경계 알림(N3)은 적용 시점 `src/` 377개 파일(import 1,161개)에서 알림 0건이었다(거짓 양성 0). 규칙 파일을 그대로 읽어 정규식으로 판정하므로, 규칙이 바뀌면 훅도 따라간다. 정본은 `check:architecture`다.
|
||||
@@ -0,0 +1,150 @@
|
||||
# 개선 — 리뷰, 결함 수정, 리팩터링, 성능, 구조, 테스트 구조
|
||||
|
||||
이미 있는 코드를 평가하거나 고치는 일의 절차다. 핵심은 하나다: 리뷰 → 수정 → 다음 라운드 리뷰를 새 High 0·새 P1 0·merge 게이트 전부 통과까지 돌고, 그 라운드의 Medium·Low를 고친 뒤 멈춘다(4.5절).
|
||||
|
||||
## 1. 언제 쓰나
|
||||
|
||||
| 지금 상태 | 작업 |
|
||||
| --- | --- |
|
||||
| 무엇이 틀렸는지 아직 모른다 | 리뷰 |
|
||||
| 계약(지원 범위, 현재 계약 문서, 게이트, 생성 명령, 짝 계약)과 다른 동작이 확인됐다 | 결함 수정 |
|
||||
| 동작은 맞는데 구조 비용이 크다 | 리팩터링 |
|
||||
| 같은 조건에서 두 번 이상 잰 숫자가 예산을 넘거나 회귀했다 | 성능 최적화 |
|
||||
| 최상위 `src/` 폴더, adapter 그룹, 기능·context 경계, import 규칙이 바뀐다 | 구조 변경 |
|
||||
| 테스트가 주장을 증명하지 못하거나 가끔 떨어진다 | 테스트 구조 개선 |
|
||||
|
||||
- 새 기능은 [new-feature.md](new-feature.md)다. 고치기 전에 소유자 결정이 필요하면 [research-design.md](research-design.md)가 먼저다.
|
||||
|
||||
## 2. 받아야 할 것
|
||||
|
||||
- 리뷰: 범위(전체 / 영역 / PR / 커밋 범위 `<base>..<head>`), 기준 커밋.
|
||||
- 수정: 고칠 발견 목록(ID, 위치)과 리뷰 문서 경로. 발견 ID 없이 고치지 않는다. 그 고침이 무엇을 막는지 아무도 모르게 된다.
|
||||
- 공통: 브랜치, 커밋 허용 여부, 돌릴 게이트. 그 발견에 필요한 소유자 결정이 [reference/decisions.md](reference/decisions.md)에도 brief에도 없으면 그 발견만 멈추고 묻는다.
|
||||
|
||||
## 3. 크기와 사고 순서
|
||||
|
||||
- 보통 중간이다: 영역 리뷰 하나, 수정 묶음 하나. 큼: 전체 리뷰, 구조 변경, 공개 포트·계약을 바꾸는 수정. 큰 일은 설계와 대안을 먼저 적는다(리뷰 가이드 41절의 일곱 질문).
|
||||
- 선행 사례는 둘이다: 같은 원인이 남은 다른 자리, 그리고 [reference/defect-patterns.md](reference/defect-patterns.md)의 같은 모양. 리뷰 전에 그 표를 훑는다.
|
||||
- 스킬은 소유자 규칙이다(리뷰·수정에 스킬을 쓴다). 불렀다는 사실보다 그 스킬의 기준으로 무엇을 봤는지가 증거다.
|
||||
|
||||
| 작업 | 절차 스킬 | 영역 스킬(바뀌는 경계에 맞춰) |
|
||||
| --- | --- | --- |
|
||||
| 리뷰 | `superpowers:requesting-code-review` | `clean-architecture`, `codebase-design`, `security-and-hardening`, `performance-optimization`, `playwright-best-practices`, `frontend-ui-engineering`, `doubt-driven-development` |
|
||||
| 리뷰 결과를 받아 고칠 때 | `superpowers:receiving-code-review` | — |
|
||||
| 결함 수정 | `superpowers:systematic-debugging` → `superpowers:test-driven-development` | 바뀌는 경계의 영역 스킬 |
|
||||
| 리팩터링 | `refactor`, `codebase-design` | `vercel-composition-patterns` |
|
||||
| 성능 | `performance-optimization` | `vercel-react-best-practices`, 에이전트 `web-performance-auditor` |
|
||||
| 구조 변경 | `superpowers:brainstorming` → `superpowers:writing-plans` | `clean-architecture` |
|
||||
| 테스트 구조 | `superpowers:test-driven-development` | `playwright-best-practices` |
|
||||
|
||||
## 4. 절차
|
||||
|
||||
### 4.1 리뷰
|
||||
|
||||
1. 범위를 고정한다: 기준 커밋, 브랜치, 확인 시점, 노트북 worktree와 desktop이 깨끗한지. 전체 리뷰면 리뷰 가이드 0.1절 전제 표를 채운다. 이 repo의 고정 전제는 루트 `AGENTS.md` 첫 문단과 꼭 지킬 것 1·2다. 요청량·데이터량 목표가 없으니 그 칸은 "기능 수 증가 축과 번들·lab 예산으로 판정"으로 적는다.
|
||||
2. 게이트를 한 번 돌린다: `VERIFY_SNAPSHOT=1 scripts/verify.sh merge`와 `scripts/verify.sh documentation`. 손으로 적은 명령 목록을 돌리지 않는다(merge 게이트 일부가 빠진 사건이 있다).
|
||||
3. 결과를 함께 읽는다. desktop 로그 폴더(`/tmp/claude-gates/<로그 이름>/`)의 게이트 로그와 `snapshot/`(artifacts·dist·test-results 사본)을 모든 리뷰어가 읽는다. 리뷰어마다 다시 돌리지 않는다([delegate.md](delegate.md) 4.2절).
|
||||
4. 영역을 나눈다. 가장 최근 `docs/reviews/*-maturity-review/README.md`의 영역 표를 다시 쓴다. 영역마다 서브에이전트 하나(결과만 받음) 또는 하위 세션 하나(문서를 커밋함).
|
||||
5. 영역 문서는 「지난 발견 재판정」부터 쓴다. 지난 라운드가 "고침"이라 한 것도 코드로 다시 본다. 코드는 들어왔지만 완료 기준 실행이 없으면 "일부"다.
|
||||
6. 더 필요한 실험은 목록으로 낸다(ID, 명령, env, 시간 상한, 변이 패치). 총괄이 모아 같은 명령은 한 번만, 실험마다 작업 폴더를 되돌리며 일괄로 돌린다.
|
||||
7. 발견을 [reference/review-criteria.md](reference/review-criteria.md) 양식으로 적는다. 같은 결함을 두 영역이 적으면 색인에서 하나로 합치고 「합친 중복」 표에 남긴다.
|
||||
8. 총괄이 High 이상과 새 P1을 코드에서 직접 다시 읽거나 실행해 확인하고, 재확인 칸에 그 사실을 적는다.
|
||||
9. README에 범위, 28개 관점 판정표, 최종 요약, 발견 색인을 쓴다(양식 review-criteria.md 7절). 총괄 자신의 실수도 적는다.
|
||||
|
||||
- PR·diff 리뷰는 바뀐 파일의 영역만 읽는다. 게이트는 2단계대로 한 번 돌린다(멈춤 판정에 merge 단계 전부가 필요하다). 범위의 base는 직전 리뷰(diff 리뷰 포함)가 본 범위의 끝 커밋, head는 맡긴 쪽이 정한 커밋(없으면 fetch한 `origin/main`)이고 둘을 머리말에 적는다. 판정 체계·양식·ID 체계(`NN-MM`)는 같고, 수정 라운드의 diff 리뷰는 그 라운드 README 「조치」 절 아래 절로 적는다.
|
||||
- 리뷰 중에 코드를 고치지 않는다. 의심 결함은 별도 worktree의 임시 테스트로 확인하고 그 코드는 리뷰 문서나 공유 노트에만 남긴다. 리뷰 문서는 리뷰 시점 기록이다. 고친 뒤에도 영역 문서를 고치지 않고, 처리 결과는 같은 README의 「조치」 절에 적는다.
|
||||
|
||||
### 4.2 결함 수정
|
||||
|
||||
1. 원인 경로를 확인한다. 증상이 아니라 원인을 적는다. 발견의 「완료 기준」 칸을 읽는다. 완료 기준의 기준은 그 칸이다.
|
||||
2. RED: 재현 테스트를 먼저 쓰고 수정 전 코드에서 실패하는 것을 실행으로 본다. 브라우저 없이 재현할 수 없으면 fake·fixture로 조건을 만든다. 리뷰가 Playwright 검증을 요구하면 spec 하나를 더한다.
|
||||
- RED가 없는 수정: 문서를 동작에 맞추면 문서의 주장을 단언하는 임시 테스트가 기준 커밋에서 실패하는 것을 RED로 쓴다. 테스트로 옮길 수 없으면 "RED 없음 — 이유"와 대신한 증거를 적는다.
|
||||
3. 검출력이 문제였던 발견(변이 생존)은 리뷰에 적힌 변이를 다시 넣어 새 테스트가 실패하는지 본다([reference/testing.md](reference/testing.md) 3절).
|
||||
4. GREEN: 가장 작은 수정으로 통과를 본다. 공개 포트는 추가만 한다. 공용 로직은 `src/adapters/platform/`이나 `src/contracts/`에 둔다.
|
||||
5. 같은 원인의 다른 자리를 찾는다. 결과 불명 쓰기의 재전송 입구처럼 하나를 막으면 다른 입구에서 다시 나온다([reference/structure.md](reference/structure.md) 6절).
|
||||
6. 템플릿 원래 상태 밖에서도 돌린다: 기능을 더한 상태(`create:feature`), 제품 확장 지점을 채운 상태, 입력·객체가 셋 이상. 원래 상태로만 확인한 수정이 다음 라운드에 다시 결함이 됐다.
|
||||
7. 수정이 새로 가정하는 것을 커밋 본문 「위험·한계」에 적는다(8절 「새로 가정하는 것」).
|
||||
8. 그 동작을 설명하는 문서를 같은 변경에서 고친다. adapter 파일을 더하거나 옮기면 `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다. 다운스트림에 보이는 변경은 `CHANGELOG.md` 미출시 절에 적는다.
|
||||
9. 커밋 전 게이트를 돌린다([reference/gates.md](reference/gates.md) 2절).
|
||||
|
||||
### 4.3 리팩터링, 성능, 구조, 테스트 구조
|
||||
|
||||
- 리팩터링: 지킬 동작·타입·실패·진단을 "보존 조건"으로 먼저 적는다(리뷰 가이드 36.3·39.9절). 기존 테스트가 그 조건을 지키는지 보고, 못 지키면 테스트부터 더한다. 바꾼 뒤 같은 테스트가 그대로 통과해야 한다. 테스트를 고쳐야 통과하면 동작이 바뀐 것이다. 소비자 없는 확장 지점은 지우지 않고, 갈라진 복사본은 하나로 합친다.
|
||||
- 성능: [reference/performance.md](reference/performance.md)의 조건으로 기준선을 다시 잰다 → 원인을 좁힌다(waterfall·청크 목록·trace) → 변경 하나 → 대조군(바꾸기 전 커밋)과 같은 세션에서 다시 잰다. 지난 측정값을 기준선으로 쓰지 않는다.
|
||||
- 구조 변경: 설계와 대안을 먼저 적고, [reference/structure.md](reference/structure.md) 3절 「바꿀 때 같이 고칠 것」을 같은 커밋에서 고친 뒤 제거 드릴(FE-GATE-020)을 돌린다.
|
||||
- 테스트 구조: [reference/testing.md](reference/testing.md). 가끔 떨어지는 테스트는 재시도·timeout으로 덮지 않고 반복 실행 → 실패 기록 → 결정적 재현 → 수정 → 변이 순서로 원인을 찾는다.
|
||||
|
||||
### 4.4 수정 라운드와 묶음
|
||||
|
||||
- 통합 브랜치 `fix/maturity-review-<YYYY-MM-DD>`(리뷰 날짜)를 만들고, 영역별 수정은 각자 worktree의 브랜치에서 한다. 다른 수정에 기대는 묶음은 그 수정이 합쳐진 뒤 시작한다. CHANGELOG·문서는 마지막에 한 세션이 다시 쓴다.
|
||||
- 총괄이 브랜치를 `--no-ff`로 하나씩 합치고, 합칠 때마다 커밋 전 게이트를 돌린다. 합친 뒤에만 생긴 실패는 README 「통합에서 생긴 것」에 적는다. 합친 트리에서 merge 단계를 돌리고 회차별 결과를 표로 남긴다.
|
||||
- 큰 라운드는 작은 PR로 나눈다. 자기완결적인 변경 하나에 PR 하나(대략 100줄, 1,000줄이면 너무 크다). 리팩터링과 동작 변경은 PR을 나눈다. 병합은 소유자가 한다. 라운드 사이에 새 기능이나 큰 구조 변경을 넣지 않는다(발견 수가 줄어드는지 볼 수 없다).
|
||||
|
||||
### 4.5 멈춤 기준 — 이 repo는 하나다
|
||||
|
||||
아래 셋을 모두 채운 라운드에서 멈춘다(소유자 결정 2026-11-04).
|
||||
|
||||
1. 그 라운드의 새 High 0.
|
||||
2. 그 라운드의 새 P1 0.
|
||||
3. merge 단계 게이트 전부 통과([reference/gates.md](reference/gates.md) 3절 방법). FE-GATE-013을 어떻게 셀지는 결정 대기라, 그동안은 같은 절의 문구로 보고하고 멈출지는 소유자가 정한다.
|
||||
|
||||
- 채워도 바로 끝내지 않는다. 그 라운드의 Medium·Low를 고치고 멈춘다. 리뷰 발견은 Low까지 고쳐 "남은 문제 0"으로 보고한다. 못 고치는 것은 결정 대기로 남긴다(형식 [reference/decisions.md](reference/decisions.md) 3절). 이유 없는 이월("나중에", "범위 밖")은 남기지 않는다.
|
||||
- 마지막 Medium·Low 수정은 다음 리뷰를 받지 않는다. 그래서 그 수정도 4.2절 6단계와 merge 판정을 그대로 거친다. 짝 백엔드는 "발견 0까지 확인 리뷰"를 쓴다. 두 기준을 맞추지 않는다(소유자 결정 2026-11-05 「각자 유지」).
|
||||
- 2026-11-03 리뷰의 수정 라운드 뒤로 세 라운드를 더 돌아도 닿지 않으면 멈추고, 왜 수렴하지 않는지 소유자에게 보고한다. 라운드는 전체 리뷰 한 번이다(diff 리뷰는 세지 않는다). 2026-11-05·06 리뷰가 그 첫째·둘째다.
|
||||
- 수정 결과의 "고침"은 확정이 아니다. 다음 리뷰가 ID별로 다시 판정한다. 보고에도 "다음 리뷰에서 재판정"이라고 적는다.
|
||||
|
||||
## 5. 완료 기준
|
||||
|
||||
- 리뷰: 모든 발견이 양식이고 성격·심각도·우선순위·통제·증거가 따로 있다. 지난 발견 전부의 지금 상태가 표 하나에 있다. 미검증 목록과 확인 방법, 결정이 필요한 항목마다 선택지와 결정할 사람이 있다.
|
||||
- 결함 수정(모든 발견에 공통):
|
||||
1. 동작을 바꾸면 RED → GREEN이 실행으로 있다. 없으면 "RED 없음 — 이유"와 대신한 증거가 있다.
|
||||
2. 검출력이 문제였던 발견은 변이를 다시 넣어 새 테스트가 실패한다.
|
||||
3. 커밋 전 검사(package script)가 통과한다: `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema`.
|
||||
4. 묶음 끝과 통합 때는 더해서 `check:ci`, `check:adapter-inventory`, `verify:documentation`, `test:sample-removal`, `build`가 통과한다.
|
||||
5. adapter 파일을 더하거나 옮겼으면 INVENTORY를 같은 커밋에서 고쳤다.
|
||||
6. 공용 로직은 kernel이나 `src/contracts/`에 있고 새 파일 단위 예외가 없다.
|
||||
7. 공개 포트는 추가만 했다. 깼으면 결정 표와 BREAKING 커밋이 있다.
|
||||
8. 논리 변경 하나에 커밋 하나, 메시지에 발견 ID, 바꾼 파일만 stage했다.
|
||||
9. 문서 요구는 문서의 각 주장이 코드 위치를 가리키는 것으로 확인했다.
|
||||
- 발견별 상태가 「고침 / 일부 / 결정 대기」 중 하나이고, 리뷰 가이드 35.6절의 다섯 연결(원래 위험, 바꾼 코드, 그 위험을 잡는 검증, 검증한 버전·환경·결과, 남은 제한)이 있다.
|
||||
- 리팩터링: 테스트 변경 없이 커밋 전 검사가 통과한다. 줄어든 이해 비용을 한 문장으로 말할 수 있다.
|
||||
- 성능: `check:bundle`(FE-GATE-012)과 `test:performance`(FE-GATE-026)가 통과하고, 전후 차이가 측정 잡음보다 크다(잡음 크기를 함께 적는다).
|
||||
- 구조 변경: `check:architecture`, `check:adapter-inventory`, `verify:documentation`, FE-GATE-020이 통과한다. merge 가능을 말하려면 merge 단계 전부가 통과했다.
|
||||
- 테스트 구조: 변이나 결정적 재현이 고친 뒤 기대대로 실패·통과하고, 반복 실행 실패 0과 횟수가 있다.
|
||||
|
||||
## 6. 하지 말 것
|
||||
|
||||
- 리뷰 중에 코드를 고치지 않는다.
|
||||
- 지난 라운드의 실행 결과나 다른 세션이 낸 "통과"를 현재 증거로 쓰지 않는다. 바뀐 커밋에서 다시 돌린다.
|
||||
- 정한 결정을 결함으로 다시 올리지 않는다. 전제가 틀렸다는 새 증거가 있을 때만 근거와 함께 다시 연다.
|
||||
- 범위 밖 결함을 고치지 않는다. 버리지도 않는다. 보고의 「범위 밖에서 본 것」에 위치와 함께 적는다. 같은 결함을 여러 번 세지 않는다.
|
||||
- 게이트 기준(문턱, 예산, 기준선, skip·only)을 낮춰 통과시키지 않는다. 문서 검사를 피하려고 경로를 백틱 밖으로 옮기지 않는다.
|
||||
- 짝 백엔드 repo에 쓰지 않는다. 백엔드가 바꿔야 할 것은 "백엔드에 넘길 것"으로 적는다.
|
||||
|
||||
## 7. 막혔을 때
|
||||
|
||||
- 고치는 법이 공개 동작(배럴 표면, 런타임 설정 키, 짝 계약, 파생 프로젝트 동작)을 바꾸면 고치기 전에 멈추고 묻는다. 형식은 [README](README.md) 5절이다.
|
||||
- RED를 만들 수 없으면(실제 브라우저·호스트 권한이 필요하다, 기계에 따라 통과한다) 그 사실과 이유를 보고하고 그 발견만 멈춘다.
|
||||
- 같은 파일·장치에서 결함이 두 라운드 연속 나오면, 다음은 수정이 아니라 [research-design.md](research-design.md)로 "이 장치가 필요한가"를 먼저 본다.
|
||||
|
||||
## 8. 보고 형식
|
||||
|
||||
[README](README.md) 6절에 더해, 고친 발견마다 아래 칸을 쓴다. 리뷰 README의 「조치」 표에 그대로 옮길 수 있게 쓴다.
|
||||
|
||||
| 칸 | 적을 것 |
|
||||
| --- | --- |
|
||||
| 발견 | ID와 한 줄 내용 |
|
||||
| 상태 | 고침 / 일부(남은 것) / 결정 대기(이유·선택지·결정할 사람) |
|
||||
| RED·GREEN | 수정 전 실패한 테스트와 수정 뒤 통과, 로그 경로. 없으면 "RED 없음 — 이유" |
|
||||
| 검증 | 명령, 테스트 수, rc, 실행 위치(desktop), env(CI env인지), 로그 경로 |
|
||||
| 새로 가정하는 것 | 빈 제품 파일, CI env 없음, 객체 하나, 기능 0개처럼 이 변경이 새로 기대는 상태와, 그 가정이 깨지는 구성에서 돌렸는지 |
|
||||
| 약해진 검사 | 이 변경이 다른 검사를 약하게 했는가(없으면 없음) |
|
||||
| 범위 밖에서 본 것 | 위치와 내용. 고치지 않았다 |
|
||||
|
||||
## 9. 자주 하는 실수
|
||||
|
||||
- 게이트 목록을 지난 라운드에서 가져온다. `scripts/verify.sh merge`로 stage 전부를 돌린다.
|
||||
- 다시 돌려 통과한 결과를 "통과"로 쓴다. 실패한 회차를 적고 원인을 찾는다.
|
||||
- 지운 코드의 실행 동작만 옮기고, 그 코드를 읽던 검사·테스트가 지키던 것을 놓친다. 지우기 전에 `git grep`으로 읽는 곳을 찾는다.
|
||||
- 짝 백엔드 사실을 문서만 보고 옮긴다. 생성기와 폼까지 코드를 따라간다.
|
||||
- "부하 탓"으로 닫는다. 부하를 낮춘 재현과 결정적 재현으로 확인하기 전에는 원인이 아니다.
|
||||
@@ -0,0 +1,78 @@
|
||||
# 새 기능 — 화면과 그 화면이 쓰는 API 호출 만들기
|
||||
|
||||
이 템플릿(또는 복사한 프로젝트)에 기능 하나를 더하는 일의 절차다. 만드는 순서와 단계별 판단 기준의 정본은 `docs/manual/`이다. 이 playbook은 그것을 다시 쓰지 않고, 크기·받을 것·완료 기준·보고만 정한다.
|
||||
|
||||
## 1. 언제 쓰나
|
||||
|
||||
- 새 기능 폴더 `src/features/<id>/`를 만든다(라우트, 페이지, API 계약, application input, HTTP adapter 기여).
|
||||
- 짝 백엔드의 `new-feature.sh`로 만든 API에 화면을 붙인다.
|
||||
- 있는 기능을 고치는 일은 이 playbook이 아니라 [improve.md](improve.md)다. 기능 폴더 밖(플랫폼, adapter, 셸)을 바꿔야 기능을 만들 수 있으면 그 부분은 improve 구조 변경이고 크기가 큼이다.
|
||||
|
||||
## 2. 받아야 할 것
|
||||
|
||||
- 기능 ID(케밥 표기, 40자 이하, 기존 기능·context ID와 겹치지 않음)와 속할 context(기존 / 새로).
|
||||
- 짝 백엔드 쪽 사실: 경로(`<base>`의 복수형 규칙은 `docs/manual/reference/create-feature.md`), 작성 API가 있는지(`--with-create`), 재전송될 수 있는 쓰기인지(`--keyed`는 백엔드 create가 멱등성 executor 뒤에 있을 때만), 인증 모드.
|
||||
- 계약 패키지 신원(`--package`·`--digest`·`--revision`). 없으면 자리표시자 신원으로 만들고, 출시 전에 채운다.
|
||||
- 커밋 허용 여부와 브랜치.
|
||||
|
||||
## 3. 크기와 사고 순서
|
||||
|
||||
- 생성 명령 출력 그대로 기능 하나를 채우면 중간이다(기능 폴더 하나 안). 생성 명령이 함께 만드는 새 context(`--context` 없이 생기는 `<base>-context`)도 중간이다. 템플릿에는 context가 없어 첫 기능은 늘 이렇게 시작한다.
|
||||
- 큼: context를 손으로 만들거나 기존 context 경계를 바꾸는 일, 기능 폴더 밖 파일(`docs/manual/03-outside-feature-folder.md`)을 생성 명령 밖에서 고치는 일, 짝 백엔드와 새 계약(오류 code, 응답 모양)을 맞추는 일, 초기 JS 예산을 올려야 하는 일. 큰 일은 [research-design.md](research-design.md)로 소유자 검토를 먼저 받는다.
|
||||
- 선행 사례: `docs/manual/reference/patterns.md`(기능 개발 패턴과 예제 위치), 매뉴얼 안의 코드 조각. 템플릿에는 복사해 볼 기능 샘플이 없다. 다른 기능 폴더를 복사해 이름을 바꾸지 않는다.
|
||||
- 스킬: `new-feature`(이 절차의 실행 순서표). 매뉴얼 01장이 단계마다 「쓸 스킬」을 적는다. 동작은 `superpowers:test-driven-development`로 테스트를 먼저 쓴다.
|
||||
|
||||
## 4. 절차
|
||||
|
||||
1. `docs/manual/README.md`와 `docs/manual/01-add-a-feature.md` 0단계(경계와 소속)를 읽고 크기를 정한다.
|
||||
2. 뼈대: `corepack pnpm create:feature <id>`(필요하면 `--context`, `--with-create`, `--keyed`). 소유자 환경에서는 pnpm을 노트북에서 돌리지 않으니 desktop에서 만들고 만든 파일을 돌려받는다: `scripts/verify.sh script create:feature --apply-back -- <id> --with-create`. 노트북 작업 트리에 생긴 파일을 `git status`로 본다([operate.md](operate.md) 4.1절).
|
||||
3. 출력의 `Next:` 목록을 보고에 옮긴다. 그 목록이 돌릴 명령과 다시 쓸 기록(초기 JS 기록 등)이다.
|
||||
4. 매뉴얼 01장 2~10단계로 뼈대를 실제 기능으로 바꾼다. 막히면 02장 결정표(context 경계, 계약 출처, 재시도 의미, 결과 불명, 인증, 페이지 템플릿, 파일 업로드), 폴더 밖 파일은 03장, 짝 백엔드 인증은 04장.
|
||||
5. import는 기능 폴더 안 계층 규칙과 꼭 지킬 것 1~3을 지킨다. 편집 훅의 경계 알림(N3)이 나오면 그 자리에서 고친다. 다른 기능을 import하지 않는다. adapter는 기능의 `adapters/`나 배럴로만 닿는다.
|
||||
6. 테스트는 `tests/features/<id>/`에 둔다(기능과 함께 지워진다). 결과 불명 쓰기와 재전송 입구는 `docs/manual/02-decision-tables.md` 3·4절 기준으로 테스트한다.
|
||||
7. 기준선과 증거: 초기 JS 기록(`config/scale/feature-shape-ceilings.json`의 `initialJavascript`)은 생성 출력 `Next:`의 명령으로 다시 쓰고 같은 커밋에 넣는다. 손으로 고치지 않는다. desktop에서 돌려 돌려받는다: `scripts/verify.sh exec --apply-back -- node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`. 예산(`config/performance/budgets.json`)을 넘으면 올리기 전에 멈추고 묻는다(꼭 지킬 것 4).
|
||||
8. 제거 확인: 매뉴얼 01장 11단계. 기능을 지운 사본이 게이트를 통과해야 한다: `scripts/verify.sh script test:sample-removal -- --feature=<id>`. merge 단계의 FE-GATE-020은 목록에 적은 기능과 새로 생성한 기능만 지우므로 이 기능의 제거를 대신 보여 주지 않는다.
|
||||
9. desktop에서 merge 단계와 lab 게이트를 돌린다: `scripts/verify.sh merge`, `scripts/verify.sh gate FE-GATE-026`(새 기능은 lazy 라우트를 더하므로 늘 돌린다). 결과를 보고 싶으면 서브에이전트 `arch-reviewer`(경계 리뷰)와 `verify-app`(desktop에서 앱을 띄워 그 라우트를 연다)에 맡긴다.
|
||||
|
||||
## 5. 완료 기준
|
||||
|
||||
- 생성 명령으로 시작했고, 템플릿 소유 파일을 생성 명령 밖에서 고치지 않았다(고쳤으면 큼으로 올려 결정을 받았다).
|
||||
- 동작마다 테스트가 있고 RED → GREEN을 봤다.
|
||||
- 초기 JS 기록이 빌드와 맞는다(`test:unit` 안의 대조).
|
||||
- `scripts/verify.sh merge`가 통과했고(FE-GATE-013은 [reference/gates.md](reference/gates.md) 3절 문구로 적었다) FE-GATE-026도 통과했다.
|
||||
- 이 기능을 지운 사본이 통과한다(`test:sample-removal -- --feature=<id>`).
|
||||
- 다운스트림에 보이는 변경(공개 포트, 생성 명령 출력)이 있으면 `CHANGELOG.md` 미출시 절에 적었다.
|
||||
|
||||
## 6. 하지 말 것
|
||||
|
||||
- 다른 기능 폴더를 복사해 이름을 바꾸지 않는다. 접두어 없는 전역 ID, 복사된 계약 출처, 기능 밖 테스트 의존으로 막힌다.
|
||||
- 기능끼리 import하지 않는다. 공용이 필요하면 `src/contracts/`(공유 어휘)나 kernel로 옮기는 일을 따로 묻는다.
|
||||
- 예산·기준선·기능 모양 상한을 올려 통과시키지 않는다.
|
||||
- 플랫폼을 지키는 테스트를 기능에 묶지 않는다. 기능 테스트가 지워도 되는 문서(`docs/reviews/` 등)를 읽지 않는다.
|
||||
- 짝 백엔드 repo를 고치지 않는다. 백엔드가 바꿔야 할 것은 보고에 "백엔드에 넘길 것"으로 적는다.
|
||||
|
||||
## 7. 막혔을 때
|
||||
|
||||
- 생성 명령이 거부하면 `docs/manual/reference/errors.md`에서 메시지를 찾는다. 고칠 파일이 적혀 있다.
|
||||
- 짝 백엔드 응답 모양·오류 code가 문서와 다르면 코드(백엔드 생성기, 이 repo의 `src/adapters/http/backend-envelope.ts`)까지 따라가 사실을 적고 묻는다. 문서만 보고 판정 표를 정하지 않는다.
|
||||
- 기능 폴더 밖을 고쳐야만 되면 거기서 멈추고 [README](README.md) 5절 형식으로 묻는다.
|
||||
- brief가 매뉴얼 예시 이름(`invoice-feature` 등)을 기능 ID로 주면 그대로 만들지 말고 묻는다. 템플릿 시험(`tests/unit/manual-code-blocks.test.ts`)이 저장소 사본에 그 이름으로 기능을 만든다.
|
||||
|
||||
## 8. 보고 형식
|
||||
|
||||
[README](README.md) 6절에 더해 적는다.
|
||||
|
||||
| 칸 | 적을 것 |
|
||||
| --- | --- |
|
||||
| 기능 | ID, context, 생성 명령(인자 그대로) |
|
||||
| 생성 출력 `Next:` | 목록과 각 항목을 했는지 |
|
||||
| 바꾼 기록 | 초기 JS 기록·기능 모양 기록의 전후 숫자와 다시 쓴 명령 |
|
||||
| 검증 | `scripts/verify.sh merge`의 게이트별 rc, 로그 경로, 제거 드릴 결과 |
|
||||
| 백엔드에 넘길 것 | 있으면 |
|
||||
|
||||
## 9. 자주 하는 실수
|
||||
|
||||
- 한 테스트 파일을 `pnpm exec vitest run <file>`로 돌려 생성물 import 오류로 실패한다. `node scripts/run-vitest.ts run <file>`을 쓴다.
|
||||
- 초기 JS 기록을 다시 쓰지 않아 `test:unit`이 기록이 낡았다고 실패한다. `Next:`의 명령으로 다시 쓴다.
|
||||
- `CI=true` 없이 돌려 통과하고 CI에서 떨어진다. `scripts/verify.sh`로 돌린다.
|
||||
- 매뉴얼 예시 기능 이름을 그대로 써서 템플릿 테스트의 글자와 부딪친다. 제품 이름을 쓴다.
|
||||
@@ -0,0 +1,100 @@
|
||||
# 운영 — 게이트 실행, desktop 검증, 릴리스, 파생 프로젝트
|
||||
|
||||
게이트를 어디서 어떻게 돌리고 결과를 어떻게 남기는지, 릴리스와 파생 프로젝트 동기화를 어떻게 하는지의 절차다. 무엇을 돌릴지는 [reference/gates.md](reference/gates.md)다.
|
||||
|
||||
## 1. 언제 쓰나
|
||||
|
||||
- 게이트·테스트·빌드·브라우저 실행을 돌리거나 그 결과를 기록할 때. 다른 playbook의 검증 단계도 실행은 이 절차를 쓴다.
|
||||
- merge 가능을 말하기 전, 릴리스 단계(`release`·`production`)를 돌릴 때.
|
||||
- 파생 프로젝트(이 템플릿을 복사해 쓰는 repo)에 템플릿 변경을 넘길 때.
|
||||
|
||||
## 2. 받아야 할 것
|
||||
|
||||
- 돌릴 트리: 브랜치와 커밋, 또는 지금 작업 트리(커밋 안 된 변경 포함). `scripts/verify.sh`는 지금 트리를 패치로 옮기므로 push가 필요 없다.
|
||||
- 돌릴 단계나 게이트 ID(`config/ci/gates.json`).
|
||||
- 로그 이름(기본은 `<브랜치>-<단계>`). 보고에 쓸 이름을 정해 `--log`로 준다.
|
||||
|
||||
## 3. 크기와 사고 순서
|
||||
|
||||
- 게이트를 돌리고 기록하는 일은 보통 작음이다. 1단계(무엇을 증명하려고 돌리나 한 줄)와 6단계(rc와 로그)만 남긴다.
|
||||
- 게이트·workflow·`config/ci/` 자체를 바꾸는 일은 큼이다([README](README.md) 2절). 그것은 [improve.md](improve.md) 구조 변경으로 하고, 거짓 통과 막기([reference/gates.md](reference/gates.md) 6절)를 같이 본다.
|
||||
- 스킬: `desktop-gates`(이 절차의 실행 순서표), 완료 주장 전 `superpowers:verification-before-completion`.
|
||||
|
||||
## 4. 절차
|
||||
|
||||
### 4.1 실행 위치 — 소유자 환경
|
||||
|
||||
- **pnpm·게이트·브라우저·빌드는 노트북에서 돌리지 않는다.** 노트북은 다른 작업과 함께 돌아 전체 테스트에 죽는다(소유자 결정 2026-11-05). desktop(`ssh desktop`, 12코어 31 GB)에서 돌린다. 노트북에서는 git·읽기·`python3` 표준 라이브러리 검사(`scripts/verify.sh docs`, `scripts/verify.sh hooks`)만 한다.
|
||||
- **진입점은 `scripts/verify.sh`다.** desktop 단계는 스크립트가 알아서 옮긴다.
|
||||
|
||||
```bash
|
||||
scripts/verify.sh merge --log fe-feature-x
|
||||
```
|
||||
|
||||
하는 일: 노트북의 지금 트리(커밋 안 된 변경 포함)를 기준 커밋(`origin/main`과 갈라진 곳)에 대한 패치로 만들어 desktop에 보낸다 → desktop 공유 checkout(`~/workspace/clean-architecture-frontend-template`)에서 새 worktree를 기준 커밋으로 만든다 → 패치를 얹고 트리 해시가 노트북과 같은지 본다 → 그 트리를 커밋 하나로 만들어(깨끗한 HEAD, 훅을 거치지 않는 `commit-tree`) → `CI=true corepack pnpm install --frozen-lockfile --offline` → `flock /tmp/claude-gates/heavy.lock` 아래 같은 단계를 돈다 → `/tmp/claude-gates/<로그 이름>/`에 `summary.txt`, 단계별 로그, `gate-artifacts/`(게이트 로그 사본), `status-after.txt`(게이트가 추적 파일을 바꿨는지)를 남긴다 → worktree를 지운다.
|
||||
- **공유 checkout을 건드리지 않는다.** desktop의 그 checkout은 다른 세션도 쓴다. 브랜치를 바꾸지 않고, `stash`를 건드리지 않는다. 어쩔 수 없이 그 checkout에서 돌려야 하면 잠금 안에서 바꾸고 끝나면 처음 브랜치로 되돌린 뒤 `git status`가 비었는지 본다.
|
||||
- **잠금.** 무거운 실행은 하나씩 돈다. 백엔드 세션도 같은 desktop에서 같은 잠금을 쓴다. 다른 세션이 잠금을 쥐고 있으면 기다리고, 기다리는 동안 다른 일을 한다. 오래 걸리는 단계는 background로 띄우고 끝나기를 한 번 기다린다(짧은 간격으로 확인하지 않는다).
|
||||
- **CI env.** `scripts/verify.sh`는 게이트를 workflow와 같은 꼴의 env로 돌린다: `CI=true`, `VITE_COMMIT_SHA`(그 worktree의 HEAD), `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE`(`@sha256:` digest 꼴). `CI=true`를 빼면 CI에서만 나는 실패를 놓친다([reference/gates.md](reference/gates.md) 4절).
|
||||
- **desktop의 FE-GATE-013.** ssh 셸에서 비특권 user namespace가 막혀 `test:system`의 provider 테스트가 호스트 원인으로 실패한다. 시스템 설정은 바꾸지 않는다. `scripts/verify.sh parts FE-GATE-013`으로 그 게이트의 명령을 하나씩 끝까지 돌려, 실패가 호스트 전제 하나뿐인지와 뒤 명령의 결과를 함께 적는다. 이 게이트를 멈춤 기준에서 어떻게 셀지는 결정 대기다([reference/decisions.md](reference/decisions.md)).
|
||||
- **노트북에서 꼭 돌려야 하면** 노트북 checkout이 아니라 깨끗한 복제본(`git clone --no-hardlinks`, 그 뒤 `corepack pnpm install --frozen-lockfile --offline`)에서 돌리고 vite가 들어가는 게이트에 `CHOKIDAR_USEPOLLING=1`을 준다. 노트북 checkout의 `.claude/worktrees/`가 `test:system`의 repo 복사와 vite 파일 감시를 깨뜨린다.
|
||||
- **desktop에서 파일을 만드는 명령**(생성 명령, 기준선 다시 쓰기)은 `--apply-back`으로 결과를 노트북 작업 트리에 받는다: `scripts/verify.sh script create:feature --apply-back -- <id>`, `scripts/verify.sh exec --apply-back -- <명령…>`. 바뀐 파일은 언제나 로그 폴더의 `changes.patch`에도 남는다.
|
||||
- **한 테스트 파일**도 desktop에서: `scripts/verify.sh exec -- node scripts/run-vitest.ts run <파일>`.
|
||||
- desktop의 비대화형 ssh에는 node가 PATH에 없다. 스크립트가 `~/.nvm/versions/node/v<.nvmrc>/bin`을 앞에 붙인다. 손으로 돌릴 때도 같다.
|
||||
|
||||
### 4.2 게이트 실행과 기록
|
||||
|
||||
1. 단계를 고른다([reference/gates.md](reference/gates.md) 2절). merge 가능을 말하려면 `scripts/verify.sh merge`다. 게이트 하나는 `scripts/verify.sh gate FE-GATE-005`, package script 몇 개는 `scripts/verify.sh script verify:documentation`.
|
||||
2. 돌리기 전에 `ssh desktop uptime`으로 부하를 본다. 높으면 기록에 적는다.
|
||||
3. 돌린다. stage는 실패가 있어도 끝까지 돌고 게이트마다 rc와 초를 적는다(`ci:gate`는 한 게이트 안에서는 첫 실패에서 멈춘다. 뒤 명령이 필요하면 `parts`).
|
||||
4. 기록한다: 단계·게이트, rc, 시간, 핵심 숫자(테스트 수, 초기 JS 바이트, 파일 수), 실행 직전 부하, 대상 트리 해시(`summary.txt` 첫 줄), 로그 경로. 숫자는 로그에서 옮긴다.
|
||||
5. 실패하면 기준 커밋에서도 돌려 이번 변경 몫인지 가린다. 다시 돌려 통과한 결과를 "통과"로 쓰지 않는다. 실패한 회차를 그대로 적고 원인을 찾는다. 고친 뒤에는 같은 게이트를 연속으로 여러 번 돌려 실패 0과 횟수를 적는다.
|
||||
6. `status-after.txt`가 비어 있지 않으면 게이트가 추적 파일을 바꾼 것이다. 결함으로 적는다.
|
||||
|
||||
### 4.3 릴리스
|
||||
|
||||
- 릴리스 단계는 `scripts/verify.sh release`, 운영 승격 조건은 `scripts/verify.sh production`이다. 단계와 게이트는 `config/ci/gates.json`의 `stages`가 정한다. release는 merge가 통과한 트리에서만 의미가 있다(`needs`).
|
||||
- 라우트 로딩·청크·초기 화면, 공급망·release 경로를 바꿨으면 merge만으로 부족하다. release 단계 게이트가 지키는 것에 닿으면 그 게이트도 돌린다.
|
||||
- 운영 복구 절차는 `docs/runbooks/`와 `docs/operations/`가 정본이다. 런북 게이트(FE-GATE-021~025)는 production 단계다.
|
||||
- 태그 push·Gitea Actions 켜기·branch protection은 소유자가 한다.
|
||||
|
||||
### 4.4 파생 프로젝트에 템플릿 변경 넘기기
|
||||
|
||||
- 소유자 환경의 파생 프로젝트는 둘이고 받는 법이 다르다. 하나는 이력을 공유하지 않아 기준점을 지정한 3-way 병합을 일반 커밋 하나로 남기고, 다른 하나는 이력을 공유해 merge로 받는다. 각 repo의 기준점 파일과 지난 동기화 기록을 먼저 읽는다.
|
||||
- 템플릿 쪽 안내는 루트 `README.md` 「Updating a copied project」와 `CHANGELOG.md`의 미출시·버전 절이다. 다운스트림에 보이는 변경과 BREAKING 단계는 CHANGELOG에 적는다.
|
||||
- 루트 `AGENTS.md`·`CLAUDE.md`, `.claude/`, `docs/work/`는 템플릿 계약이라 파생 프로젝트도 받는다(소유자 결정 2026-11-07). 예전처럼 `CLAUDE.md`를 걸러 내지 않는다. 파생 프로젝트가 바꿀 것은 이 문서 4.1절과 [delegate.md](delegate.md) 4.3절(소유자 환경)뿐이다. `docs/ledger/estimates.jsonl`은 줄을 비우고 자기 줄을 쌓는다.
|
||||
- 파생 프로젝트 repo에는 쓰지 않는다(그 일은 그 repo의 세션이 한다). 템플릿 쪽에서는 이행 안내와 확인 방법만 준다.
|
||||
|
||||
## 5. 완료 기준
|
||||
|
||||
- 돌린 단계마다 rc, 시간, 부하, 트리 해시, 로그 경로가 기록에 있다. 숫자는 로그에서 옮겼다.
|
||||
- merge 가능을 말했으면 merge 단계 전부가 `CI=true` env로 통과했고(FE-GATE-013은 4.1절대로 적었다), 트리 해시가 PR head 트리와 같다.
|
||||
- desktop 공유 checkout의 브랜치와 `git status`가 실행 전과 같고, 만든 worktree가 지워졌다.
|
||||
|
||||
## 6. 하지 말 것
|
||||
|
||||
- 노트북 checkout에서 pnpm·게이트·브라우저를 돌리지 않는다.
|
||||
- desktop 공유 checkout의 브랜치를 바꾼 채 두거나 `stash`를 건드리지 않는다.
|
||||
- 게이트를 골라 돌린 결과로 merge 가능을 말하지 않는다. `CI=true`를 빼고 돌린 결과로도 말하지 않는다.
|
||||
- 다시 돌려 통과한 결과를 "통과"로 쓰지 않는다. 시스템 설정(inotify 한도, user namespace)을 바꾸지 않는다.
|
||||
- desktop에 env를 준 실행을 실제 CI 러너 결과로 쓰지 않는다. 증거에 「실제 CI 미검증」을 함께 적는다.
|
||||
|
||||
## 7. 막혔을 때
|
||||
|
||||
- `scripts/verify.sh`가 rc=4(원격 준비 실패)를 내면 메시지를 본다: 기준 커밋이 desktop에 없으면 그 커밋을 push하거나 brief를 준 쪽에 묻는다. 트리 해시가 다르면 패치가 줄바꿈·권한을 잃은 것이다. 손으로 고치지 말고 원인을 적어 묻는다.
|
||||
- 잠금이 오래 풀리지 않으면 누가 쥐고 있는지(`ssh desktop 'ps -ef | grep flock'`) 적고 기다린다. 남의 실행을 죽이지 않는다.
|
||||
- 호스트 전제(브라우저, 글꼴, bwrap)로 실패하면 게이트 결함인지 호스트 문제인지 가린 뒤, 호스트 문제면 그 사실과 증거를 적고 소유자에게 묻는다.
|
||||
|
||||
## 8. 보고 형식
|
||||
|
||||
[README](README.md) 6절의 「확인」 줄을 이 표로 쓴다.
|
||||
|
||||
| 단계·게이트 | rc | 시간 | 핵심 숫자 | 부하 | 트리 | 로그 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| merge / FE-GATE-005 | 0 | 134s | unit 3,090 통과 | 1.0 | `summary.txt` 첫 줄 | `/tmp/claude-gates/<이름>/FE-GATE-005.log` |
|
||||
|
||||
## 9. 자주 하는 실수
|
||||
|
||||
- 노트북 checkout에서 한 파일 테스트쯤은 괜찮다고 돌린다. 한 파일도 desktop에서 `scripts/verify.sh script`나 `ssh desktop`으로 돌린다.
|
||||
- 한 테스트 파일을 `pnpm exec vitest run <file>`로 돌려 생성물이 없어 실패한다. `node scripts/run-vitest.ts run <file>`을 쓴다.
|
||||
- 캐시된 산출물(`dist/`, `artifacts/`)이 남은 checkout에서 돌려 다른 실행의 결과를 읽는다. `scripts/verify.sh`의 새 worktree를 쓴다.
|
||||
- 게이트 로그 대신 `ci:gate`의 마지막 줄만 옮긴다. `gate-artifacts/FE-GATE-0NN.txt`에서 숫자를 옮긴다.
|
||||
@@ -0,0 +1,91 @@
|
||||
# 결정 색인
|
||||
|
||||
결정은 **한 번 하고, 한 곳에 적고, 다시 묻지 않는다.** 이 repo의 결정은 리뷰 README·`SPEC.md`(2026-09-25 수정 라운드의 기본값)·결정 기록에 흩어져 있다. 이 문서는 그 결정들의 **색인**이다. 원문은 옮기지 않고 출처만 단다(원문을 옮겨 쓰면 갈라진 복사본이 된다).
|
||||
|
||||
```text
|
||||
리뷰가 선택지를 낸다 → 리뷰 README 「결정이 필요한 것」
|
||||
소유자가 고른다 → 같은 README 「조치」의 결정 표 (또는 SPEC.md 「결정」, 결정 기록)
|
||||
이 색인에 한 줄 → 다음 작업은 여기부터 찾는다
|
||||
```
|
||||
|
||||
## 1. 결정을 다시 묻지 않는 규칙
|
||||
|
||||
1. 결정이 필요해 보이면 먼저 2절 색인과 가장 최근 리뷰 README의 결정 절을 찾는다.
|
||||
2. 이미 정했으면 따른다. 상황이 바뀌어 뒤집어야 하면 새 결정으로 적고 옛 결정을 가리킨다. 옛 기록을 고치지 않는다.
|
||||
3. 정한 적이 없으면 3절 형식으로 결정 대기를 만든다. 스스로 정하지 않는다. 다만 소유자가 위임한 범위 안에서는 총괄이 정하고 그 위임 문장을 출처로 적는다.
|
||||
4. 다시 열 수 있는 것은 결정의 전제가 틀렸다는 새 증거가 있을 때뿐이다. 그 증거와 재검토 조건을 함께 적는다.
|
||||
|
||||
## 2. 색인
|
||||
|
||||
「출처」의 리뷰 README는 `docs/reviews/<날짜>-maturity-review/README.md`다. 「repo 밖」은 소유자 지시가 세션 기록과 작업 메모에만 있던 것이다. 이 매뉴얼의 해당 절이 그 규칙의 repo 안 기록이다.
|
||||
|
||||
### 2.1 작업 방식 (소유자 지시)
|
||||
|
||||
| # | 날짜 | 결정 | 출처 | 이 매뉴얼 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| O-1 | 2026-09-16 | 이 repo는 템플릿이다. 소비자 없는 코드와 빈 레지스트리는 확장 지점이지 죽은 코드가 아니다 | 옛 루트 `CLAUDE.md` 리뷰 전제 | `AGENTS.md` 첫 문단, `structure.md` 2절 |
|
||||
| O-2 | 2026-09-16 | adapter 배럴을 공개 경계로 만든다(배럴 폐지안 기각) | 옛 `CLAUDE.md`, `docs/architecture/layers.md` | 꼭 지킬 것 1 |
|
||||
| O-3 | 2026-09-16 | 갈라진 IndexedDB 복사본은 kernel(`src/adapters/platform/`)로 모은다. 새 파일 단위 예외를 만들지 않는다 | 옛 `CLAUDE.md`, `SPEC.md` 공통 완료 기준 6 | 꼭 지킬 것 2 |
|
||||
| O-4 | 2026-11-01 | 커밋·PR은 design-docs `conventions/commit-and-pr.md`를 따른다. AI 꼬리말은 어디에도 넣지 않는다 | repo 밖 | `docs/work/README.md` 4절 |
|
||||
| O-5 | 2026-11-03 | merge 가능 판정은 `ci:gate`로 merge 단계 전부를 workflow env로 돌려서 한다. 고른 스크립트 목록으로 판정하지 않는다 | repo 밖. 실행 기록은 1103 README 14.5절 | `gates.md` 3절 |
|
||||
| O-6 | 2026-11-03~05 | 리뷰 발견은 Low까지 고쳐 "남은 문제 0"으로 보고한다. 못 고치는 것은 결정 대기로 이유와 함께 남긴다 | repo 밖 | `improve.md` 4.5절 |
|
||||
| O-7 | 2026-11-03~05 | 리뷰·수정에 스킬을 쓴다 | repo 밖 | `improve.md` 3절 |
|
||||
| O-8 | 2026-11-03~05 | 총괄 세션은 하위 세션에 일을 맡긴다 | repo 밖 | `delegate.md` |
|
||||
| O-9 | 2026-11-04 | 수정 → 리뷰를 반복한다. 새 High 0·새 P1 0·merge 단계 통과면 그 라운드의 Medium·Low를 고치고 멈춘다. 1103 수정 라운드 뒤로 세 라운드를 더 돌아도 닿지 않으면 멈추고 이유를 보고한다 | repo 밖 | `improve.md` 4.5절 |
|
||||
| O-10 | 2026-11-05 | 테스트·게이트는 노트북에서 돌리지 않고 desktop에서 돌린다 | repo 밖 | `operate.md` 4.1절 |
|
||||
| O-11 | 2026-11-05 | 리뷰 중 실행은 게이트를 한 번 돌리고 산출물을 함께 읽는다. 추가 실험은 목록으로 모아 같은 명령은 한 번만, 실험마다 작업 폴더를 되돌리며 일괄로. 작업 폴더 복제본을 늘려 해결하지 않는다 | 1105 README 11.4절 | `delegate.md` 4.2절 |
|
||||
| O-12 | 2026-11-05 | 백엔드와 다른 종료 조건을 각자 유지한다(「각자 유지」). 백엔드는 발견 0까지 확인 리뷰를 반복하고, 프론트는 O-9대로 한다 | repo 밖(백엔드 총괄 전달) | `improve.md` 4.5절 |
|
||||
| O-13 | 상시 | 짝 백엔드 repo는 읽기만 한다. stage·commit·push하지 않는다 | 1103 README 14.2절 D1 「이유」 | `delegate.md` 4.3절 |
|
||||
| O-14 | 상시 | 리뷰에서는 코드를 고치지 않는다 | 옛 `CLAUDE.md` | `review-criteria.md` 1절 |
|
||||
| O-15 | 2026-11-05 | 수정 결과의 「고침」을 그대로 믿지 않는다. 다음 리뷰에서 ID별로 다시 판정한다 | repo 밖. 근거 사례 1105 README 3.1절 | `improve.md` 4.5절 |
|
||||
| O-16 | 2026-11-05 | 큰 라운드는 작은 PR로 나눈다(커밋 규칙 5.1절). 소유자가 PR을 merge한다 | repo 밖 | `improve.md` 4.4절 |
|
||||
| O-17 | 2026-11-07 | Claude Code 하네스를 자료(제작 책임자가 권하는 방식)대로 적용한다: 루트 `AGENTS.md` 정본(40줄 이하) + `CLAUDE.md`가 가져오기, 경로별 규칙 `.claude/rules/`, 모델이 부르는 스킬(설명에 발동 조건), repo 훅은 넛지 위주, 검증 진입점 `scripts/verify.sh`, 장부 `docs/ledger/estimates.jsonl` | design-docs `harness/01-harness-design.md` 13절 | 이 매뉴얼 전체 |
|
||||
| O-18 | 2026-11-07 | Agent 금지를 두지 않는다. 결과만 받는 일(검색, 구조 리뷰, 실행 검증, 단순화 제안)은 서브에이전트, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야 하는 위임은 하위 세션이다 | 같은 문서 13절 Q5 | `delegate.md` 4.3절 |
|
||||
| O-19 | 2026-11-07 | 루트 `AGENTS.md`·`CLAUDE.md`(와 `.claude/`, `docs/work/`)는 템플릿 계약이다. 복사한 프로젝트가 받는다. 지워도 되는 문서 목록에 넣지 않는다 | 같은 문서 13절 Q4 | `structure.md` 4절, `operate.md` 4.4절 |
|
||||
| O-20 | 2026-11-08 | 프론트 편집 훅은 노트북에서 표준 라이브러리 정적 검사만 한다. 포맷·린트·타입은 desktop `scripts/verify.sh`에서 돈다. 설계 13절 Q6(편집 훅에서 한 파일 포맷·린트)과 다른 점은 프론트 린터가 pnpm·`node_modules`를 써서 "pnpm은 desktop에서만"(O-10)과 부딪치기 때문이다 | 하네스 적용 brief(백엔드 총괄, 2026-11-08) | `scripts/hooks/README.md` |
|
||||
|
||||
### 2.2 기술 결정 (리뷰 라운드)
|
||||
|
||||
| 묶음 | 날짜 | 무엇을 정했나 | 출처 |
|
||||
| --- | --- | --- | --- |
|
||||
| 0925 수정 라운드 기본값 D-1~D-19 | 2026-09-25 | 결과 불명 intent 보관과 같은 키 재전송(D-1), 효과 분류 선택 필드(D-2), Web Lock 직렬화(D-3·D-4), 확인 못 한 판정은 `UNVERIFIED`(D-14), 문서 색인(D-16), 규모 측정은 실제 모양 기능 25·100개(D-18) 등 | `SPEC.md` 「결정」(문서 체계 정리 뒤에는 `docs/history/`로 옮겨진다) |
|
||||
| 0929 결정이 필요한 것 7건 | 2026-09-29 | 확장 지점 범위, 409 분류, `x-correlation-id`, fanout 검사, remediation 원장, cross-context kernel 예외, 리뷰 게이트 목록에 `test:system` | 0929 README |
|
||||
| 1101 결정 표 | 2026-11-03 | 확장 지점을 템플릿이 연다, design-system side effect 없음, raw mutation 입력을 공개 훅에서 뺌(BREAKING), 빠른 계층 quarantine 없음 유지, OPFS 여러 페이지 purge 등 24행 | 1101 README 14절 |
|
||||
| V2 HTTP 경로 삭제 | 2026-11-03 | HTTP 실행은 V3 하나. 지운 V2 동작의 판정 | 1101 README, 1103 README 3절 |
|
||||
| 1103 결정 D1~D6 | 2026-11-04 | 짝 업로드는 Fileserver multipart client(D1), 업무 거절은 operation 단위 `refusedBeforeWrite` code 목록(D2), 시각 테스트는 기능 영역을 가리고 찍음(D3), 접근성 e2e 응답 모양(D4), CHANGELOG는 순 변경 요약(D5), 짝 계약은 pin 파일 + 답 표 대조 + drift 검사(D6) | 1103 README 「조치」 |
|
||||
| WebKit preload 경고(1103/11-09) | 2026-11-05 | 경고 문구 하나만 무시하고 preload 사용을 세 엔진에서 직접 검사한다 | 1103 README 14.7절 |
|
||||
| 1105 결정 D7 | 2026-11-05 | 초기 JS 예산을 204,800 B에서 206,848 B로 올린다 | 1105 README 16.2절 |
|
||||
| 1106 결정 D9·D10 | 2026-11-06 | 초기 JS 예산 206,848 B를 그대로 두고 근거·되돌림 규칙을 `docs/operations/performance-evidence.md`에 둔다(D9). 결과 불명 KEYED 재전송이 쓰기 전 거절로 끝나도 훅이 결과 불명과 키를 지킨다. 재전송의 거절이 결과 불명을 푸는 것은 짝 백엔드 표의 code뿐이다(D10과 보완 둘, 판정 `src/contracts/errors.ts` `isRefusedOnEveryAttempt`) | 1106 README 16.2절 |
|
||||
| 구조·기술 결정 기록 | 2026-07-26~ | `VD-01`~(빈 번호 있음) | `docs/architecture/decisions/` |
|
||||
|
||||
## 3. 결정 대기 쓰는 법
|
||||
|
||||
못 고치는 발견은 이 형식으로 남긴다. 이 형식을 채우지 못하면 결정 대기가 아니라 미완이다.
|
||||
|
||||
| 칸 | 내용 |
|
||||
| --- | --- |
|
||||
| 번호·관련 발견 | 예: D8, 1105/12-01 |
|
||||
| 왜 고치지 못하나 | 예: 러너 전제를 바꾸는 일이라 소유자 결정이 필요하다 |
|
||||
| 선택지 | 권하는 안을 먼저. 각 안의 비용과 위험 |
|
||||
| 결정할 사람 | 프론트 소유자 / 두 repo 소유자 / 프론트 소유자 + reviewer 등 |
|
||||
| 결정 전까지 | 임시 처리와 보고 방법(예: `gates.md` 3절의 FE-GATE-013 기록 방법) |
|
||||
| 재검토 조건 | 어떤 규모·버전·계약 변화가 결론을 바꾸나 |
|
||||
|
||||
결정 표에 들어갈 것: 고른 것과 이유(무엇을 지키는지로), 버린 대안과 버린 이유, 확인한 사실 / 기록된 의도 / 추론의 구분, 재검토 조건.
|
||||
|
||||
### 3.1 지금 열린 결정 대기
|
||||
|
||||
2026-11-06 리뷰(1106) 시점이다. 다음 라운드가 닫거나 새로 열면 이 표를 고친다.
|
||||
|
||||
| 번호 | 결정 | 관련 | 결정할 사람 | 출처 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| D1 | 운영 advisory 2건(zod·react-router). zod 갱신은 초기 JS를 약 7 KB 늘린다 | 1103/13-03 | 프론트 소유자 + reviewer | 1106 README 7절 |
|
||||
| D2 | 플랫폼 구성 화면을 진단 화면으로 인정할지, 기능으로 옮기고 다시 잴지 | 1103/09-04 | 프론트 소유자 | 같음 |
|
||||
| D3 | 백엔드 생성기의 목록 GET | 1103/03-07 | 두 repo 소유자 | 같음 |
|
||||
| D8 | FE-GATE-013을 멈춤 기준에서 어떻게 셀지(호스트 제약 실패로 제외 / 다른 러너에서 통과할 때까지 미충족) | 1105/12-01 | 소유자 | 같음 |
|
||||
| D11 | 생성 기능 설치 상태의 브라우저 merge 게이트 | 1105/16-03 | 템플릿 담당 | 같음 |
|
||||
| D6(1105) | 실행 격리: 실행별 출력·빈 포트, 또는 "한 checkout 한 실행" 명시. `ci:gate` 두 실행은 아직 같은 `dist`·`artifacts/`를 쓴다 | 1105/12-04 | 프론트 소유자 | 1105 README 7절, 1106 README 2.3절 |
|
||||
|
||||
## 4. 커밋·PR
|
||||
|
||||
정본은 repo 밖 design-docs `conventions/commit-and-pr.md`다. 이 repo에서 덧붙이는 것은 [review-criteria.md](review-criteria.md) 11절(발견 ID 꼬리말, CHANGELOG 리뷰 ID, BREAKING)과 [../README.md](../README.md) 4절이다. PR 본문은 그 문서 5.3절의 칸을 쓰고 「위험과 영향」과 「검증」은 비우지 않는다. 병합은 소유자가 한다.
|
||||
@@ -0,0 +1,100 @@
|
||||
# 결함 패턴
|
||||
|
||||
2026-09-24 src 리뷰와 성숙도 리뷰 다섯 라운드(0925·0929·1101·1103·1105)에서 **같은 모양으로 두 번 이상 나온 결함**을 모았다. 리뷰 전에 이 목록을 훑으면 지난 라운드가 이미 본 모양을 빨리 알아본다. 고칠 때는 「막는 기준」 칸의 문서를 따른다. 2026-11-06 라운드(1106)는 새 패턴 없이 같은 모양(C1·C2·G2)을 다시 냈다.
|
||||
|
||||
- **ID**는 이 문서의 번호다. 영역 글자(G 게이트·CI, T 테스트, C 코드, S 구조, W 문서, B 성능·예산)와 번호. 다른 문서가 「결함 패턴 C2」처럼 가리킨다. 옛 번호(docs/improvement 초안의 `P-NN`)와의 대응은 [../evidence.md](../evidence.md) 4절이다.
|
||||
- **대표 발견**은 리뷰 ID(`MMDD/NN-MM`, `docs/reviews/<날짜>-maturity-review/`의 발견)다. 같은 발견을 두 행의 대표로 쓰지 않았다.
|
||||
- **관점**은 대표 발견들의 리뷰 문서 「관련 관점」 칸에서 많이 나온 번호다.
|
||||
- 「막는 기준」이 「없음」이면 지난 리뷰에서 일반 기준이 정해지지 않았다는 뜻이다. 그 행을 다시 보면 리뷰는 기준을 제안해야 한다.
|
||||
- Critical은 다섯 라운드 모두 0건이다. 패턴에 들지 않은 High는 0929/09-01(= 1101/09-01, 공개 API가 세션 상태 때문에 전송되지 않음) 하나다.
|
||||
|
||||
## 1. 게이트·CI·검증 절차
|
||||
|
||||
| ID | 패턴 | 모양 | 대표 발견 | 막는 기준 | 관점 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| G1 | 돌리는 게이트 목록이 stage 전체가 아니거나, 게이트가 늦은 단계에서만 돈다 | 리뷰·드릴이 손으로 적은 명령 목록을 돌려 merge 게이트 일부가 빠진다. release 단계 게이트를 아무도 안 돌린다. CI가 꺼져 있다 | 0925/12-01, 0925/12-02, 1101/15-01, 1103/12-02, 1105/12-03 | `gates.md` 2·3절, `scripts/verify.sh merge` | 21, 10, 26 |
|
||||
| G2 | 게이트·수정 확인이 템플릿 원래 상태와 작은 입력만 본다 | 기능 0개, 제품 파일이 빈 상태, 객체 0~1개에서만 맞다 | 0925/09-01, 1103/12-01, 1103/16-09, 1105/09-01, 1105/16-03 | `improve.md` 4.2절 6단계, `testing.md` 3절 | 10, 21, 25, 3, 20 |
|
||||
| G3 | workflow env에서만 나는 게이트 실패 | `CI=true`·빌드 식별값이 테스트 기대값·dev server·테스트 안 빌드로 새어 실제 CI에서만 실패 | 1103/11-06, 1103/11-07, 1103/11-08 | `gates.md` 3·4절 | 21, 10, 18, 19 |
|
||||
| G4 | 고정 출력 경로·포트·추적 파일에 쓴다 | `dist/`, `artifacts/`, 고정 포트, 커밋된 파일에 써서 한 checkout의 두 실행이 부딪히고 추적 파일이 바뀐다 | 1105/12-04, 1103/12-08, 1105/16-01, 0929/14-01, 0925/00-01 | 브라우저 테스트는 `TEST_RUN_ID`·빈 포트. `ci:gate` 두 실행은 아직 같은 경로를 쓴다(1106 README 2.3절). 실행 뒤 `git status`가 비어야 한다 | 20, 25, 12, 10 |
|
||||
| G5 | 사전 점검·앞 단계는 PASS인데 본 단계가 실패한다 | 점검이 본 단계와 다른 방법으로 확인해 PASS 뒤 원인 없는 원문 오류가 난다 | 1103/11-04, 1105/12-01, 0929/06-01, 1101/09-06 | `gates.md` 5절 | 21, 20, 8, 18 |
|
||||
| G6 | 게이트가 호스트·checkout 조건을 말없이 가정한다 | 글꼴 패키지, 옆 백엔드 checkout, user namespace를 적지도 확인하지도 않아 기계마다 결과가 다르다 | 1103/11-02, 1105/12-02, 1101/11-02 | `testing.md` 4절, `gates.md` 7절 | 21, 20, 19, 17 |
|
||||
| G7 | 거짓 PASS — 검사가 실제 대상과 비교하지 않는다 | 자기 산출물, 이전 release, 상수 `true`, 오류 화면, fixture 전용 규칙을 보고 통과한다 | 0925/11-01, 1101/13-01, 1103/11-01, 1103/12-04, 1103/13-01, 1105/11-01, 1105/06-02 | 확인 못 한 판정은 `UNVERIFIED`(0925 라운드 결정 D-14). `gates.md` 6절, `testing.md` 3절 | 21, 18, 10, 5 |
|
||||
| G8 | 정적 검사가 문자열·정규식·이름 모양으로 판정한다 | 코드 구조 대신 정규식·접두어·파일 목록으로 판정해 오탐·미탐이 난다 | 0929/08-02, 0929/07-06, 1101/12-01, 1101/12-03 | import 규칙은 그래프 규칙으로(0925 라운드 결정 D-12). 문구 검사는 ESLint 구문 규칙으로 | 21, 10, 23, 24 |
|
||||
| G9 | 검사기 자신을 지키는 음성 fixture가 없다 | 규칙을 통째로 꺼도 게이트가 통과한다. 검사기가 0개 모듈을 보고 통과한다 | 1101/12-02, 0925/12-05, 0929/11-08, 1101/14-05 | 통과 fixture와 거절 fixture를 함께(`docs/testing/taxonomy.md`). `gates.md` 8절 | 21, 10, 24 |
|
||||
| G10 | 항상 실패하거나 통과할 수 없는 게이트를 방치한다 | main에서 항상 실패하지만 CI가 꺼져 있어 아무도 막히지 않고 라운드를 넘긴다 | 0929/11-01, 1101/11-01, 0929/11-02, 1103/12-09 | 사용자 피해가 없어도 Medium·P1로 매겨 첫 묶음에 넣는다(`review-criteria.md` 3절) | 21, 10, 26 |
|
||||
| G11 | 제거 드릴이 제거와 무관하게 실패하거나 제거 뒤 상태를 안 본다 | 드릴마다 복사·제외 목록을 따로 들어 문서를 빠뜨린다. 예제를 지운 상태는 아무 게이트도 돌지 않는다 | 1103/02-06, 1103/14-04, 1103/16-02, 1105/14-01 | 복사 목록 하나(`scripts/lib/removal-fixture.ts`). `structure.md` 12절 | 27, 21, 10, 20 |
|
||||
| G12 | 게이트 출력·로그에 실패 원인이 남지 않는다 | "실패"만 남고 넘은 한도·reason·로그는 버려지거나 올라가지 않는다 | 0925/12-11, 1101/14-06, 1103/14-06, 1103/15-03, 1105/13-01 | 예산 검사는 넘은 항목·값·초과량을 출력한다. release job 로그는 실패 때도 올린다(1106 README 1절, runner 미가동이라 일부) | 8, 20, 5 |
|
||||
| G13 | 수정이 새 결함을 만든다 | 고친 커밋이 새 가정(빈 제품 파일, CI env 없음)을 들이거나 다른 검사를 약하게 한다 | 1103/11-08, 1105/09-01, 1105/09-02, 1105/14-03, 1106/16.7절 DR-01·DR-02 | `structure.md` 11절, `improve.md` 8절 「새로 가정하는 것」 | 21, 10, 3 |
|
||||
| G14 | 완료 기준을 돌리지 않고 "고침"으로 닫는다 | 코드가 들어가면 완료 기준 실행 없이 "고침"으로 적는다. 다음 라운드에 "일부"로 정정된다 | 1103/05-01, 1103/16-01, 1103/11-02, 1103/11-03 | 가이드 35.6절. `review-criteria.md` 6절, `improve.md` 4.5절 | 10, 21 |
|
||||
|
||||
## 2. 테스트
|
||||
|
||||
| ID | 패턴 | 모양 | 대표 발견 | 막는 기준 | 관점 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| T1 | 규칙을 지워도·결함을 고쳐도 테스트가 그대로 통과한다 | 보호 규칙을 지우는 변이, 판정 경계를 바꾸는 변이가 살아남는다. 커버리지 100%인 곳도 있다 | 1101/07-06, 1101/02-04, 1103/10-02, 1103/07-02, 1105/02-04, 1105/01-04 | RED 먼저, 변이 확인(`testing.md` 3절). 판정 규칙의 변이 도구는 미조치(1105/10-03) | 10, 21, 6 |
|
||||
| T2 | 단언이 대상에 닿지 않아 항상 참이다 | fixture가 비어 첫 줄에서 return하거나 전제를 만들지 않는다. 로딩 화면·fixture 자신을 검사한다 | 1101/10-01, 1101/10-02, 0925/08-05, 0925/11-05 | `testing.md` 3절. 전역 `expect.hasAssertions()`는 제안만 됐다 | 10, 21, 24 |
|
||||
| T3 | 시간·속도·준비 상태를 가정한 테스트 | 기본 대기, 짧은 상한, 실제 시계, 짧은 전이 상태 폴링에 기대 부하가 있는 호스트에서 실패한다 | 0929/10-01, 1103/10-01, 1103/11-03, 1103/11-05, 0929/11-04 | 공통 대기 기한은 `tests/setup.ts` 한 곳. `testing.md` 5절 | 10, 21, 12 |
|
||||
| T4 | 브라우저의 추정에 기댄다 | WebKit이 load 3초 뒤 한 번 하는 preload 추정에 기대 곧 쓰일 preload로 실패하고, 정말 안 쓴 preload는 놓친다 | 1103/11-09 | 추정 대신 확인하려는 사실을 직접 검사한다(`testing.md` 5절) | 10, 21 |
|
||||
| T5 | 그리는 중인 화면을 누른다 | 앱 뒤에 붙인 버튼이 렌더링 중 밀려 클릭이 닿지 않는다 | 1103/11-10 | 테스트가 붙이는 조작 요소는 고정 층에(`testing.md` 5절) | 10, 21 |
|
||||
| T6 | 테스트 대역이 실제 상대와 다르다 | 메모리 IndexedDB, fake, 백엔드 문서에서 옮긴 MSW 응답이 실제와 달라 결함을 숨긴다 | 0925/05-08, 0925/06-01, 1103/05-04, 1103/16-01, 1105/01-01 | 실제 짝 백엔드 응답으로 맞추기는 미조치(1105 README 9절) | 10, 17, 12 |
|
||||
| T7 | 플랫폼 테스트가 샘플·특정 파일·예시 이름에 묶인다 | 샘플을 지우면 테스트가 같이 사라지거나 게이트가 깨진다. 템플릿 테스트의 글자가 매뉴얼 예시 기능 이름과 부딪힌다 | 0925/14-01, 0929/10-02, 1101/16-02, 1105/10-01, 1105/16-04 | 테스트 전용 라우트와 플랫폼 소유 MSW 카탈로그(`testing.md` 2절). 탐침 이름은 예약 접두어 `typecheck-probe-*` | 27, 10, 21, 20 |
|
||||
| T8 | 빠른 계층에 느린 테스트가 섞인다 | unit에 프로세스를 띄우는 도구 테스트, 실제 시계로 기다리는 테스트가 섞이고 같은 파일을 두 번 돈다 | 1101/10-05, 1101/10-06, 1101/10-07, 1101/15-04 | 없음. `testing.md` 6절 | 14, 20, 10 |
|
||||
| T9 | 깨끗한 clone·다른 호스트에서 실패한다 | gitignore된 생성물, 기준선을 만든 CPU, 실행기가 넣는 npm 환경변수에 기댄다 | 0924 6.0절, 0925/10-01, 0925/11-03, 1101/15-05 | 한 파일 실행도 `scripts/run-vitest.ts`로. merge 판정은 깨끗한 checkout에서(`gates.md` 2·3절) | 10, 21, 20 |
|
||||
| T10 | 지우거나 바꾼 코드가 지키던 검사·테스트를 같이 잃는다 | 삭제·이름 변경이 실행 동작만 옮기고, 지운 행·테스트가 지키던 규칙은 옮기지 않는다 | 1103/07-01, 1103/10-04, 1105/04-01, 1105/10-01 | `structure.md` 9절 | 10, 21, 17 |
|
||||
|
||||
## 3. 코드
|
||||
|
||||
| ID | 패턴 | 모양 | 대표 발견 | 막는 기준 | 관점 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| C1 | 실패를 다른 종류로 분류해 복구 경로가 닫힌다 | status 하나나 표 밖 기본값으로 판정해 업무 거절·입력 오류·일시 오류·서버 장애가 뒤섞인다 | 0925/03-02, 0929/03-05, 1103/03-01, 1105/01-01, 1105/04-02, 1105/03-02, 1106/03-01 | `structure.md` 6절 | 6, 17, 8, 24 |
|
||||
| C2 | 결과 불명 쓰기를 무방비로 다시 보낸다 | 적용됐을 수 있는 쓰기를 키 없이, 새 키로 다시 보내는 입구가 남는다. 고칠 때마다 다른 입구에서 나온다 | 0925/03-01, 0929/03-01, 0929/03-03, 1103/03-03, 1103/04-01, 1105/01-02, 1105/03-01, 1106/16.8절 FR-01 | `structure.md` 6절, `docs/manual/02-decision-tables.md` 3·4절 | 6, 17, 12, 28 |
|
||||
| C3 | 오지 않을 신호를 기다리며 멈춘다 | 재시도 상태 기계가 그 상황에서 오지 않는 신호(새 online 이벤트, 예산 재충전)를 기다려 재시도도 종료도 없이 멈춘다 | 0925/04-01, 0929/04-01, 0929/04-04 | `structure.md` 7절 | 6, 28, 5 |
|
||||
| C4 | 손상 한 건이 목록·작업 전체를 멈춘다 | 행 하나가 손상되면 목록 읽기·purge·GC가 그 뒤로 계속 같은 곳에서 실패한다 | 0925/05-02, 0925/05-05, 0929/05-01, 0929/02-01 | `structure.md` 7절 | 6, 28, 11 |
|
||||
| C5 | 결과·상태를 실제와 다르게 보고한다 | 다 하지 못했는데 `COMPLETED`·`verified`·`active`를 보고한다. 겹치는 작업 사이 틈을 놓친다 | 0929/05-02, 0925/02-05, 1101/09-07, 1103/05-01, 1103/02-04 | `structure.md` 7절 | 24, 11, 12, 5 |
|
||||
| C6 | 실패가 원인·추적값을 버린다 | 서로 다른 실패를 같은 reason으로 남기거나 `traceId`·effect를 싣지 않는다. 새 모듈에서 같은 누락이 다시 생긴다 | 0925/09-04, 1101/02-05, 1103/03-05, 1103/03-06, 1105/01-03, 1105/02-01 | `structure.md` 7절 | 8, 24, 7 |
|
||||
| C7 | router base path를 무시한 URL | 하위 경로에 배포하면 `/`부터 조립한 URL이 앱 밖을 가리킨다 | 0925/13-07, 0929/06-02, 1101/06-01 | `structure.md` 10절 | 19, 18, 23 |
|
||||
| C8 | 같은 설정을 경로마다 다르게 읽는다 | 번들·빌드 스크립트·SW 빌드가 같은 설정을 다른 출처에서 읽는다 | 0925/09-02, 0925/06-10, 0929/13-02 | `structure.md` 10절 | 19, 18, 23 |
|
||||
| C9 | 여러 탭·동시 실행 경쟁 | 두 탭이 같은 저장소·구독·잠금을 건드려 진행 중 데이터를 지우거나 잠금을 무기한 쥔다 | 0925/05-01, 0925/06-02, 0925/05-07, 1103/05-02 | `structure.md` 10절, 0925 라운드 결정 D-3·D-4(Web Locks) | 12, 6, 11 |
|
||||
| C10 | 이름 하나가 여러 뜻, 뜻 하나가 여러 이름 | 같은 이름이 다른 모양·뜻을 가리키거나 한 개념을 여러 이름으로 적는다 | 0929/09-04, 1101/07-01, 1101/07-05, 1101/04-02 | `structure.md` 9절(`@deprecated` 별칭) | 24, 23, 4 |
|
||||
| C11 | 실패·복구 전이 뒤 화면이 다음 행동을 잃는다 | 한 전이에서 고친 포커스·안내를 다른 전이에 쓰지 않아 키보드 사용자가 위치를 잃거나 버튼이 무반응으로 남는다 | 1103/08-02, 1105/08-01, 1105/08-02, 1105/08-04, 1103/09-11 | `structure.md` 7절 | 1, 6, 24, 28 |
|
||||
|
||||
## 4. 구조
|
||||
|
||||
| ID | 패턴 | 모양 | 대표 발견 | 막는 기준 | 관점 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| S1 | 같은 사실을 repo 안 여러 곳에 손으로 적는다 | 스키마 메타, 레지스트리 행, 허용 키, 빌드 입력 목록을 원본과 따로 적고 대조 검사가 없다 | 1101/07-02, 0929/07-05, 1103/16-04, 1103/13-04, 1105/15-03, 1105/05-01 | `structure.md` 8절 | 23, 17, 3, 21 |
|
||||
| S2 | 두 템플릿 사이 계약을 문서 문장·손 사본으로 맞춘다 | 짝 백엔드의 프로토콜·오류 code·응답 모양·생성기 규칙을 프론트 문서·JSON·문자열로 옮기고 게이트가 어긋남을 알리지 않는다 | 1103/01-01, 1103/12-06, 1103/04-02, 1105/07-01, 1105/16-02 | `structure.md` 8절, 1103 결정 D6(pin + 답 표 대조 + drift 검사) | 17, 26, 21 |
|
||||
| S3 | 갈라진 중복 복사본 | 같은 로직·fixture·helper·port를 두 벌 이상 두고 이미 규칙이 서로 다르다 | 0924 5.1절, 0925/09-12, 0929/05-03, 1101/07-03, 1101/10-08 | 루트 `AGENTS.md` 첫 문단, `structure.md` 2·8절 | 9, 23, 22 |
|
||||
| S4 | 제품이 템플릿 소유 파일을 고쳐야 한다 | 제품마다 다른 것이 템플릿 소유 파일에만 있어 동기화마다 충돌한다 | 0929/09-02, 0929/14-03, 1103/02-01, 1103/12-07, 1105/13-02 | `structure.md` 10절. 1101 결정 「확장 지점을 템플릿이 연다」 | 3, 25, 22 |
|
||||
| S5 | 경계·kernel 예외가 실제 쓰임보다 넓다 | 예외가 필요한 것보다 넓게 열려 있거나 공유 메커니즘이 아닌 파일이 kernel 예외를 받는다 | 0925/12-07, 0929/02-06, 1101/05-04 | 꼭 지킬 것 2, `structure.md` 2절 | 2, 22, 21 |
|
||||
| S6 | 연결된 두 모듈의 약속이 어긋난다 | 모듈마다 테스트는 있지만 한쪽이 보내는 결과를 다른 쪽이 다른 뜻으로 받는다 | 0929/04-02, 1101/04-01, 1101/03-04 | 없음. `structure.md` 10절 | 17, 22, 4 |
|
||||
|
||||
## 5. 문서
|
||||
|
||||
| ID | 패턴 | 모양 | 대표 발견 | 막는 기준 | 관점 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| W1 | 문서의 주장·숫자·상태가 코드와 갈라진다 | 운영 문서가 없는 동작을 안내하거나, 손으로 적은 기준선·상한·상태가 다음 변경에서 낡는다 | 0925/06-03, 1101/01-01, 1103/15-02, 1103/14-01, 1105/04-03 | 숫자는 한 곳에 두고 문서는 그곳을 가리킨다(`performance.md` 5절). `verify:documentation`은 경로·이름만 본다(`gates.md` 7절) | 9, 5, 24, 26 |
|
||||
| W2 | `file:line`·이력 문서 참조가 낡는다 | 줄 번호 참조가 코드 변경으로 밀려 다른 코드를 가리킨다. 결정 근거를 지워도 되는 이력 문서로만 가리킨다 | 0929/02-04, 1101/05-05, 1101/14-01 | 현재 계약 문서는 이력 문서에 기대지 않는다(`structure.md` 4절). 작업 매뉴얼 본문은 이력 ID 0(`scripts/check-work-docs.py`) | 9, 4, 24 |
|
||||
| W3 | 매뉴얼·안내를 그대로 따르면 게이트가 실패한다 | 매뉴얼 예시, CHANGELOG 이행 단계, 오류 안내를 글자 그대로 따라 한 제품이 merge 게이트에서 실패한다 | 1105/14-02, 1103/14-02, 1103/09-07, 1106/14-01 | 매뉴얼 코드 조각은 `tests/unit/manual-code-blocks.test.ts`가 사본에서 돌린다. 이행 안내를 게이트가 실행하는 기준은 없음 | 20, 19, 9 |
|
||||
| W4 | CHANGELOG [계약] 표시가 실제 변경과 다르다 | [계약] 행이 실제 경로·대상과 다르거나 게이트를 좁힌 변경에 표시가 없다 | 0929/02-03, 0929/07-07, 0929/14-04, 1101/14-02 | 리뷰 ID 형식은 `tests/unit/changelog-review-ids.test.ts`. [계약] 표시 기준은 없음 | 9, 17, 26 |
|
||||
|
||||
## 6. 성능·예산
|
||||
|
||||
| ID | 패턴 | 모양 | 대표 발견 | 막는 기준 | 관점 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| B1 | 예산 여유가 바닥이고, 한도·허용치를 여유와 비교하지 않는다 | 예산을 직전 측정값으로 올려 증가를 묻는 신호가 사라진다. 대조 허용치가 남은 여유보다 크다 | 0929/05-04, 1103/15-04, 1105/15-02, 1106/15-01 | 레시피 예산은 측정값 + 3%, 3% 초과는 커밋 본문에 이유. `performance.md` 5절 | 14, 21, 13 |
|
||||
| B2 | 성능 측정이 화면 하나·조건 하나만 본다 | lab이 한 화면, `/`의 CLS, 스크롤바를 숨긴 Chromium만 재고 release 단계에서만 돈다 | 1103/15-01, 1105/15-04, 1105/15-01, 1105/15-05 | `performance.md` 2·6절 | 14, 21, 13 |
|
||||
| B3 | 필요 없는 코드가 초기 청크에 실린다 | 첫 화면에 필요 없는 코드가 배럴·side effect 판정 때문에 초기 청크에 들어간다 | 0925/13-14, 1101/08-08 | design-system side effect 없음 선언, 기능 선언과 실행부 분리 | 14, 13, 22 |
|
||||
| B4 | 작은 변경이 캐시·청크 전체를 다시 받게 한다 | build id 하나, 파일 하나 변경이 큰 청크·캐시 전체를 무효화한다 | 0929/13-03, 1101/06-05 | react-dom 청크 분리(`docs/operations/performance-evidence.md` 「build id와 재방문 캐시」) | 14, 13 |
|
||||
|
||||
## 코드에 결정을 드러내는 곳
|
||||
|
||||
- 판정 표: `src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE`, 재전송 판정 `src/contracts/errors.ts`의 `isRefusedOnEveryAttempt`.
|
||||
- 규칙 예외: `.dependency-cruiser.json` 규칙의 `comment`.
|
||||
- 예산과 그 근거: `config/performance/budgets.json`, `docs/operations/performance-evidence.md`.
|
||||
|
||||
## 패턴을 더하는 법
|
||||
|
||||
- 리뷰 라운드가 끝나면 새 반복 모양을 행으로 더한다. 한 번만 나온 것은 넣지 않는다. 같은 모양이 다시 나오면 대표 발견 칸에 더한다.
|
||||
- 번호는 다시 매기지 않는다. 새 행은 그 영역의 마지막 번호 다음을 쓴다.
|
||||
- 막는 기준이 생기면 그 기준은 `structure.md`·`testing.md`·`performance.md`·`gates.md`에 쓰고 이 표는 그 문서를 가리킨다.
|
||||
@@ -0,0 +1,113 @@
|
||||
# 게이트
|
||||
|
||||
무엇을 돌릴지는 **언제인지**로 정한다. 작업 중에는 바뀐 테스트 파일만, 커밋 전에는 검사 몇 개(package script, 2절 표), 통합 때는 몇 개를 더, merge 가능을 말할 때는 merge 단계 전부를 CI와 같은 env로 돌린다. 어디서 어떻게 돌리는지는 [../operate.md](../operate.md) 4.1절이다.
|
||||
|
||||
```text
|
||||
작업 중 바뀐 테스트 파일 하나 (2절)
|
||||
커밋 전 검사(package script) (2절)
|
||||
묶음 끝·통합 + 검사 더 (2절)
|
||||
merge 판정 scripts/verify.sh merge (stage 전부, CI env) (3절)
|
||||
리뷰 시작 merge 단계 + documentation 단계 (3절)
|
||||
```
|
||||
|
||||
게이트 ID·단계·명령의 정본은 `config/ci/gates.json`이고 설명은 `docs/operations/ci-quality-gates.md`다. 이 문서는 그 목록을 다시 적지 않는다.
|
||||
|
||||
## 1. 진입점 `scripts/verify.sh`
|
||||
|
||||
```text
|
||||
scripts/verify.sh <단계> [대상…] [--on here|<호스트>] [--log <이름>] [--dry-run]
|
||||
```
|
||||
|
||||
| 단계 | 하는 일 | 기본 위치 |
|
||||
| --- | --- | --- |
|
||||
| `docs` | 작업 매뉴얼 검사(`scripts/check-work-docs.py`)와 장부 형식 | 여기(노트북) |
|
||||
| `hooks` | repo 훅·검사기·장부 시험(`python3 -m unittest discover -s scripts/tests`) | 여기 |
|
||||
| `gate <ID>…` | 게이트마다 `corepack pnpm ci:gate <ID>`, CI env로 | desktop |
|
||||
| `parts <ID>` | 그 게이트의 명령(`commandIds`)을 하나씩 끝까지. 음성 fixture(`expect: fail`)는 정해진 종료 코드면 통과 | desktop |
|
||||
| `script <이름>… [-- 인자…]` | package script를 하나씩(예: `verify:documentation`). `--` 뒤 인자는 script가 하나일 때만 넘긴다(예: `scripts/verify.sh script test:sample-removal -- --feature=<id>`) | desktop |
|
||||
| `exec -- <명령…>` | 명령 하나. 한 테스트 파일(`node scripts/run-vitest.ts run <파일>`)이나 package script가 아닌 node 스크립트 | desktop |
|
||||
| stage id | `config/ci/gates.json` `stages`의 그 단계 `gateIds` 전부 | desktop |
|
||||
|
||||
- stage id는 계약 파일에서 읽는다. 단계가 바뀌면 스크립트를 고치지 않아도 따라간다. `--dry-run`은 돌릴 명령만 보인다.
|
||||
- 게이트·stage는 실패가 있어도 끝까지 돌고 게이트마다 `<이름> rc=<n> <초>s` 한 줄을 남긴다. 하나라도 실패하면 rc=1이다. 종료 코드 2는 사용법, 4는 원격 준비 실패다.
|
||||
- 잘못된 단계·게이트 ID는 desktop에 보내기 전에 노트북에서 거절한다.
|
||||
- desktop에서 바뀐 파일(생성 명령, 기준선 다시 쓰기의 결과)은 로그 폴더의 `changes.patch`에 남는다. `--apply-back`을 주면 그 패치를 노트북 작업 트리에 얹는다. 예: `scripts/verify.sh script create:feature --apply-back -- <id> --with-create`.
|
||||
- `VERIFY_SNAPSHOT=1`을 주면 `artifacts`·`dist`·`test-results`를 로그 폴더의 `snapshot/`에 복사한다. 리뷰어가 함께 읽는 사본이다.
|
||||
- 환경 변수로 바꿀 수 있는 것(호스트, 원격 checkout, 기준 ref, 잠금, 로그 폴더, node 경로)은 스크립트 머리 주석에 있다. 복사한 프로젝트는 [../operate.md](../operate.md) 4.1절과 이 값만 자기 환경으로 바꾼다.
|
||||
|
||||
## 2. 언제 무엇을
|
||||
|
||||
- 패키지 스크립트는 `corepack pnpm <script>`로 돌린다. `npm run`으로 돌리면 제거 드릴이 pnpm을 가정해 모든 검사가 `Unknown command`로 실패한다.
|
||||
- 테스트 파일 하나는 `node scripts/run-vitest.ts run <file>`로 돌린다. 이 runner가 `src/.generated/`를 먼저 만든다. `pnpm exec vitest run <file>`은 그 단계를 건너뛰어 import 오류로 실패하고, `pnpm test:unit -- <file>`은 범위를 좁히지 않는다(`docs/testing/taxonomy.md`).
|
||||
- 실패를 경고로 낮추지 않는다. `continue-on-error`나 경고만 내는 스크립트를 쓰지 않는다.
|
||||
|
||||
| 때 | 돌릴 것 |
|
||||
| --- | --- |
|
||||
| 작업 중 | 바뀐 테스트 파일. 브라우저 테스트는 그 spec 하나 |
|
||||
| 커밋 전(작업마다) | `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema` |
|
||||
| 묶음 끝·통합 | 위에 더해 `check:ci`, `check:adapter-inventory`, `verify:documentation`, `test:sample-removal`, `build` |
|
||||
| 브랜치를 합칠 때마다 | 커밋 전 8개. 합친 뒤에만 생긴 실패는 기록한다 |
|
||||
| merge 가능이라고 말하기 전 | `scripts/verify.sh merge`(3절) |
|
||||
| 리뷰 시작 | `scripts/verify.sh merge`와 `scripts/verify.sh documentation`(FE-GATE-017) |
|
||||
| 라우트 로딩·청크·초기 화면을 바꿀 때 | merge에 더해 `check:bundle`(FE-GATE-012)과 lab 게이트 `test:performance`(FE-GATE-026) |
|
||||
| 공급망·release 경로를 바꿀 때 | `scripts/verify.sh release` |
|
||||
| 작업 매뉴얼·훅을 바꿀 때 | 노트북 `scripts/verify.sh docs`, `scripts/verify.sh hooks` |
|
||||
|
||||
release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회귀가 147커밋 동안 아무 게이트에도 걸리지 않은 일이 있다. 바꾼 것이 release 단계 게이트가 지키는 것에 닿으면 그 게이트도 돌린다.
|
||||
|
||||
## 3. merge 가능 판정
|
||||
|
||||
"merge 가능"은 다음 방법으로만 말한다(소유자 지시 2026-11-03). 고른 스크립트 목록이 다 통과했다는 것은 근거가 아니다. 스크립트를 골라 "23개 통과"라고 보고했지만 merge 게이트 셋이 실패하던 일이 있다.
|
||||
|
||||
1. **대상:** `config/ci/gates.json`의 `stages` 중 `merge`의 `gateIds` 전부.
|
||||
2. **명령:** 게이트마다 `corepack pnpm ci:gate <ID>`. workflow도 같은 명령을 쓴다. `scripts/verify.sh merge`가 그것을 돈다.
|
||||
3. **env:** workflow 전역 env와 같은 꼴(`CI=true`, `VITE_COMMIT_SHA` 40자리, `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE` digest). `CI=true`를 빼지 않는다. 빼고 "통과"라고 했다가, 넣자 FE-GATE-005·008·020이 실패한 일이 있다. `SOURCE_DATE_EPOCH`는 `ci:gate`가 HEAD에서 만든다.
|
||||
4. **작업 폴더:** 깨끗한 checkout. `scripts/verify.sh`의 desktop worktree가 그것이다. 노트북 checkout은 `.claude/worktrees/`를 품고 있어 `test:system`의 repo 복사와 vite 파일 감시가 깨진다.
|
||||
5. **한 게이트 안의 명령:** `ci:gate`는 그 게이트의 명령 중 첫 실패에서 멈춘다. 뒤 명령의 결과가 필요하면 `scripts/verify.sh parts <ID>`로 돌린다.
|
||||
6. **기록:** 게이트마다 결과·시간·핵심 숫자(테스트 수, 초기 JS 바이트, 파일 수)와 실행 시점의 부하를 표로 남긴다. 게이트 로그는 `artifacts/quality/gates/`의 `FE-GATE-0NN.txt`에 쌓이고, `scripts/verify.sh`가 desktop 로그 폴더의 `gate-artifacts/`로 복사한다. 실패를 고칠 때마다 다시 돌리고 회차를 남긴다.
|
||||
|
||||
**가끔 떨어지는 게이트.** 다시 돌려 통과시킨 결과를 "통과"로 쓰지 않는다. 실패한 회차를 그대로 적고 원인을 찾는다([testing.md](testing.md) 5절). "세 번째 실행에서 통과"로 적혔던 FE-GATE-008의 두 실패는 둘 다 테스트 결함이었다. 원인을 고친 뒤에는 같은 게이트를 연속으로 여러 번 돌려 실패 0을 적는다.
|
||||
|
||||
**desktop에서 FE-GATE-013.** ssh 셸에서 비특권 user namespace가 막혀 `bwrap --unshare-net`이 실패하고, `test:system`의 provider 테스트가 호스트 원인으로 떨어진다. 사전 점검(`scripts/check-system-test-prerequisites.ts`)은 이제 이 제한을 이름으로 대며 실패한다. 이 게이트를 멈춤 기준에서 어떻게 셀지는 결정 대기다([decisions.md](decisions.md)). 결정 전까지 merge 판정 보고는 이 문구로 쓴다: 「merge 단계 중 FE-GATE-013 밖 전부 통과, FE-GATE-013은 desktop 호스트 제약 실패(뒤 명령 결과 첨부). merge 가능 여부는 소유자가 정한다(FE-GATE-013을 멈춤 기준에서 어떻게 셀지의 결정 대기, [decisions.md](decisions.md) 3.1절)」. 뒤 명령 결과는 `scripts/verify.sh parts FE-GATE-013`으로 낸다. 시스템 설정은 바꾸지 않는다.
|
||||
|
||||
## 4. CI env에서만 나는 실패
|
||||
|
||||
로컬 env로 통과해도 workflow env에서 실패하는 결함이 반복됐다(결함 패턴 G3).
|
||||
|
||||
| 모양 | 기준 |
|
||||
| --- | --- |
|
||||
| e2e가 build id를 `"local-build"`로 고정해 workflow의 `VITE_BUILD_ID`와 어긋났다 | merge 판정은 3절 env로만 한다 |
|
||||
| workflow 전역 env의 빌드 식별값이 vitest와 dev server로 새어 merge 게이트 다섯 개가 실제 CI에서만 실패했다 | 테스트가 직접 띄우는 빌드·서버의 env는 테스트가 정한다. 테스트용 로컬 빌드 식별값은 `scripts/lib/build-environment.ts`가 한 곳에서 준다 |
|
||||
| `CI=true`가 테스트 안의 로컬 빌드까지 release 빌드로 검사되게 했다 | 같음 |
|
||||
|
||||
## 5. 검사가 PASS인데 그 뒤가 실패
|
||||
|
||||
사전 점검·준비 단계가 "통과"를 내고, 그 뒤 실제 단계가 원인 없는 원문 오류로 실패하는 결함이다(결함 패턴 G5). 예: 사전 점검이 실행 파일·cgroup·systemd bus만 보고 bwrap을 실제로 돌리지 않아 PASS 뒤 provider 테스트가 bwrap 원문 오류로 떨어졌다. git worktree에서 `.git` 때문에 실패하는 단계를 사전 점검이 PASS로 냈다.
|
||||
|
||||
기준: 사전 점검은 **본 단계가 쓰는 것과 같은 방법으로** 한 번 실행해 본다. 실패하면 원인 이름을 붙여 멈춘다. 존재 여부만 보는 점검은 PASS가 아니라 "확인 안 함"(`UNVERIFIED`)으로 적는다.
|
||||
|
||||
## 6. 게이트를 믿을 조건 — 거짓 통과 막기
|
||||
|
||||
- 검사가 실제 대상과 비교하는지 본다. 자기 산출물, 이전 release, 상수 `true`, 오류 화면, fixture 전용 규칙을 보고 통과하면 거짓 통과다(결함 패턴 G7).
|
||||
- 검사기 자신을 지키는 음성 fixture가 있어야 한다. 통제는 통과 fixture와 거절 fixture가 둘 다 있어야 검증된다(`docs/testing/taxonomy.md`). 아키텍처 검사기가 0개 모듈을 훑고 통과한 일 뒤로 `check:architecture`는 자체 그래프와 고정 fixture를 쓴다.
|
||||
- 확인하지 못한 판정은 `PASS`가 아니라 `UNVERIFIED`다. 코드에 상수 `true` 판정을 두지 않는다.
|
||||
- 게이트를 고친 뒤 그 게이트가 막던 결함을 다시 넣어(변이) 실패하는지 본다.
|
||||
- 게이트 실행 뒤 `git status`가 비어야 한다. 비지 않으면 고정 출력 경로·추적 파일 쓰기 결함이다(결함 패턴 G4).
|
||||
|
||||
## 7. 문서 검사
|
||||
|
||||
`verify:documentation`(FE-GATE-017, documentation 단계)이 문서를 검사하는 범위와 방법의 정본은 `scripts/verify-documentation-readiness.ts`와 `docs/README.md` 1절 끝 문단이다.
|
||||
|
||||
- **범위:** `docs/README.md`와 그 1절이 링크한 문서. 폴더 링크는 그 폴더 바로 아래 `.md`만 본다. 루트 `AGENTS.md`, 이 폴더와 `docs/work/`는 1절에서 링크되어 범위 안이다.
|
||||
- **보는 것:** 백틱 안의 repo 경로(`:줄` 꼬리는 떼고 본다), 셸 코드 블록과 백틱 안 명령의 경로 인자, 마크다운 링크, `corepack pnpm <script>`와 백틱 안 `<prefix>:<name>` 꼴의 package script, `FE-GATE-0NN` ID가 실제로 있는가. 설명·수치가 코드와 맞는지는 보지 않는다.
|
||||
- **예외:** git이 무시하는 생성 산출물, 복사한 프로젝트가 지운 작업 이력(루트 `README.md`의 지워도 되는 파일 표)은 없어도 된다.
|
||||
- **짝 백엔드 경로:** `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리에서 찾는다. 옆 checkout이 없거나 그 커밋이 없으면 실패가 아니라 "확인 못 함"으로 남긴다.
|
||||
- **도는 곳:** FE-GATE-017은 merge 체인 밖이다. 그러나 같은 검사가 merge 게이트 안에서도 돈다. `tests/unit/documentation-readiness.test.ts`가 문서를 복사해 검사를 돌리고(FE-GATE-005), 기능을 지우거나 더한 사본을 만드는 FE-GATE-020의 드릴도 문서를 복사해 돌린다(복사 목록은 `scripts/lib/removal-fixture.ts`). 그래서 1절 문서의 경로 하나가 틀리면 merge가 막힌다.
|
||||
- **돌리는 법:** desktop에서 `scripts/verify.sh script verify:documentation`. 설치가 끝난 worktree라 pnpm이 재설치 대기로 멈추지 않는다.
|
||||
- 작업 매뉴얼의 분량·이력 ID·뼈대는 `verify:documentation`이 보지 않는다. `scripts/verify.sh docs`가 본다.
|
||||
|
||||
## 8. 게이트·검사 스크립트를 더할 때
|
||||
|
||||
- 새 게이트·명령은 `config/ci/gates.json`에 더하고 workflow는 생성기로 다시 만든다(`check:ci`가 대조한다). 손으로 workflow만 고치지 않는다.
|
||||
- 새 검사에는 통과 fixture와 거절 fixture를 함께 둔다. 실패 메시지는 넘은 항목·잰 값·고칠 파일을 말한다.
|
||||
- 새 package script가 어느 게이트에서도 돌지 않으면 `check:ci`가 실패한다. 예외는 이유와 함께 `config/ci/ungated-scripts.json`·`config/ci/ungated-tests.json`에 둔다. 이 목록을 늘리는 것은 게이트 기준을 낮추는 일이다(꼭 지킬 것 4).
|
||||
@@ -0,0 +1,74 @@
|
||||
# 성능 기준
|
||||
|
||||
이 템플릿의 성능 목표는 **예산**이다. 요청량·데이터량 목표는 없다. 예산은 세 측정 맥락으로 나뉘고, 맥락마다 재는 곳과 막는 게이트가 다르다. 괄호 안 `결함 패턴 X0`은 [defect-patterns.md](defect-patterns.md)의 행이다.
|
||||
|
||||
```text
|
||||
번들(빌드 산출물) ── check:bundle FE-GATE-012 merge 단계 초기 JS bytes·파일 수, lazy 청크 bytes
|
||||
lab(실험실 브라우저) ── test:performance FE-GATE-026 release 단계 LCP·CLS·이름 붙은 상호작용(중앙값)
|
||||
field(운영 표본) ── field Web Vitals FE-GATE-018 field 단계 p75 LCP·CLS·INP, 28일
|
||||
```
|
||||
|
||||
숫자의 정본은 `config/performance/budgets.json`이고, 세 맥락의 계약은 `docs/operations/performance-evidence.md`다. 이 문서는 숫자를 다시 적지 않는다. **언제 재는지, 어떤 조건으로 재는지, 숫자를 고칠 때 무엇을 같이 하는지**만 정한다.
|
||||
|
||||
## 1. 정본
|
||||
|
||||
| 무엇 | 정본 |
|
||||
| --- | --- |
|
||||
| 예산 값 | `config/performance/budgets.json` |
|
||||
| 세 맥락의 계약과 측정 항목 | `docs/operations/performance-evidence.md` |
|
||||
| 번들 예산 검사 | `scripts/check-bundle.ts`(`check:bundle`) |
|
||||
| lab 측정 | `scripts/test-performance.ts`(`test:performance`), 기본값 `scripts/lib/lab-performance.ts` |
|
||||
| 템플릿 그대로의 초기 JS 기준선, 기능·context 하나당 증가량, 갱신 명령 | `docs/operations/performance-evidence.md` 「번들 예산의 기준선과 여유」 절, 기록 `config/scale/feature-shape-ceilings.json` |
|
||||
| 규모 설계와 예산의 근거 | `docs/architecture/scale-architecture.md` |
|
||||
| 측정 결과에 붙일 정보의 일반론 | 리뷰 가이드 14절 「측정 결과에 반드시 붙일 정보」 |
|
||||
|
||||
## 2. 언제 재나
|
||||
|
||||
| 바꾼 것 | 잴 것 |
|
||||
| --- | --- |
|
||||
| 라우트 로딩, dynamic import, 초기 화면, 청크 나누기(`vite.config.ts`) | `check:bundle`과 `test:performance` 둘 다 |
|
||||
| 의존성 추가·갱신 | `check:bundle`. 갱신 하나가 초기 JS를 약 7 KB 늘려 예산을 넘긴 예가 있다(zod 4.6.x) |
|
||||
| 기능 추가(`create:feature`) | 생성 명령의 `Next:` 안내대로 초기 JS 기록을 다시 쓰고 FE-GATE-005·012를 돌린다 |
|
||||
| 성능 최적화 작업 | 바꾸기 전·후를 같은 조건으로(3절) |
|
||||
|
||||
lab 게이트는 release 단계에만 있다. merge 게이트만 돌리면 lab 회귀를 모른다. 예제 화면 진입 회귀가 147커밋 동안 아무 게이트에도 걸리지 않은 일이 있다. 라우트 로딩을 건드린 커밋은 merge에 더해 `test:performance`를 돌린다.
|
||||
|
||||
## 3. 측정 조건
|
||||
|
||||
측정값에는 아래를 함께 적는다. 하나라도 빠지면 다른 측정과 비교하지 않는다.
|
||||
|
||||
| 항목 | 이 repo에서 |
|
||||
| --- | --- |
|
||||
| 위치 | desktop([../operate.md](../operate.md) 4.1절). 노트북 측정은 비교에 쓰지 않는다 |
|
||||
| 하드웨어·런타임 | CPU 모델·논리 코어 수·Node 버전. lab 결과 JSON이 자동으로 담는다 |
|
||||
| 부하 | 측정 앞뒤의 load average. 다른 무거운 실행과 겹치지 않게 잠금 아래에서 잰다 |
|
||||
| 브라우저와 조건 | lab: Chromium, 1280×720, `contract-fast-4g`, CPU 4배 감속, 빈 캐시·새 browser context(`scripts/test-performance.ts`) |
|
||||
| 반복과 통계 | 기본 5회의 중앙값으로 판정한다. 표본 전부와 퍼짐을 함께 적는다. 예: "중앙값 227 ms(표본 223·224·227·438·526)" |
|
||||
| 빌드 | 커밋과 build id. 비교하는 두 빌드는 같은 env로 만든다. 커밋 ID가 빌드에 박혀 초기 JS가 몇 바이트 달라진다 |
|
||||
| 대조군 | 바꾸기 전 커밋을 같은 세션·같은 조건에서 함께 잰다. 지난 측정값을 대조군으로 쓰지 않는다 |
|
||||
| 규모 | 기능 수에 따른 비용은 실제 모양 기능 25개·100개로 재고 호스트 부하를 함께 적는다 |
|
||||
|
||||
## 4. 예산 사이의 균형
|
||||
|
||||
- **초기 JS bytes와 초기 파일 수는 함께 본다.** bytes를 줄이려고 청크를 나누면 파일 수가 는다. HTTP/1.1에서는 요청이 줄을 서서 첫 화면이 늦어진다. 파일 수 상한은 HTTP/2 호스팅을 전제로 정했다(`docs/operations/performance-evidence.md` 「초기 청크 수와 HTTP/1.1」).
|
||||
- **청크 이름으로 크기를 판단하지 않는다.** 공용 청크는 안에 든 모듈 하나의 이름을 받는다. 출처별 크기는 sourcemap으로 나눠 잰다.
|
||||
- **재방문 비용도 본다.** release마다 이름이 바뀌는 청크에 큰 라이브러리가 들어가면 코드가 같아도 다시 받는다(같은 문서 「build id와 재방문 캐시」, 결함 패턴 B4).
|
||||
- **여유를 적는다.** 예산에서 기준선을 뺀 여유와 기능 하나가 쓰는 양을 함께 보고한다.
|
||||
|
||||
## 5. 숫자를 고칠 때
|
||||
|
||||
- **기준선 기록**은 손으로 고치지 않는다. 측정 스크립트를 `--initial-baseline --write`로 돌리고 같은 변경에 넣는다. 손으로 적은 숫자는 두 번 낡았다. 묶음마다 맞아도 합친 트리에서 낡을 수 있으니 합친 끝에서 다시 잰다.
|
||||
- **대조 허용치는 남은 여유보다 작아야 한다.** 기록 대조 허용 1%(약 2 KB)가 남은 여유(1,873 B)보다 커서 여유를 다 쓰는 변경이 통과할 수 있었다. 허용치를 정할 때 여유·측정 오차와 비교한다(결함 패턴 B1).
|
||||
- **예산 값**(`config/performance/budgets.json`)을 올리는 것은 결정이다(꼭 지킬 것 4). 이유·대안·재검토 조건을 [decisions.md](decisions.md) 3절 형식으로 남기고 소유자 결정을 받는다. 예: 초기 파일 수 상한을 26에서 32로, 초기 JS 예산을 204,800 B에서 206,848 B로 올린 결정. 근거와 되돌림 규칙은 `docs/operations/performance-evidence.md`에 있다.
|
||||
- **문서에 측정값을 적을 때**는 커밋과 측정일을 붙인다. 그 숫자가 지금 빌드와 다를 수 있다고 적는다.
|
||||
|
||||
## 6. 성능 쪽 반복 결함
|
||||
|
||||
| 패턴 | 막는 기준 |
|
||||
| --- | --- |
|
||||
| release 단계에만 있는 게이트의 회귀를 아무도 모른다 | 2절: 라우트 로딩을 건드리면 `test:performance`도 돌린다 |
|
||||
| 실패 메시지가 무엇을 얼마나 넘었는지 말하지 않는다 | 예산 검사는 넘은 항목·잰 값·초과량을 모두 출력한다 |
|
||||
| 측정 조건 없이 숫자만 남아 비교할 수 없다 | 3절 표 |
|
||||
| lab이 화면 하나·조건 하나만 잰다. `/` 밖 화면의 layout shift, 스크롤바가 보이는 환경을 어느 게이트도 재지 않는다(결함 패턴 B2) | 기능 라우트 로딩을 바꾸면 그 라우트 첫 진입을 lab과 같은 조건으로 따로 재고 결과에 적는다 **[제안]** |
|
||||
| 부하가 높은 시간대의 실패를 "부하 탓"으로 닫는다 | [testing.md](testing.md) 5절: 부하를 낮춘 재현과 결정적 재현으로 확인한 뒤에만 부하를 원인으로 쓴다 |
|
||||
| 첫 화면에 필요 없는 코드가 배럴·side effect 판정 때문에 초기 청크에 들어간다(결함 패턴 B3) | design-system은 side effect 없음을 선언하고, 기능 선언과 실행부를 나눈다 |
|
||||
@@ -0,0 +1,179 @@
|
||||
# 리뷰 기준
|
||||
|
||||
이 repo를 리뷰할 때(전체·모듈·PR·diff 리뷰 모두)의 기준이다. 일반 기준의 정본은 리뷰 가이드다: design-docs `conventions/template-maturity-review-guide.md`(이 문서의 「가이드 N절」). repo 안 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`는 정본 위치만 적은 포인터다(절 번호는 정본과 같다). 가이드를 읽을 수 없는 프로젝트를 위해 발견 양식과 등급 정의를 7·8절에 줄여 옮겼다. 절차는 [../improve.md](../improve.md) 4.1절이다.
|
||||
|
||||
```text
|
||||
발견 하나 = 항목 하나 (관련 관점 번호를 모두 붙인다, 가이드 0.3절)
|
||||
├─ 성격 확인된 결함 / 구조적 위험 / 미검증 / 개선 제안 (가이드 35.1절)
|
||||
├─ 심각도 Critical / High / Medium / Low (35.2절)
|
||||
├─ 우선순위 P0~P3 (35.3절)
|
||||
├─ 통제 M0~M4, 확인 못 했으면 「미확인」(M0 아님) (35.4절)
|
||||
└─ 증거 E0~E4 (35.5절)
|
||||
```
|
||||
|
||||
## 1. 리뷰의 규칙
|
||||
|
||||
- 발견은 가이드의 28개 관점 번호로 분류한다. 결함 하나는 항목 하나로 적고 관련 관점 번호를 모두 붙인다. 같은 결함을 여러 번 세지 않는다.
|
||||
- 성격, 심각도(Critical~Low), 우선순위(P0~P3), 통제 수준(M0~M4), 증거(E0~E4)를 따로 적는다. 확인하지 못한 것은 M0가 아니라 `미확인`이다.
|
||||
- 발견은 가이드 36.3절 양식, 최종 요약은 36.5절 양식, 관점별 판정은 36.2절 표를 쓴다.
|
||||
- README와 설계 문서는 주장이다. 근거는 현재 커밋의 코드·설정·실행 결과에서 찾는다(가이드 34.1절). 이전 리뷰의 실행 결과를 현재 증거로 재사용하지 않는다.
|
||||
- 리뷰에서는 코드를 고치지 않는다. 고치는 일은 리뷰 문서를 근거로 따로 한다.
|
||||
- 심각도 체계는 가이드의 것(Critical~Low, P0~P3) 하나만 쓴다. 소유자 지시의 "Minor"는 Low로 읽는다.
|
||||
|
||||
**이 repo의 리뷰 전제**(루트 `AGENTS.md` 첫 문단·꼭 지킬 것 1·2와 같다).
|
||||
|
||||
- 이 repo는 템플릿(reference implementation)이다. 소비자가 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이지 죽은 코드가 아니다. 갈라진 중복 복사본은 문제로 본다.
|
||||
- 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은 없다.
|
||||
|
||||
## 2. 결함으로 보는 것
|
||||
|
||||
결함은 **이 repo가 스스로 한 약속**을 어기는 것이다.
|
||||
|
||||
| 약속 | 어디에 |
|
||||
| --- | --- |
|
||||
| 지원 범위와 상태 값 | 루트 `README.md` 「Support scope」 |
|
||||
| 현재 계약 | `docs/README.md` 1절이 링크한 문서 |
|
||||
| 게이트가 지키는 것 | `config/ci/gates.json`과 각 검사 스크립트 |
|
||||
| 생성 명령으로 기능을 더하면 템플릿 파일을 고치지 않고 merge를 통과한다 | `docs/manual/README.md`, `docs/manual/reference/create-feature.md` |
|
||||
| 지울 수 있다고 한 것은 지워도 게이트가 통과한다 | 루트 `README.md`의 지워도 되는 파일 표, FE-GATE-020 |
|
||||
| 짝 백엔드와 맞춘 계약 | `docs/architecture/backend-api-and-server-state-contract.md` 4.1·6·6.1절, `config/contracts/backend-contract-pin.json` |
|
||||
|
||||
결함으로 보지 않는 것: 소비자 없는 코드와 빈 레지스트리, 지원 범위 밖이라고 적힌 기능이 없는 것(예: SSR, bulk `results`), 서버 메모리 상태·다중 인스턴스 경쟁(탭 사이 경쟁은 본다), 인터페이스가 많다·kernel이 크다는 사실만으로(가이드 35.2절 끝 문단).
|
||||
|
||||
헷갈리는 경우:
|
||||
|
||||
| 경우 | 판정 |
|
||||
| --- | --- |
|
||||
| 게이트가 코드와 무관하게 항상 실패하거나, 실패 이유를 숨긴다 | 결함. 사용자 피해가 없으면 Medium, merge·release를 막으면 P1 |
|
||||
| 게이트가 PASS인데 그 뒤 단계가 실패한다 | 결함(검사가 거짓 PASS를 낸다) |
|
||||
| 문서 문장이 코드와 다르다 | 결함. 코드가 맞다. 문장이 사용자를 틀린 행동으로 이끌면 등급을 올린다 |
|
||||
| 같은 사실을 여러 곳에 손으로 적었고 아직 같다 | 구조적 위험 |
|
||||
| 같은 사실의 손 사본이 이미 서로 다르다 | 확인된 결함 |
|
||||
| 수정이 템플릿 원래 상태에서만 맞다 | 결함. 지원 구성(기능 추가·확장 지점 채움)에서 재현하면 확인된 결함 |
|
||||
|
||||
## 3. 심각도와 우선순위 — 이 repo의 판정 예
|
||||
|
||||
같은 모양이면 같은 등급을 준다. 등급을 영역 제안과 다르게 매기면 README 「심각도 조정」 표에 이유를 남긴다.
|
||||
|
||||
| 등급 | 이 repo의 예 |
|
||||
| --- | --- |
|
||||
| High·P1 | 결과 불명 쓰기를 키 없이 다시 보내 같은 항목이 둘 생긴다(가이드 35.2절 High 예시와 같은 모양). 짝 백엔드의 업무 거절이 모든 쓰기에서 결과 불명이 되어 폼이 막힌다. 두 템플릿을 짝으로 쓰면 업로드가 연결되지 않는다 |
|
||||
| Medium·P1 | 사용자 피해 없이 merge·release 게이트가 틀린 답을 내거나 이유를 숨긴다. "생성 명령으로 빠른 출시"라는 핵심 약속을 깨는 것도 여기다 |
|
||||
| Medium·P2 | 위험한 경로가 남았지만 템플릿이 그리는 경로는 막고, 제품이 직접 hook을 부를 때만 닿는다 |
|
||||
| Low·P3 | 낡은 문장, 이름, 작은 진단 누락 |
|
||||
|
||||
- **P1의 기준:** 도입·출시·확대 전에 해결해야 하는 것(가이드 35.3절). 이 repo에서는 merge 단계 게이트를 막는 것과, 지원 구성에서 짝 백엔드와 쓰는 기본 경로를 막는 것이다.
|
||||
- **복제 범위를 함께 적는다.** 다운스트림이 그대로 복제하는 기본값이면 그 사실을 적는다.
|
||||
|
||||
## 4. 증거 규칙
|
||||
|
||||
- **현재 커밋에서 찾는다.** 다른 세션이 같은 커밋에서 낸 결과도 가져다 쓰지 않고 다시 돌린다.
|
||||
- **실행 증거에는 조건을 붙인다.** 커밋, 위치(desktop), env(CI env인지), 부하, 반복 수. 부하가 높을 때의 실패는 따로 표시한다.
|
||||
- **desktop에 CI env를 준 실행은 실제 러너가 아니다.** 실제 Gitea 러너는 꺼져 있다. 이 실행의 증거 수준은 E2~E3이고, 「실제 CI 미검증」을 함께 적는다.
|
||||
- **"오케스트레이터 확인"의 뜻을 지킨다.** 재확인 칸에 이 말을 쓰면 총괄이 그 줄을 직접 읽었거나 직접 실행했다는 뜻이다.
|
||||
- **확인하지 못한 것은 「미확인」이다.** M0(통제 부재 확인)와 다르다.
|
||||
- 서브에이전트의 리뷰 결과는 코드를 실행하지 않았으면 E1이다. High 이상은 총괄이 다시 확인한다.
|
||||
|
||||
## 5. 28개 관점 — 이 repo에서 볼 곳
|
||||
|
||||
관점의 일반 설명은 가이드 1~28절이다. 「검사」 칸이 비어 있으면 그 관점을 기계로 지키는 게이트가 없다는 뜻이다. 관점마다 지난 대표 발견은 [../evidence.md](../evidence.md) 3절이다.
|
||||
|
||||
| # | 관점 | 이 repo에서 볼 곳 | 검사 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 코드 성숙도 | 판정 규칙이 모인 곳: `src/adapters/http/backend-envelope.ts`, 효과 분류, 폼 상태 | FE-GATE-002·003 |
|
||||
| 2 | 구조적 성숙도 | `docs/architecture/layers.md`, `.dependency-cruiser.json` | `check:architecture`(FE-GATE-010) |
|
||||
| 3 | 변경 용이성 | 기능 하나를 더하거나 지울 때 템플릿 파일을 고쳐야 하는가 | FE-GATE-020 |
|
||||
| 4 | 인지 부하 | 기능 작성자가 알아야 할 등록 규약 수, `docs/manual/` 막힘 | |
|
||||
| 5 | 위험 가시성 | 결과 불명·재전송·삭제 같은 위험이 코드와 화면에 드러나는가(가이드 29절) | |
|
||||
| 6 | 실패 성숙도 | 짝 백엔드 오류 응답의 분류, 결과 불명 처리 | FE-GATE-007 |
|
||||
| 7 | 운영 성숙도 | `docs/runbooks/`, `docs/operations/`, release job 로그 | FE-GATE-021~025 |
|
||||
| 8 | 디버깅 가능성 | 실패 메시지가 원인과 고칠 파일을 말하는가, `traceId` | |
|
||||
| 9 | 유지보수 성숙도 | 낡은 문장, CHANGELOG 미출시 절 | `verify:documentation` |
|
||||
| 10 | 테스트 성숙도 | 변이 검출, 템플릿 원래 상태 밖 입력([testing.md](testing.md)) | FE-GATE-005~009 |
|
||||
| 11 | 데이터 성숙도 | 로그아웃·계정 삭제 뒤 남는 데이터(IndexedDB, OPFS, Cache Storage) | |
|
||||
| 12 | 동시성 성숙도 | 탭 사이 경쟁, Web Locks, 같은 입력 재제출, 한 checkout 두 실행 | |
|
||||
| 13 | 확장성 | 기능 수 증가 축: 초기 JS 여유, 기능 모양 상한 | FE-GATE-005, FE-GATE-012 |
|
||||
| 14 | 성능 성숙도 | [performance.md](performance.md) | FE-GATE-012·026 |
|
||||
| 15 | 보안 성숙도 | `docs/security/browser-boundary.md`, 저장 키, 401 전달, CSP | FE-GATE-013 |
|
||||
| 16 | 의존성 성숙도 | advisory, lockfile, 의존성 변경 증거 | FE-GATE-001·013 |
|
||||
| 17 | API / Contract 성숙도 | 짝 백엔드 계약 pin, 답 표, 생성기가 옮긴 사실 | FE-GATE-007, 짝 계약 대조 테스트 |
|
||||
| 18 | 배포 성숙도 | `docs/architecture/static-delivery.md`, 호스팅 헤더, 배포 슬롯 | FE-GATE-019 |
|
||||
| 19 | 설정 성숙도 | 런타임 설정과 빌드 식별값, CI env | `verify:documentation`(runtime variables) |
|
||||
| 20 | 개발자 경험 | `create:feature`, 로컬 실행, 한 파일 테스트 실행 | |
|
||||
| 21 | Guardrail 성숙도 | 게이트가 맞는 답을 내는가, 사전 점검이 실제로 확인하는가 | `check:ci` |
|
||||
| 22 | 추상화 성숙도 | descriptor·포트가 실제 요청을 통제하는가 | |
|
||||
| 23 | 일관성 | 같은 판정을 하는 두 표가 같은가 | |
|
||||
| 24 | 네이밍 / 의미 성숙도 | 오류 code·상태 이름의 뜻 | |
|
||||
| 25 | 조직 확장성 | 기능 브랜치끼리 같은 줄 충돌, 다운스트림 동기화 비용 | |
|
||||
| 26 | Ownership 성숙도 | 규칙 `comment`의 담당·재검토 조건, 두 repo 사이 몫 | |
|
||||
| 27 | 삭제 가능성 | 기능·recipe·선택 runtime 제거([structure.md](structure.md) 12절) | FE-GATE-020 |
|
||||
| 28 | 회복 가능성 | 회복 필요 응답 뒤 행동, SW 비상 경로, release rollback | FE-GATE-025 |
|
||||
|
||||
## 6. 다시 판정할 때
|
||||
|
||||
다음 라운드 리뷰는 지난 발견 전부의 지금 상태를 표 하나로 적는다.
|
||||
|
||||
- 상태: 고침 / 일부 / 남음 / 결정 대기. 지난 「고침」도 코드로 다시 본다. 코드는 들어왔지만 완료 기준 실행이 없으면 「일부」다(가이드 35.6절, 결함 패턴 G14).
|
||||
- 「일부」면 남은 부분에 새 등급을 매긴다. 남은 부분이 원래보다 좁으면 등급을 내린다.
|
||||
- 지난 수정이 만든 새 결함은 새 발견으로 세고, 원인 수정 커밋을 적는다.
|
||||
|
||||
## 7. 리뷰 문서 형식
|
||||
|
||||
**폴더와 ID.** 폴더는 `docs/reviews/<YYYY-MM-DD>-maturity-review/`, README 하나와 영역 문서 `NN-<영역>.md`. 발견 ID는 라운드 안에서 `NN-MM`(영역 번호-순번), 라운드 밖에서는 `MMDD/NN-MM`(가이드 36.3절). 총괄이 직접 찾은 발견은 관련 영역 번호를 쓰고 README 「오케스트레이터 발견」 절에 둔다. diff 리뷰도 같은 체계를 쓴다(바뀐 파일의 영역 번호).
|
||||
|
||||
**발견 하나의 칸**(가이드 36.3절을 줄인 것). 설계 선택이 없는 단순 결함은 「결정의 근거」「대안 비교」「단순화의 보존 조건」「재검토 조건」을 `적용 제외 — 이유 한 문장`으로 둔다.
|
||||
|
||||
| 칸 | 적을 것 |
|
||||
| --- | --- |
|
||||
| ID·제목 | `NN-MM`과 구체적인 문제 |
|
||||
| 성격, 관련 관점 | 2절의 넷 중 하나, 28개 관점 번호 전부 |
|
||||
| 근거, 발생 조건, 영향 | 파일·심볼·설정·실행 결과(`file:line`), 어떤 입력·순서·장애·규모에서, 누구에게 무엇이 |
|
||||
| 심각도·우선순위, 통제, 증거 | 등급과 이유(3절), M0~M4 또는 `미확인`, E0~E4(8절) |
|
||||
| 확실성과 남은 가정, 결정의 근거 | 확인한 사실과 추론의 경계, 설계 선택이면 지금 제약과 선택 이유 |
|
||||
| 최소 개선 방향, 대안 비교, 비용·부작용 | 위험을 줄이는 가장 작은 변경, 여러 선택지면 비교 |
|
||||
| 완료 기준, 검증 방법 | 끝났는지 볼 관찰 가능한 조건, 그 위험을 직접 다루는 테스트·실험 |
|
||||
| 상태, 재검증 결과 | 열림·고침·일부·결정 대기, 변경 버전과 결과 |
|
||||
|
||||
**README 절 순서.** 가이드 36.5절 요약 일곱 항목과 36.1·36.2절을 담는다.
|
||||
|
||||
| 절 | 내용 |
|
||||
| --- | --- |
|
||||
| 머리말 | 기준 가이드, 대상 커밋, 영역 수, 실행 위치, 리뷰 중 코드를 고치지 않았다는 사실 |
|
||||
| 0 평가 전제 | 가이드 0.1절 표 |
|
||||
| 1 사용 결정 | 용도별 사용 가능·조건부·보류와 막는 항목(36.5-1) |
|
||||
| 2 차단 항목 | 새 High, 새 P1(재확인 칸 포함), 이월 항목 중 남은 큰 것, 심각도 조정과 합침 |
|
||||
| 3 물은 것에 대한 답 | 리뷰를 맡긴 쪽이 따로 물은 것 |
|
||||
| 4 새 발견 건수 | 지난 라운드와 심각도·우선순위·성격별 비교 |
|
||||
| 5~10 | 확인된 강점, 반복되는 원인, 결정이 필요한 것, 미검증, 개선 순서, 재검토 조건(36.5-2~7) |
|
||||
| 11 리뷰 범위 | 36.1절 표, 게이트 실행 결과, 영역 분할, 합친 중복, 실행 방식과 안전 사항, 총괄 자신의 실수 |
|
||||
| 12 28개 관점 판정 | 36.2절 표. 종합은 평균하지 않는다. 한 영역이라도 미충족이면 미충족(35.7절) |
|
||||
| 13 지난 발견 상태 | 6절 |
|
||||
| 14 오케스트레이터 발견 | 36.3절 양식 |
|
||||
| 15 새 발견 색인 | 영역 문서에서 기계적으로 모은다. 손으로 옮기지 않는다 |
|
||||
|
||||
수정 라운드가 끝나면 같은 README에 「조치」 절(방법, 결정, 통합에서 생긴 것, 발견별 상태, 확인, 남은 문제)을 더한다.
|
||||
|
||||
**영역 문서 절 순서.** 0 결론(몇 줄) · 1 범위(36.1절, 읽은 경로, 돌린 것, 확인하지 못한 것) · 2 지난 발견 재판정(6절) · 3 이번 발견(36.3절 양식. 설계 선택이 없는 단순 결함은 선택 비교 칸을 「적용 제외」와 한 문장 이유로) · 4 28개 관점 판정(36.2절) · 5 설계 선택 설명(가이드 41절, 여러 타당한 선택지가 있는 발견만) · 6 실험·실행 기록.
|
||||
|
||||
## 8. 통제와 증거의 뜻
|
||||
|
||||
- 통제(가이드 35.4절, 선정한 규칙 하나에 매긴다): M0 지킬 수단이 없음을 확인함 · M1 규칙이 적혀 있음 · M2 필요한 코드 경로에 구현됨 · M3 자동 검사가 위반을 잡음 · M4 타입·공개 범위·권한 같은 경계가 위반을 막음. 읽지 못했으면 M0가 아니라 `미확인`이다.
|
||||
- 증거(가이드 35.5절): E0 문서·주장 · E1 코드·설정을 읽어 확인 · E2 명시한 테스트가 그 버전에서 통과 · E3 실제 의존성·부하·장애 조건의 통합·실험 · E4 실제 운영 관찰. 높은 번호 하나가 낮은 번호의 다른 검증을 대신하지 않는다.
|
||||
|
||||
## 9. 판단을 적는 법
|
||||
|
||||
- 확인한 사실 / 기록된 의도 / 추론을 나눈다(가이드 41.3절). 다운스트림 파일을 열지 않고 이름으로 추정한 문장이 CHANGELOG에 틀린 이행 안내로 남은 일이 있다.
|
||||
- 결정이 필요한 것은 선택지, 권하는 안, 결정할 사람을 적는다([decisions.md](decisions.md) 3절 형식).
|
||||
- 리뷰에 쓴 스킬과 그 스킬의 기준으로 무엇을 봤는지를 「범위」 절에 한 줄씩 적는다 **[제안]**.
|
||||
|
||||
## 10. 총괄이 README에 쓰는 것
|
||||
|
||||
범위(가이드 36.1절), 28개 관점 판정표(36.2절), 최종 요약(36.5절), 발견 색인. High 이상 발견은 코드에서 직접 다시 확인한 뒤에 쓴다.
|
||||
|
||||
## 11. 커밋·CHANGELOG의 리뷰 ID
|
||||
|
||||
- 결함 수정 커밋은 꼬리말 `Refs:`에 라운드 접두어를 붙인 발견 ID를 적는다(`Refs: <MMDD>/<NN>-<MM>` 꼴). 형식의 정본은 design-docs `conventions/commit-and-pr.md` 3.4절과 가이드 36.3절이다.
|
||||
- `CHANGELOG.md`의 리뷰 ID도 `MMDD/NN-MM` 꼴이어야 한다. `tests/unit/changelog-review-ids.test.ts`가 검사한다.
|
||||
- 호환을 깨는 변경은 type 뒤 `!`와 `BREAKING CHANGE:` 꼬리말을 단다. 본문은 문제 → 고른 방법과 버린 대안 → 위험·한계 → 검증 순서다.
|
||||
@@ -0,0 +1,120 @@
|
||||
# 구조 기준 — 폴더·모듈·코드
|
||||
|
||||
폴더 구조와 import의 규칙은 이미 코드와 게이트에 있다. 이 문서는 **구조를 바꿀 때 어느 정본을 같이 고쳐야 하는지**, **리뷰에서 구조 결함으로 볼 것과 보지 않을 것**, 그리고 **게이트가 지키지 못해 반복된 코드 결함을 막는 기준**을 적는다. 괄호 안 `결함 패턴 X0`은 [defect-patterns.md](defect-patterns.md)의 행이다.
|
||||
|
||||
```text
|
||||
src/ 최상위 폴더 ── 역할: docs/architecture/layers.md 표
|
||||
│ 규칙: .dependency-cruiser.json (check:architecture, FE-GATE-010)
|
||||
├─ adapters/<그룹>/index.ts ── 공개 경계(배럴)
|
||||
│ └─ platform/** 등 kernel 3곳만 그룹을 넘어 import 가능
|
||||
├─ features/<id>/ ── 지울 수 있는 기능 하나 (제거 드릴, FE-GATE-020)
|
||||
└─ contexts/, apps/ ── 기능 묶음과 배포 단위
|
||||
```
|
||||
|
||||
## 1. 정본
|
||||
|
||||
| 무엇 | 정본 | 검사 |
|
||||
| --- | --- | --- |
|
||||
| 최상위 `src/` 폴더와 각 역할 | `docs/architecture/layers.md` 표 | `verify:documentation`이 폴더 목록·설명 일치를 본다 |
|
||||
| import 규칙 | `.dependency-cruiser.json` `forbidden`, 설명은 `docs/architecture/layers.md` | `check:architecture` |
|
||||
| adapter kernel | `docs/architecture/layers.md`, 규칙 `adapters-do-not-know-other-concrete-adapters` | `check:architecture` |
|
||||
| 규칙 예외의 이유·담당·재검토 조건 | 그 규칙의 `comment` | 사람이 본다 |
|
||||
| adapter 그룹의 공개 경계 | 규칙 `adapter-groups-are-reached-through-their-barrel` | `check:architecture`, 고정 fixture `tests/fixtures/architecture/dependency-graph/barrel` |
|
||||
| adapter 파일 목록 | `docs/reviews/adapters/INVENTORY.md` | `check:adapter-inventory`(FE-GATE-010) |
|
||||
| 공유 타입·프리미티브를 어디에 둘지 | `docs/architecture/contract-ownership.md` 「Decision rule」 | 사람이 본다 |
|
||||
| 기능 폴더의 모양 | `docs/manual/01-add-a-feature.md`, `create:feature`가 만드는 파일 | FE-GATE-020의 `test:feature-scaffold` |
|
||||
| 재시도 의미, 결과 불명, 인증, 업로드의 판단 기준 | `docs/manual/02-decision-tables.md` | 사람이 본다 |
|
||||
| 오류·재시도·실패 경계·trace 모델 | `docs/architecture/scale-architecture.md`(코드 주석의 `scale-architecture.md §N`) | 사람이 본다 |
|
||||
| 짝 백엔드 쓰기 응답의 판정 표 | `src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE`, 근거 `docs/architecture/backend-api-and-server-state-contract.md` 6.1절 | 짝 계약 대조 테스트 |
|
||||
|
||||
## 2. 이 repo의 고정 전제
|
||||
|
||||
1. **확장 지점은 남긴다.** 소비자 없는 코드와 빈 레지스트리는 다운스트림용이다. 죽은 코드로 보고 지우지 않는다(소유자 결정 2026-09-16).
|
||||
2. **갈라진 중복 복사본은 하나로.** 같은 일을 하는 코드가 두 벌이고 서로 달라지기 시작했으면 결함이다(결함 패턴 S3). 합칠 곳은 kernel(`src/adapters/platform/`)이나 `src/contracts/`다.
|
||||
3. **배럴이 공개 경계다.** 그룹 바깥(`src/bootstrap`, `src/features`, `src/presentation`)은 그룹의 `index.ts`만 import한다. 배럴 폐지안은 2026-09-16에 기각됐다. 2단계 `index.ts`는 공개 배럴이 아니다(예외: `storage/indexeddb`, `storage/opfs` 서브배럴).
|
||||
4. **kernel 예외는 셋뿐이다.** `src/adapters/platform/` 폴더 전체, `src/adapters/browser-file-storage/result.ts`, `src/adapters/cross-context-invalidation/index.ts`. 새 파일 단위 예외를 제안하지 않는다. 새 공유 프리미티브는 `src/adapters/platform/`에 넣는다. 폴더 전체가 예외라 규칙을 바꿀 필요가 없다.
|
||||
5. **실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker다.** 서버 메모리 상태·다중 인스턴스 경쟁 기준은 적용하지 않는다. 탭 사이 경쟁은 적용한다.
|
||||
|
||||
## 3. 바꿀 때 같이 고칠 것
|
||||
|
||||
| 바꾸는 것 | 같은 커밋에서 고칠 것 |
|
||||
| --- | --- |
|
||||
| 최상위 `src/` 폴더 추가·삭제 | `docs/architecture/layers.md` 표 한 행. 같은 설명 문장을 루트 `README.md`, `docs/architecture/overview.md`, `docs/architecture/frontend-application-foundation.md`에 그대로(`verify:documentation`이 대조한다) |
|
||||
| import 규칙 추가·이름 변경 | `.dependency-cruiser.json`, `docs/architecture/layers.md` 규칙 표의 행 |
|
||||
| 규칙 예외 | 그 규칙의 `pathNot`과 `comment`(이유·담당·재검토 조건). 파일 단위 kernel 예외는 만들지 않는다 |
|
||||
| adapter 파일 추가·이동·삭제 | `docs/reviews/adapters/INVENTORY.md` |
|
||||
| adapter 그룹 공개 표면 | 그 그룹의 `index.ts` |
|
||||
| 기능·context 경계 | `src/features/<id>/`와 `tests/features/<id>/`. 기능끼리, context끼리 import하지 않는다 |
|
||||
| 지울 수 있는 단위(기능, recipe, 선택 runtime) | 그 단위의 제거 드릴이 함께 지울 목록(`scripts/test-sample-removal.ts` 머리말) |
|
||||
|
||||
## 4. 문서 위치와 지워도 되는 문서
|
||||
|
||||
- 지금 코드가 지키는 규칙은 `docs/README.md` 1절 묶음, 앞으로의 설계·결정은 2절(결정 기록은 `docs/architecture/decisions/`), 리뷰·계획·작업 추적은 3절(복사한 프로젝트가 지울 수 있다), 새 기능 절차는 `docs/manual/`, 작업 절차는 `docs/work/`, 여러 repo에 걸친 설계는 repo 밖 design-docs다.
|
||||
- 코드·테스트·스크립트·설정은 지워도 되는 문서(루트 `README.md`의 지워도 되는 파일 표)를 읽지 않는다. 예외는 `docs/reviews/adapters/INVENTORY.md` 하나다. `tests/unit/deletable-history-documents.test.ts`가 검사한다. 테스트가 리뷰 문서를 열어 제거 드릴 셋을 깨뜨린 일이 있다.
|
||||
- 루트 `AGENTS.md`·`CLAUDE.md`, `.claude/`, `docs/work/`는 지워도 되는 문서가 아니다. 복사한 프로젝트가 받는 템플릿 계약이다(소유자 결정 2026-11-07).
|
||||
- 현재 계약 문서는 작업 이력 문서에 기대지 않는다.
|
||||
|
||||
## 5. 리뷰에서 구조 결함으로 보는 것
|
||||
|
||||
| 결함으로 본다 | 결함으로 보지 않는다 |
|
||||
| --- | --- |
|
||||
| 갈라진 중복 복사본(결함 패턴 S3) | 소비자 없는 확장 지점, 빈 레지스트리 |
|
||||
| 같은 사실을 여러 곳에 손으로 다시 적는다(결함 패턴 S1) | 인터페이스가 많다는 사실만으로 |
|
||||
| 문서가 없는 폴더·규칙을 말한다 | kernel 폴더가 크다는 사실만으로 |
|
||||
| 템플릿 파일을 고쳐야 기능을 더하거나 지울 수 있다(결함 패턴 S4) | 다운스트림이 쓰지 않는 선택 runtime |
|
||||
| 지울 수 있다고 한 단위를 지우면 게이트가 실패한다 | |
|
||||
|
||||
## 6. 코드 기준 — 판정 규칙은 한 곳에
|
||||
|
||||
- **실패 분류는 status 하나로 하지 않는다.** status와 code를 함께 본다. 표 밖의 값은 안전한 쪽(결과 불명)으로 둔다. 업무 거절이 결과 불명으로, 일시 오류가 무결성 실패로 분류되는 결함이 여러 영역에서 났다(결함 패턴 C1).
|
||||
- **짝 백엔드 쓰기 응답의 판정 표는 `REFUSED_BEFORE_WRITE` 하나다.** 실행 경로가 둘이어도 같은 표를 읽는다. operation 단위 예외는 descriptor의 `commandEffect.refusedBeforeWrite` code 목록으로만 선언한다.
|
||||
- **결과 불명 쓰기를 다시 보내는 모든 입구를 함께 본다.** 재전송 버튼, hook 재제출, 실행기 재시도, poll 재시도, 업로드 재시도. 하나를 막으면 다른 입구에서 다시 나왔다. 키 없는 쓰기(`NEVER`)는 결과 불명 뒤 재전송하지 않는다. 키 있는 쓰기는 같은 키로만 다시 보낸다(결함 패턴 C2).
|
||||
- **판정 규칙의 경계를 테스트로 고정한다.** 경계 하나를 바꾸는 변이가 게이트에서 실패해야 한다([testing.md](testing.md) 3절).
|
||||
|
||||
## 7. 코드 기준 — 실패는 드러나게
|
||||
|
||||
- **원인과 추적값을 싣는다.** 실패 객체·진단에 effect, reason, `traceId`, 어느 참여자인지를 싣는다. 서로 다른 실패를 같은 reason으로 남기지 않는다. 진단 reason은 이 repo가 소유한 닫힌 목록이고 서버 code를 그대로 넣지 않는다. 서버 code는 실패의 `AppFailure.code`에 남는다. 새 adapter도 같은 기준으로 리뷰한다(결함 패턴 C6).
|
||||
- **오지 않을 신호를 기다리지 않는다.** 모든 대기에는 끝나는 조건(예산 소진, 마감, 취소)이 있다 **[제안]**(결함 패턴 C3).
|
||||
- **손상 한 건이 전체를 멈추지 않게 한다.** 손상 행은 건너뛰고 수를 보고한다(결함 패턴 C4).
|
||||
- **결과를 사실대로 보고한다.** 다 하지 못했으면 `COMPLETED`·`verified`·`active`를 보고하지 않는다. 읽은 시점과 보고 시점 사이에 다른 작업(다른 탭의 put, release)이 끼어들 수 있으면, 같은 잠금 아래에서 다시 대조하거나 끝난 뒤 한 번 더 센다. 테스트는 객체 셋 이상으로 한다(결함 패턴 C5).
|
||||
- **실패·복구 전이 뒤 화면이 다음 행동을 남긴다.** 실패 표시에서 고친 포커스·안내를 복구 성공, 확인, 진행 중 전이에도 쓴다. 페이지마다 복사하지 않고 공용 폼 hook 안에서 한다(결함 패턴 C11).
|
||||
- **확인하지 못한 판정은 `PASS`가 아니라 `UNVERIFIED`다.** 코드에 상수 `true` 판정을 두지 않는다.
|
||||
|
||||
## 8. 코드 기준 — 같은 사실은 한 곳에
|
||||
|
||||
- **repo 안:** 스키마 메타, 레지스트리 행, 허용 키 목록, 빌드 입력 목록, 저장 키를 원본(zod 스키마, descriptor, registry)에서 뽑는다. 손으로 다시 적어야 하면 원본과 대조하는 테스트를 같이 둔다. 두 검사기가 같은 산출물을 다른 키 목록으로 읽어 merge 게이트가 항상 실패한 일이 있다(결함 패턴 S1).
|
||||
- **이미 갈라진 복사본은 하나로 합친다.** 갈라진 recipe port는 지우고 `src` port를 다시 내보낸다.
|
||||
- **두 템플릿 사이:** 짝 백엔드의 프로토콜·오류 code·응답 모양·생성기 규칙을 옮길 때는 백엔드 문서만 보지 않고 **코드까지 따라간다**(백엔드 생성기, 프론트 폼까지). 판정 표를 백엔드 계약 문서만으로 정해 High를 만든 일이 있다. 옮긴 사실은 기준 커밋(`config/contracts/backend-contract-pin.json`)과 대조 테스트로 묶는다. pin과 drift 검사는 아직 계약 문서 글자만 비교하고, 답 표 JSON과 생성기 사실은 대조 밖이다(결함 패턴 S2).
|
||||
- 짝 백엔드 repo는 읽기만 한다. 백엔드가 바꿔야 할 것은 "백엔드에 넘길 것"으로 적는다.
|
||||
|
||||
## 9. 코드 기준 — 지우거나 바꿀 때
|
||||
|
||||
- **그 코드가 지키던 것을 찾는다.** 실행 동작만 옮기면 지운 행·테스트·분기가 지키던 규칙이 조용히 사라진다. 지우기 전에 그 코드를 읽는 테스트와 검사를 `git grep`으로 찾고, 각각이 지키던 규칙이 새 경로에도 있는지 적는다(결함 패턴 T10).
|
||||
- **이름을 바꿀 때는** 새 이름을 내고 옛 이름은 한 릴리스 동안 `@deprecated` 별칭으로 남긴다. 이름 하나가 여러 뜻을 가지거나 한 뜻이 여러 이름을 가지면 결함이다(결함 패턴 C10).
|
||||
- **공개 포트는 추가만 한다.** 깨야 하면 결정 표에 적고 BREAKING으로 커밋한다.
|
||||
|
||||
## 10. 코드 기준 — 설정·환경, 동시성, 확장 지점
|
||||
|
||||
- **같은 설정을 경로마다 다르게 읽지 않는다.** 번들, 빌드 스크립트, Service Worker 빌드가 같은 출처에서 읽는다(결함 패턴 C8).
|
||||
- **URL은 router base path를 따른다.** `/`부터 직접 조립하지 않는다. 기본 게이트가 루트 경로만 돌아 드러나지 않는다. 하위 경로 빌드 테스트로 확인한다(결함 패턴 C7).
|
||||
- **테스트가 띄우는 빌드·서버의 env는 테스트가 정한다**([gates.md](gates.md) 4절).
|
||||
- **환경 가정은 적고, 확인하고, 없으면 이유를 말하며 실패한다.** 글꼴, user namespace, 옆 checkout(결함 패턴 G6).
|
||||
- **여러 탭이 같은 저장소·구독·잠금을 건드리는 경로**는 Web Locks로 직렬화하거나 잠금 없이도 안전한 이유를 적는다. 잠금을 기다리는 작업에는 abort와 상한이 있다(결함 패턴 C9).
|
||||
- **제품마다 다른 것은 제품 소유 파일에 둔다.** 제품이 템플릿 소유 파일을 고쳐야 하면 결함이다. 동기화마다 같은 파일이 충돌한다. 제품 소유 자리의 예: `src/bootstrap/product-composition.ts`, `src/contracts/product-contracts.ts`, `config/ci/product-gates.json`. 효과는 다음 동기화 충돌 수로 잰다(결함 패턴 S4).
|
||||
- **경계 예외는 실제 쓰임만큼만 연다.** kernel 폴더에는 공유 메커니즘만 둔다(결함 패턴 S5).
|
||||
- **두 모듈이 이어지는 곳을 지나는 테스트를 둔다.** 한쪽이 보내는 결과를 다른 쪽이 다른 뜻으로 받는 결함은 연결 지점에서만 보인다(결함 패턴 S6).
|
||||
|
||||
## 11. 고칠 때 — 수정이 새로 가정하는 것
|
||||
|
||||
2026-11-05 리뷰의 새 발견 48건 중 22건은 원인이 지난 수정이었다. 수정 커밋마다 본문 「위험·한계」에 적는다(결함 패턴 G13).
|
||||
|
||||
1. 이 변경이 새로 가정하는 상태(빈 제품 파일, CI env 없음, 객체 하나, 기능 0개 등).
|
||||
2. 그 가정이 깨지는 지원 구성에서 한 번 돌렸는가([../improve.md](../improve.md) 4.2절 6단계).
|
||||
3. 이 변경이 다른 검사를 약하게 했는가. 경로를 백틱 밖으로 옮겨 문서 검사를 피한 수정이 그 경로를 검사 밖으로 냈다. 위험을 커밋 본문에 적고도 테스트하지 않아 다운스트림 게이트가 항상 실패한 수정도 있다.
|
||||
|
||||
## 12. 제거 가능성
|
||||
|
||||
지울 수 있는 단위는 merge 게이트 FE-GATE-020의 드릴이 지킨다. 드릴 목록은 `config/ci/gates.json`의 FE-GATE-020 `commandIds`다.
|
||||
|
||||
- 구조를 바꾸면 드릴을 돌린다. 드릴 fixture가 복사하는 목록(`scripts/lib/removal-fixture.ts`, 이 목록 하나만 쓴다)이 바뀐 구조를 아는지 본다. 그 목록에 `README.md`·`CHANGELOG.md`가 없어 드릴 넷 중 셋이 항상 실패한 일이 있다(결함 패턴 G11).
|
||||
- 드릴은 오래 걸린다(FE-GATE-020은 14~21분). desktop에서 잠금 아래 돌린다.
|
||||
@@ -0,0 +1,106 @@
|
||||
# 테스트 기준
|
||||
|
||||
테스트는 **결함을 막는지**로 평가한다. 테스트가 있다는 사실, 커버리지 숫자는 근거가 아니다. 이 repo의 테스트 결함은 여러 라운드 동안 같은 모양으로 반복됐다. 괄호 안 `결함 패턴 X0`은 [defect-patterns.md](defect-patterns.md)의 행이다.
|
||||
|
||||
```text
|
||||
결함을 고쳐도·규칙을 지워도 통과한다 → 변이로 확인한다 (3절)
|
||||
템플릿 원래 상태·작은 입력에서만 맞다 → 기능 추가·확장 지점 채움·입력 3개 이상으로도 돈다 (3절)
|
||||
속도·부하·브라우저 추정에 기댄다 → 결정적 재현으로 원인을 찾는다 (5절)
|
||||
고정 경로·포트·로컬 생성물에 기댄다 → 깨끗한 clone·한 checkout 두 실행으로 확인한다 (4절)
|
||||
```
|
||||
|
||||
## 1. 정본
|
||||
|
||||
| 무엇 | 정본 |
|
||||
| --- | --- |
|
||||
| 테스트 층, 명령, 실행 환경, 층을 정하는 기준 | `docs/testing/taxonomy.md` |
|
||||
| 넓은 테스트 설계, flaky 정책, 금지 패턴 | `docs/testing/frontend-platform-testing-strategy.md`. 목표 설계 문서라 지금 코드와 다른 곳이 있다. 다르면 코드가 맞다 |
|
||||
| Vitest 수집 범위, `.only` 금지, 전역 timeout | `vitest.config.ts` |
|
||||
| Vitest 실행 runner(Node 버전, `NODE_ENV`, 생성물) | `scripts/run-vitest.ts` |
|
||||
| Playwright skip·fixme의 quarantine 조건, `forbidOnly` | `scripts/check-test-evidence.ts` |
|
||||
| 테스트 공통 대기 기한 | `tests/setup.ts` |
|
||||
| 모든 테스트 파일이 어떤 게이트에서 도는가 | `check:ci`, 예외 목록 `config/ci/ungated-tests.json` |
|
||||
| 지워도 되는 문서를 테스트가 읽지 않는다 | `tests/unit/deletable-history-documents.test.ts` |
|
||||
|
||||
## 2. 테스트를 어디에 둘까
|
||||
|
||||
`docs/testing/taxonomy.md`가 기준이다. **프레임워크가 아니라 필요한 실행 환경**이 층을 정한다.
|
||||
|
||||
| 필요한 것 | 둘 곳 | 명령 |
|
||||
| --- | --- | --- |
|
||||
| Node만(도메인·정책·순수 함수, 스크립트의 짧은 CLI 계약) | `tests/unit` | `test:unit` |
|
||||
| 재사용 capability의 소비자 계약 | `tests/contract` | `test:contract` |
|
||||
| React·hook·UI 동작 | `tests/component` | `test:component` |
|
||||
| HTTP/MSW, IndexedDB, 조립된 경계, 오래 사는 자식 프로세스 | `tests/integration` | `test:integration` |
|
||||
| systemd·bubblewrap·cgroup v2 | `tests/system` | `test:system`(FE-GATE-013) |
|
||||
| 실제 브라우저 3엔진 | `tests/e2e`, `tests/browser-capabilities`, `tests/visual`, `tests/storybook` | FE-GATE-008·009 |
|
||||
| 한 기능의 테스트 | `tests/features/<id>/` | 기능 폴더와 함께 지워진다 |
|
||||
|
||||
- 스크립트 테스트가 자식 프로세스를 띄우면 그 suite가 자기 timeout을 선언한다. 전역 timeout을 올리지 않는다.
|
||||
- 플랫폼을 지키는 테스트는 기능·스타터 화면에 묶지 않는다. 테스트 전용 라우트와 플랫폼 소유 MSW 카탈로그(`tests/mocks/`)를 쓴다(결함 패턴 T7). 생성물 탐침 이름은 예약 접두어(`typecheck-probe-*`)를 쓴다.
|
||||
- 기능 테스트가 지워도 되는 문서를 읽으면 제거 드릴이 깨진다([structure.md](structure.md) 4절).
|
||||
- 테스트 작성의 편집 직후 규칙은 `.claude/rules/tests.md`다(Claude Code는 테스트 파일을 열 때 읽는다).
|
||||
|
||||
## 3. 테스트가 결함을 막는지 확인하는 법
|
||||
|
||||
**RED 먼저.** 동작을 바꾸는 수정은 재현 테스트가 먼저 실패하고, 고친 뒤 통과한다. 커밋 본문에 RED와 GREEN을 적는다. 이 규칙을 강제하는 게이트는 없다. 리뷰가 커밋 본문으로 확인한다.
|
||||
|
||||
**변이로 검출력을 잰다.**
|
||||
|
||||
- 보호 규칙 한 줄을 지우거나 바꾸는 변이를 넣어, 그 규칙을 지키는 테스트가 실패하는지 본다. 결함 수정안을 넣었을 때 기존 테스트가 모두 통과하면 그 테스트는 결함을 막지 못했던 것이다(결함 패턴 T1).
|
||||
- 커버리지 100%인 곳에서도 판정 경계의 변이가 살아남았다. 커버리지는 줄을 지나갔다는 뜻일 뿐이다.
|
||||
- 변이 실험은 일괄 실행 목록으로 낸다. 리뷰어가 손으로 만들어 checkout 전체를 잠그며 돌리지 않는다([../delegate.md](../delegate.md) 4.2절).
|
||||
|
||||
**템플릿 원래 상태 밖에서도 돈다.** 수정을 템플릿 원래 상태나 작은 입력으로만 확인하면 다운스트림에서 다시 결함이 된다(결함 패턴 G2).
|
||||
|
||||
| 확인할 상태 | 지난 예 |
|
||||
| --- | --- |
|
||||
| 기능을 하나 이상 더한 상태(`create:feature`) | 기능을 더하면 시각 테스트가 실패했다 |
|
||||
| 제품 확장 지점을 채운 상태 | 타입 검사 탐침이 제품 파일을 통째로 덮어써 제품 capability가 있는 사본에서 FE-GATE-005가 항상 실패했다 |
|
||||
| 예제 기능을 지운 상태 | CHANGELOG 안내대로 예제를 지우면 문서 검사가 실패했다 |
|
||||
| 입력·객체가 셋 이상 | purge 수정 테스트가 객체 0~1개만 써서 3개 이상의 결함을 놓쳤다 |
|
||||
| 매뉴얼 예시 이름으로 만든 기능 | 템플릿 테스트의 글자가 제품 기능 이름과 부딪쳐 제거 드릴이 실패했다 |
|
||||
|
||||
**단언이 대상에 닿는가.** fixture가 비어 첫 줄에서 return하지 않는가. 전제(예: 포커스가 먼저 옮겨졌는가)를 함께 단언하는가. 실제 화면이 아니라 로딩 화면·오류 화면·fixture 자신을 검사하지 않는가. 접근성 e2e가 기능의 빈 목록이 아니라 오류 화면을 검사하고 "passed"로 적은 일이 있다(결함 패턴 T2).
|
||||
|
||||
## 4. 환경에 기대지 않는다
|
||||
|
||||
| 기대는 것 | 증상 | 기준 |
|
||||
| --- | --- | --- |
|
||||
| gitignore된 로컬 생성물 | 깨끗한 clone에서 실패 | 테스트가 필요한 생성물을 스스로 만든다. 한 파일 실행도 `scripts/run-vitest.ts`를 거친다 |
|
||||
| 작성자 PC의 글꼴·CPU | 다른 호스트에서 시각·규모 테스트 실패 | 글꼴은 `fonts.conf`로 고정한다. 규모 테스트는 CPU와 무관한 비교만 단언한다 |
|
||||
| 바깥 env(빌드 식별값, `CI=true`) | 실제 CI에서만 실패 | 테스트가 띄우는 빌드·dev server의 env는 테스트가 정한다([gates.md](gates.md) 4절) |
|
||||
| 고정 출력 경로·고정 포트 | 한 checkout에서 두 실행이 부딪힌다 | 브라우저 테스트는 실행마다 `TEST_RUN_ID`, 서버는 빈 포트. `ci:gate`는 한 checkout에서 하나씩(결함 패턴 G4) |
|
||||
| 호스트 권한(user namespace 등) | 사전 점검 PASS 뒤 원문 오류 | 사전 점검이 본 단계와 같은 방법으로 한 번 실행해 본다([gates.md](gates.md) 5절) |
|
||||
| 옆 checkout(짝 백엔드) | 기계마다 결과가 다르다 | 없으면 "확인 못 함"으로 보고한다 |
|
||||
|
||||
## 5. 가끔 떨어지는 테스트
|
||||
|
||||
**금지.**
|
||||
|
||||
- 재시도, timeout 늘리기, worker 줄이기, `force` 클릭·합성 이벤트로 덮지 않는다.
|
||||
- skip은 Playwright spec에만, owner·defect·route·만료일이 있는 quarantine으로만 둔다(`scripts/check-test-evidence.ts`). 빠른 계층에는 quarantine이 없다. 고치거나 느린 층으로 옮긴다(소유자 결정 2026-11-03).
|
||||
- "부하 탓"으로 닫지 않는다. 부하를 낮춘 재현과 결정적 재현으로 확인하기 전에는 원인이 아니다. 부하 탓으로 적었던 두 실패가 모두 테스트 결함이었다.
|
||||
|
||||
**조사 절차.**
|
||||
|
||||
1. 반복 실행으로 빈도를 잰다. 같은 조건에서 30회씩 돌려 실패 수를 적는다.
|
||||
2. 실패 기록을 남긴다. 이벤트 순서(pointerdown·pointerup·click 대상), 위치, 시각, 네트워크 로그를 실패한 실행에서 모은다. 진단용 코드는 별도 브랜치에 둔다.
|
||||
3. 결정적 재현을 만든다. 원인이라고 본 조건을 강제로 만들어 매번 실패하게 한다. 예: mousedown 때 앱 높이를 늘리면 세 엔진 6/6 실패, 모듈 응답을 3.5초 늦추면 WebKit 경고 2/2.
|
||||
4. 고친다. 고친 뒤 결정적 재현이 통과하고, 실제 조건 반복 실행에서 실패 0인지 본다(예: 660/660).
|
||||
5. 검사가 약해지지 않았는지 변이로 본다. 경고를 무시하게 고쳤으면, 원래 잡아야 할 것(정말 안 쓴 preload)을 여전히 잡는지 확인한다.
|
||||
|
||||
**브라우저 테스트에서 반복된 원인.**
|
||||
|
||||
| 원인 | 예 | 기준 |
|
||||
| --- | --- | --- |
|
||||
| 브라우저의 추정에 기댄다 | WebKit이 load 3초 뒤 한 번 하는 "preload를 안 썼다" 추정. 곧 쓰일 preload로 가끔 실패하고, 정말 안 쓴 preload는 놓쳤다 | 경고 대신 확인하려는 사실(preload가 평가됐는가)을 직접 검사한다(결함 패턴 T4) |
|
||||
| 그리는 중인 화면을 누른다 | 앱 뒤에 붙인 버튼이 렌더링 중 12 px 밀려 클릭이 닿지 않았다 | 테스트가 붙이는 조작 요소는 앱 레이아웃과 무관한 고정 층에 둔다. "다 그려질 때까지 기다리기"는 신호가 없어 쓰지 않는다(결함 패턴 T5) |
|
||||
| 짧은 상태를 폴링으로 잡는다 | 500 ms만 이어지는 `BLOCKED` 상태를 폴링으로 잡으려다 두 엔진에서 실패 | 상태 변화를 이벤트·기록으로 받는다 |
|
||||
| 고정 상한과 첫 실행 비용 | provider 테스트 10개가 10초 상한에 묶이고, 하나만 고르면 첫 테스트가 fixture 빌드를 떠안아 실패 | 무거운 준비는 suite 준비 단계로 옮기고 suite가 자기 timeout을 선언한다 |
|
||||
|
||||
## 6. 테스트 실행 비용
|
||||
|
||||
- 빠른 계층(`tests/unit`)에 프로세스를 띄우는 도구 테스트, 실제 시계로 기다리는 테스트가 섞이면 전체가 느려진다(결함 패턴 T8).
|
||||
- merge 단계가 같은 파일을 두 번 돌리지 않는지 본다.
|
||||
- 긴 드릴은 시간을 함께 적는다. FE-GATE-020은 14~21분(2026-11-06·08 desktop 실측 822~1,245초)이다. job 상한(45분)과의 여유를 본다.
|
||||
@@ -0,0 +1,87 @@
|
||||
# 조사·설계 — 바꾸기 전에 대안을 비교하고 결정을 받는다
|
||||
|
||||
코드를 바꾸기 전에 무엇을 할지 정하는 일이다. 사고 순서(목적 → 선행 사례 → 방법 → 필요한 정보 → 격차 → 만들고 시험)의 정본은 design-docs `conventions/work-thinking-order.md`다. 이 playbook은 순서를 다시 쓰지 않고, 이 repo에서 어디를 보고 결과를 어디에 두는지만 정한다.
|
||||
|
||||
## 1. 언제 쓰나
|
||||
|
||||
- 고치거나 만들기 전에 소유자 결정이 필요하다: import 규칙, adapter 배럴의 공개 표면, 게이트 단계·기준, 짝 백엔드 계약, 런타임 설정 키, 파생 프로젝트 동작, 보안 정책, 되돌리기 비싼 선택.
|
||||
- 리뷰가 「결정이 필요한 것」으로 남긴 항목을 어떻게 닫을지 정해야 한다.
|
||||
- 큰 일의 1~5단계와 대안 비교를 소유자 검토용으로 만든다. 설계 메모 하나를 쓴다.
|
||||
- 결정이 이미 [reference/decisions.md](reference/decisions.md)에 있으면 이 playbook이 아니다. 그 결정대로 [improve.md](improve.md)나 [new-feature.md](new-feature.md)로 간다.
|
||||
|
||||
## 2. 받아야 할 것
|
||||
|
||||
- 정할 질문 한 문장과 누가 왜 묻는가(요청 원문).
|
||||
- 크기와 결정할 사람. 큼이면 소유자 검토가 만들기 전에 있어야 한다.
|
||||
- 산출물 위치(4절 7단계 기준과 다르면 brief를 따른다). 코드를 바꿔도 되는지. 기본은 바꾸지 않는다.
|
||||
|
||||
## 3. 크기와 사고 순서
|
||||
|
||||
- 설계 메모 하나는 보통 중간이다: 선행 사례 2~3곳(내부 선례 포함), 대안 2~3개. 다루는 대상이 [README](README.md) 2절의 "파일 하나여도 큼" 표면이어도 메모만 쓰고 바꾸지 않으면 중간이다. 큼은 그 메모를 적용하는 일이다.
|
||||
- 새 체계·아키텍처·공개 계약은 큼이다: 선행 사례 10~15곳, 대안 3~5개. 1~5단계 결과와 대안 비교를 소유자가 먼저 본다.
|
||||
- 이 repo의 내부 선례를 찾는 곳:
|
||||
- [reference/decisions.md](reference/decisions.md)와 그 출처 문서
|
||||
- `docs/reviews/`의 리뷰 README 「결정이 필요한 것」「조치」 절
|
||||
- `docs/architecture/decisions/`(오래 가는 구조·기술 선택), `docs/architecture/`의 설계 문서(현재 계약인지 목표 설계인지는 `docs/README.md` 묶음으로 본다)
|
||||
- `git log --oneline -- <경로>`와 커밋 본문의 "고른 방법과 버린 대안"
|
||||
- 규칙 예외의 이유·담당·재검토 조건: 그 규칙의 `comment`(`.dependency-cruiser.json`)
|
||||
- 외부 선례: 쓰는 라이브러리의 공식 문서와 릴리스 노트(React, Vite, TanStack Query, Playwright 등), 같은 문제를 다룬 공개 저장소. 직접 쓴 글(1차)인지 정리한 글(2차)인지 표시한다.
|
||||
- 스킬: `superpowers:brainstorming`, 결정 기록은 `documentation-and-adrs`, 공식 문서 확인은 `source-driven-development`. 큰 판단은 `doubt-driven-development`로 반론을 세운다.
|
||||
|
||||
## 4. 절차
|
||||
|
||||
1. 목적을 한 문장으로 적고 성공 기준을 정한다. 요청 원문이 있으면 인용한다.
|
||||
2. 이미 정한 것을 찾는다(3절의 내부 선례). 이미 정해져 있으면 멈추고 그 결정을 보고한다.
|
||||
3. 현황을 확인한다. 주장마다 출처를 단다: `file:line`, 커밋, 명령 결과. 확인한 사실 / 기록된 의도 / 추론을 나눈다(리뷰 가이드 41.3절). 코드 읽기로 동작이 하나로 정해지지 않으면 별도 worktree에서 탐침 테스트를 desktop으로 돌리고(`scripts/verify.sh script`), 탐침 코드는 남기지 않는다.
|
||||
4. 선행 사례 표를 만든다: 출처 · 1차/2차 · 그들이 한 것 · 실패와 비판 · 가져올 것.
|
||||
5. 대안을 비교한다. 실제로 다른 대안 2~5개(크기에 맞게), 기준(효과, 비용, 되돌리기, 파생 프로젝트 영향, 기존 결정과 충돌, 초기 JS·예산 영향), 권하는 안과 이유. 파생 프로젝트 영향은 그 repo에서 바꿀 이름(파일, 키, 타입)을 `git grep`해 쓰는 곳을 센다.
|
||||
6. 반증할 수 있는 가정을 적는다: "이 안이 틀렸다면 어디서 드러나나". 재검토 조건(어떤 규모·버전·계약 변화가 결론을 바꾸나)과 반론·답도 적는다.
|
||||
7. 산출물을 둔다.
|
||||
- 이 repo에만 해당하고 오래 가는 선택: `docs/architecture/decisions/`의 결정 기록(기존 번호를 잇는다, 머리 블록은 `docs/README.md`).
|
||||
- 여러 repo나 소유자 운영에 걸침: design-docs. 템플릿 `docs/`는 파생 프로젝트로 복사되므로 로드맵·운영 설계는 여기에 두지 않는다.
|
||||
- 짧은 설계 메모는 보고 본문으로 충분하다(brief가 파일을 요구하지 않으면).
|
||||
8. 소유자 결정 목록을 쓴다: 항목 · 선택지 · 권하는 안과 이유 · 정할 사람. 한 번에 묻는다.
|
||||
9. 멈추고 검토를 받는다. 승인을 받으면 승인 시각을 적는다.
|
||||
10. 결정을 기록한다([reference/decisions.md](reference/decisions.md) 3절). 만들기는 [new-feature.md](new-feature.md)나 [improve.md](improve.md)로 넘긴다.
|
||||
|
||||
## 5. 완료 기준
|
||||
|
||||
- 보고에 사고 순서 흔적이 있다. 크기에 맞는 단계가 있고, 생략한 단계는 이유가 한 줄 있다.
|
||||
- 사실마다 출처(`file:line`, 커밋, 명령 결과)가 있다. 추정은 추정이라고 적었다.
|
||||
- 대안 비교 표, 권하는 안, 반증할 수 있는 가정, 재검토 조건이 있다.
|
||||
- 소유자 결정 목록이 있고, 질문을 보냈거나 승인 시각이 있다.
|
||||
- brief가 허용하지 않았으면 코드가 바뀌지 않았다(`git diff --stat`에 문서만).
|
||||
|
||||
## 6. 하지 말 것
|
||||
|
||||
- 소유자 검토 전에 만들지 않는다. 큰 일은 1~5단계와 대안 비교까지만 하고 멈춘다.
|
||||
- 크기를 스스로 내리지 않는다. 이미 정한 결정을 다시 묻지 않는다(다시 열 조건은 [reference/decisions.md](reference/decisions.md) 1절).
|
||||
- "업계 표준이다", "추상화가 많다" 같은 말을 근거로 쓰지 않는다. 이 repo의 어느 계약·비용에 닿는지로 쓴다.
|
||||
- 대안을 하나만 놓고 권하지 않는다. 탐침 코드를 제품 코드에 남기지 않는다.
|
||||
|
||||
## 7. 막혔을 때
|
||||
|
||||
- 필요한 정보가 이 repo와 공개 자료에 없으면(운영 수치, 소유자의 계획) 그 칸을 "모름"으로 두고 질문 목록에 넣는다.
|
||||
- 질문은 한 번에 모아 보낸다. 형식은 [README](README.md) 5절이다. 답이 올 때까지 그 결정에 기대는 단계만 멈춘다.
|
||||
|
||||
## 8. 보고 형식
|
||||
|
||||
[README](README.md) 6절에 더해 적는다.
|
||||
|
||||
```markdown
|
||||
## 결론 (권하는 안 한 문장)
|
||||
## 사고 순서 흔적 (크기: 중간)
|
||||
1. 목적: 2. 선행 사례: 3. 방법: 4. 필요한 정보: 5. 격차: 6. 만들고 시험:
|
||||
## 대안 비교
|
||||
| 대안 | 효과 | 비용 | 되돌리기 | 기존 결정과 충돌 |
|
||||
## 반증할 수 있는 가정 / 재검토 조건 / 반론과 답
|
||||
## 소유자가 정할 것
|
||||
| 항목 | 선택지 | 권하는 안과 이유 | 정할 사람 |
|
||||
```
|
||||
|
||||
## 9. 자주 하는 실수
|
||||
|
||||
- 정리한 글(2차)을 원문처럼 인용한다. 원문을 찾아 확인하고 1차/2차를 표시한다.
|
||||
- 지난 리뷰의 결정을 찾지 않아 같은 질문을 다시 한다. 결정 색인과 리뷰 README 「결정」 절부터 본다.
|
||||
- 짝 백엔드 사실을 계약 문서 문장만으로 정한다. 백엔드 코드와 이 repo의 pin(`config/contracts/backend-contract-pin.json`)까지 따라간다.
|
||||
- 조사하다 바로 고친다. 고치는 일은 결정 뒤에 다른 playbook으로 한다.
|
||||
Executable
+358
@@ -0,0 +1,358 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Fail when the work manual stops being readable without history or grows past its size limits.
|
||||
|
||||
The work manual is the root `AGENTS.md` (the map and the rules that must hold) plus `docs/work/`. A
|
||||
Claude Code session reads the map through the root `CLAUDE.md`, which imports it (`@AGENTS.md`) and
|
||||
adds a few Claude-only lines. A session that has never seen this repository's history reads the map,
|
||||
`docs/work/README.md` and one playbook, and must be able to finish the job from those alone. Two
|
||||
things break that, and both are mechanical:
|
||||
|
||||
1. History IDs in the body. A sentence such as "fixed as in 1103/11-07" means nothing to a reader
|
||||
who does not know that review. History belongs in `docs/work/evidence.md` and the two reference
|
||||
files that are indexes of history (`reference/decisions.md`, `reference/defect-patterns.md`). The
|
||||
same rule covers the other files a new session reads first: the root `AGENTS.md` and `CLAUDE.md`,
|
||||
every folder rule book `src/**/AGENTS.md` and the documents under `.claude/` (rules, skills,
|
||||
subagents). Review documents keep their IDs.
|
||||
2. Length. Each entry file has a line limit and the entry path (map + root `CLAUDE.md` + README +
|
||||
one playbook) has a total limit, so a session reads the whole path instead of skimming it. The
|
||||
map limit is 40 lines (owner decision 2026-11-07: the root holds the rules, the map and the
|
||||
router only).
|
||||
|
||||
It also checks that every playbook keeps the shared nine-section skeleton, that the "common
|
||||
mistakes" section stays short, that `CLAUDE.md` starts with the import, that every folder rule book
|
||||
`src/**/AGENTS.md` has a `CLAUDE.md` beside it that only imports it (so Claude Code reads the same
|
||||
book) and stays under 200 lines, and that relative links in the checked files resolve. The same layout and limits as the paired backend template's checker.
|
||||
|
||||
Standard library only, so it runs on the laptop and in the edit hook (scripts/hooks/hooks.py, N2).
|
||||
`verify:documentation` (FE-GATE-017) checks the paths, scripts and gate IDs these documents name.
|
||||
|
||||
python3 scripts/check-work-docs.py
|
||||
python3 scripts/check-work-docs.py --links docs README.md # relative links only, any files
|
||||
python3 scripts/check-work-docs.py --history docs/manual # history IDs only, any files
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parent.parent
|
||||
MAP = REPO_ROOT / "AGENTS.md"
|
||||
CLAUDE_ENTRY = REPO_ROOT / "CLAUDE.md"
|
||||
IMPORT_LINE = "@AGENTS.md"
|
||||
CLAUDE_FOLDERS = ("rules", "skills", "agents")
|
||||
WORK = REPO_ROOT / "docs/work"
|
||||
README = WORK / "README.md"
|
||||
|
||||
PLAYBOOKS = [
|
||||
"new-feature.md",
|
||||
"improve.md",
|
||||
"research-design.md",
|
||||
"docs-writing.md",
|
||||
"operate.md",
|
||||
"delegate.md",
|
||||
]
|
||||
REFERENCES = [
|
||||
"reference/gates.md",
|
||||
"reference/review-criteria.md",
|
||||
"reference/structure.md",
|
||||
"reference/testing.md",
|
||||
"reference/performance.md",
|
||||
"reference/defect-patterns.md",
|
||||
"reference/decisions.md",
|
||||
]
|
||||
EVIDENCE = "evidence.md"
|
||||
|
||||
# Files that may name history, relative to docs/work/. Everything else must not.
|
||||
HISTORY_ALLOWED = {EVIDENCE, "reference/decisions.md", "reference/defect-patterns.md"}
|
||||
|
||||
MAP_LIMIT = 40
|
||||
CLAUDE_ENTRY_LIMIT = 15
|
||||
README_LIMIT = 80
|
||||
PLAYBOOK_LIMIT = 150
|
||||
ENTRY_PATH_LIMIT = 350
|
||||
MISTAKES_LIMIT = 10
|
||||
# A folder rule book is read whole whenever a file in that folder is opened (Claude Code: under 200).
|
||||
MODULE_GUIDE_LIMIT = 200
|
||||
SKIPPED_PARTS = {"node_modules", ".generated", "dist"}
|
||||
|
||||
SKELETON = [
|
||||
"1. 언제 쓰나",
|
||||
"2. 받아야 할 것",
|
||||
"3. 크기와 사고 순서",
|
||||
"4. 절차",
|
||||
"5. 완료 기준",
|
||||
"6. 하지 말 것",
|
||||
"7. 막혔을 때",
|
||||
"8. 보고 형식",
|
||||
"9. 자주 하는 실수",
|
||||
]
|
||||
|
||||
# Each pattern names a kind of history identifier. A match is a sentence that only a reader who
|
||||
# knows the past can follow. re.ASCII keeps \b and \w to ASCII: Python counts Korean letters as
|
||||
# word characters, so "1105/12-01과" would otherwise slip through.
|
||||
HISTORY_PATTERNS = [
|
||||
("review ID with a date prefix (MMDD/NN-MM)",
|
||||
re.compile(r"(?<![\w./-])(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01])/[\w-]", re.ASCII)),
|
||||
("review README named by its date (1105 README)",
|
||||
re.compile(r"(?<![\w./-])(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01]) (?:README|조치|리뷰)", re.ASCII)),
|
||||
("review round folder name (round6)", re.compile(r"\bround\d+\b", re.ASCII)),
|
||||
# A finding number written after the word for review or round: "리뷰 02-01", "review 12-03".
|
||||
("finding number after a review or round word (리뷰 02-01)",
|
||||
re.compile(r"(?:리뷰|라운드|(?<![A-Za-z])[Rr]eview)[^|()\n]{0,20}?(?<![\w./-])\d{2}-\d{2}(?![\w-])",
|
||||
re.ASCII)),
|
||||
# Finding numbers listed with no word in front: "(05-01, 04-01)". One bare NN-NN stays allowed,
|
||||
# because a lone pair is often an ordinary range or chapter number.
|
||||
("list of finding numbers (05-01, 04-01)",
|
||||
re.compile(r"(?<![\w./:,-])\d{2}-\d{2}(?:, |·)\d{2}-\d{2}(?![\w-])", re.ASCII)),
|
||||
# A count of rounds ("3라운드마다") is not a name for one past round.
|
||||
("round number in Korean (4라운드, 라운드6)",
|
||||
re.compile(r"(?<![\w.~-])\d{1,2} ?라운드(?! ?(?:동안|마다|씩|간))|라운드 ?\d{1,2}(?![\w.])", re.ASCII)),
|
||||
("review README section number (리뷰 README 13절)", re.compile(r"리뷰 README \d", re.ASCII)),
|
||||
# A decision named by its date ("owner decision 2026-11-06") is content plus a date, not a number.
|
||||
("decision named by number only",
|
||||
re.compile(r"결정 ?(?!\d{4}-)(?:\d+|[①-⑳])(?!\s*(?:개|건|가지|번째))"
|
||||
r"|(?<![A-Za-z])[Dd]ecision (?!\d{4}-)\d+", re.ASCII)),
|
||||
# The improvement manual's own numbers: decisions M-3, owner orders O-12, round defaults D-14, and
|
||||
# the defect pattern catalogue P-43.
|
||||
("old manual number (M-3, O-12, D-14, P-43)", re.compile(r"\b[MODP]-\d{1,2}\b", re.ASCII)),
|
||||
("design decision number (D5)", re.compile(r"\bD\d{1,2}\b", re.ASCII)),
|
||||
("finding number with its chosen option (03-11 (b))",
|
||||
re.compile(r"(?<![\w./:-])\d{2}-\d{2} \([a-e]\)", re.ASCII)),
|
||||
("commit sha", re.compile(r"\b(?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{7,40}\b", re.ASCII)),
|
||||
]
|
||||
|
||||
LINK = re.compile(r"\[[^\]]*\]\(([^)\s]+)\)", re.ASCII)
|
||||
|
||||
|
||||
def rel(path: Path) -> str:
|
||||
return path.relative_to(REPO_ROOT).as_posix()
|
||||
|
||||
|
||||
def line_count(path: Path) -> int:
|
||||
return len(path.read_text(encoding="utf-8").splitlines())
|
||||
|
||||
|
||||
def check_exists(errors: list[str]) -> bool:
|
||||
expected = [MAP, CLAUDE_ENTRY, README, WORK / EVIDENCE]
|
||||
expected += [WORK / name for name in PLAYBOOKS + REFERENCES]
|
||||
missing = [rel(path) for path in expected if not path.is_file()]
|
||||
for name in missing:
|
||||
errors.append(f"{name}: missing")
|
||||
return not missing
|
||||
|
||||
|
||||
def check_limits(errors: list[str], report: list[str]) -> None:
|
||||
for path, limit in [(MAP, MAP_LIMIT), (CLAUDE_ENTRY, CLAUDE_ENTRY_LIMIT), (README, README_LIMIT)]:
|
||||
lines = line_count(path)
|
||||
report.append(f"{rel(path)}: {lines}/{limit}")
|
||||
if lines > limit:
|
||||
errors.append(f"{rel(path)}: {lines} lines, limit {limit}")
|
||||
base = line_count(MAP) + line_count(CLAUDE_ENTRY) + line_count(README)
|
||||
for name in PLAYBOOKS:
|
||||
path = WORK / name
|
||||
lines = line_count(path)
|
||||
entry = base + lines
|
||||
report.append(f"{rel(path)}: {lines}/{PLAYBOOK_LIMIT}, entry path {entry}/{ENTRY_PATH_LIMIT}")
|
||||
if lines > PLAYBOOK_LIMIT:
|
||||
errors.append(f"{rel(path)}: {lines} lines, limit {PLAYBOOK_LIMIT}")
|
||||
if entry > ENTRY_PATH_LIMIT:
|
||||
errors.append(
|
||||
f"{rel(path)}: entry path AGENTS.md + CLAUDE.md + docs/work/README.md + this file is {entry} lines,"
|
||||
f" limit {ENTRY_PATH_LIMIT}"
|
||||
)
|
||||
|
||||
|
||||
def outside_code_blocks(lines: list[str]) -> list[str]:
|
||||
"""Blank out fenced code blocks, so an example such as a report template is not a section."""
|
||||
kept: list[str] = []
|
||||
fenced = False
|
||||
for line in lines:
|
||||
if line.lstrip().startswith("```"):
|
||||
fenced = not fenced
|
||||
kept.append("")
|
||||
else:
|
||||
kept.append("" if fenced else line)
|
||||
return kept
|
||||
|
||||
|
||||
def check_skeleton(errors: list[str]) -> None:
|
||||
for name in PLAYBOOKS:
|
||||
path = WORK / name
|
||||
lines = outside_code_blocks(path.read_text(encoding="utf-8").splitlines())
|
||||
headings = [line[3:].strip() for line in lines if line.startswith("## ")]
|
||||
if headings != SKELETON:
|
||||
errors.append(f"{rel(path)}: sections must be exactly {SKELETON} in that order, found {headings}")
|
||||
continue
|
||||
start = lines.index("## " + SKELETON[-1])
|
||||
items = [line for line in lines[start + 1:] if re.match(r"^(?:[-*]|\d+\.) ", line)]
|
||||
if len(items) > MISTAKES_LIMIT:
|
||||
errors.append(
|
||||
f"{rel(path)}: '{SKELETON[-1]}' has {len(items)} items, limit {MISTAKES_LIMIT}"
|
||||
" (move one to a reference file or delete one)"
|
||||
)
|
||||
|
||||
|
||||
def check_claude_entry(errors: list[str]) -> None:
|
||||
"""The root CLAUDE.md starts with the import, so a Claude Code session reads the map."""
|
||||
lines = CLAUDE_ENTRY.read_text(encoding="utf-8").splitlines()
|
||||
if not lines or lines[0].strip() != IMPORT_LINE:
|
||||
errors.append(f"{rel(CLAUDE_ENTRY)}: the first line must be '{IMPORT_LINE}'")
|
||||
|
||||
|
||||
def module_guides() -> list[Path]:
|
||||
"""Every src/**/AGENTS.md, the local rule book of a layer folder."""
|
||||
return sorted(path for path in (REPO_ROOT / "src").rglob("AGENTS.md")
|
||||
if not SKIPPED_PARTS.intersection(path.relative_to(REPO_ROOT).parts))
|
||||
|
||||
|
||||
def check_guides(errors: list[str], report: list[str]) -> None:
|
||||
longest = 0
|
||||
for guide in module_guides():
|
||||
lines = line_count(guide)
|
||||
longest = max(longest, lines)
|
||||
if lines > MODULE_GUIDE_LIMIT:
|
||||
errors.append(f"{rel(guide)}: {lines} lines, limit {MODULE_GUIDE_LIMIT}")
|
||||
if not guide.with_name("CLAUDE.md").is_file():
|
||||
errors.append(f"{rel(guide.with_name('CLAUDE.md'))}: missing; it must be the one line '{IMPORT_LINE}'")
|
||||
for entry in sorted(path for path in (REPO_ROOT / "src").rglob("CLAUDE.md")
|
||||
if not SKIPPED_PARTS.intersection(path.relative_to(REPO_ROOT).parts)):
|
||||
lines = [line.strip() for line in entry.read_text(encoding="utf-8").splitlines() if line.strip()]
|
||||
if lines != [IMPORT_LINE]:
|
||||
errors.append(f"{rel(entry)}: must be exactly '{IMPORT_LINE}'; the rules live in AGENTS.md beside it")
|
||||
if not entry.with_name("AGENTS.md").is_file():
|
||||
errors.append(f"{rel(entry)}: imports {rel(entry.with_name('AGENTS.md'))}, which does not exist")
|
||||
report.append(f"src/**/AGENTS.md: {len(module_guides())} files, longest {longest}/{MODULE_GUIDE_LIMIT}")
|
||||
|
||||
|
||||
def claude_documents() -> list[Path]:
|
||||
"""The tracked Claude Code documents a session reads: path rules, skills, subagent definitions.
|
||||
Only these folders: the rest of .claude/ is local state (worktrees, hook state, settings.local.json)."""
|
||||
return sorted(path for folder in CLAUDE_FOLDERS for path in (REPO_ROOT / ".claude" / folder).rglob("*.md"))
|
||||
|
||||
|
||||
def history_checked_files() -> list[Path]:
|
||||
files = [MAP, CLAUDE_ENTRY] + claude_documents() + module_guides()
|
||||
for path in sorted(WORK.rglob("*.md")):
|
||||
if path.relative_to(WORK).as_posix() not in HISTORY_ALLOWED:
|
||||
files.append(path)
|
||||
return files
|
||||
|
||||
|
||||
def history_match(line: str, following: str) -> tuple[str, str] | None:
|
||||
"""The first history ID on this line, or one that a line break splits ("review\n1103/11-07")."""
|
||||
for label, pattern in HISTORY_PATTERNS:
|
||||
match = pattern.search(line)
|
||||
if match:
|
||||
return label, match.group(0)
|
||||
if not following.strip():
|
||||
return None
|
||||
joined = line.rstrip() + " " + following.strip()
|
||||
for label, pattern in HISTORY_PATTERNS:
|
||||
for match in pattern.finditer(joined):
|
||||
if match.start() < len(line.rstrip()) < match.end():
|
||||
return label, match.group(0)
|
||||
return None
|
||||
|
||||
|
||||
def history_hits(files: list[Path]) -> list[tuple[Path, int, str, str]]:
|
||||
hits = []
|
||||
for path in files:
|
||||
lines = path.read_text(encoding="utf-8").splitlines()
|
||||
for number, line in enumerate(lines, start=1):
|
||||
found = history_match(line, lines[number] if number < len(lines) else "")
|
||||
if found:
|
||||
hits.append((path, number, *found))
|
||||
return hits
|
||||
|
||||
|
||||
def broken_links(files: list[Path]) -> tuple[int, list[tuple[Path, int, str]]]:
|
||||
checked = 0
|
||||
broken = []
|
||||
for path in files:
|
||||
for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
|
||||
for target in LINK.findall(line):
|
||||
if re.match(r"^[a-z][a-z0-9+.-]*:", target) or target.startswith("#"):
|
||||
continue
|
||||
checked += 1
|
||||
if not (path.parent / target.split("#", 1)[0]).exists():
|
||||
broken.append((path, number, target))
|
||||
return checked, broken
|
||||
|
||||
|
||||
def check_history(errors: list[str], report: list[str]) -> None:
|
||||
hits = history_hits(history_checked_files())
|
||||
for path, number, label, text in hits:
|
||||
errors.append(
|
||||
f"{rel(path)}:{number}: {label} '{text}'"
|
||||
" - write the content instead, and move the ID to docs/work/evidence.md"
|
||||
)
|
||||
report.append(f"history ID lines in checked files: {len(hits)}")
|
||||
|
||||
|
||||
def check_links(errors: list[str], report: list[str]) -> None:
|
||||
checked, broken = broken_links([MAP, CLAUDE_ENTRY] + sorted(WORK.rglob("*.md")) + claude_documents()
|
||||
+ module_guides())
|
||||
for path, number, target in broken:
|
||||
errors.append(f"{rel(path)}:{number}: broken relative link '{target}'")
|
||||
report.append(f"relative links checked: {checked}")
|
||||
|
||||
|
||||
def markdown_files(targets: list[str]) -> list[Path]:
|
||||
files: list[Path] = []
|
||||
for target in targets:
|
||||
path = (Path.cwd() / target).resolve()
|
||||
files += sorted(path.rglob("*.md")) if path.is_dir() else [path]
|
||||
return files
|
||||
|
||||
|
||||
def links_only(targets: list[str]) -> int:
|
||||
files = markdown_files(targets)
|
||||
checked, broken = broken_links(files)
|
||||
print(f"files: {len(files)}, relative links checked: {checked}, broken: {len(broken)}")
|
||||
for path, number, target in broken:
|
||||
print(f" {path}:{number}: broken relative link '{target}'", file=sys.stderr)
|
||||
return 1 if broken else 0
|
||||
|
||||
|
||||
def history_only(targets: list[str]) -> int:
|
||||
files = markdown_files(targets)
|
||||
hits = history_hits(files)
|
||||
print(f"files: {len(files)}, lines with history IDs: {len(hits)}")
|
||||
for path, number, label, text in hits:
|
||||
print(f" {path}:{number}: {label} '{text}'", file=sys.stderr)
|
||||
return 1 if hits else 0
|
||||
|
||||
|
||||
MODES = {"--links": links_only, "--history": history_only}
|
||||
|
||||
|
||||
def main() -> int:
|
||||
if sys.argv[1:2] and sys.argv[1] in MODES:
|
||||
if len(sys.argv) < 3:
|
||||
print(f"usage: check-work-docs.py {sys.argv[1]} <file or directory>...", file=sys.stderr)
|
||||
return 2
|
||||
return MODES[sys.argv[1]](sys.argv[2:])
|
||||
errors: list[str] = []
|
||||
report: list[str] = []
|
||||
if check_exists(errors):
|
||||
check_limits(errors, report)
|
||||
check_claude_entry(errors)
|
||||
check_guides(errors, report)
|
||||
check_skeleton(errors)
|
||||
check_history(errors, report)
|
||||
check_links(errors, report)
|
||||
for line in report:
|
||||
print(line)
|
||||
if errors:
|
||||
print(f"\nFAILED: {len(errors)} problem(s)", file=sys.stderr)
|
||||
for error in errors:
|
||||
print(f" {error}", file=sys.stderr)
|
||||
return 1
|
||||
print("\nOK")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -0,0 +1,46 @@
|
||||
# repo 훅
|
||||
|
||||
Claude Code가 정해진 때에 대신 실행하는 명령이다. 연결은 `.claude/settings.json`, 본체는 `hooks.py` 하나, 시험은 `scripts/tests/test_hooks.py`다. 모델이 잊어도 돈다.
|
||||
|
||||
```text
|
||||
Edit·Write 직후 ──> post-edit ──> src TypeScript면 N3 경계 알림, 테스트·기준 파일이면 N6 게이트 기준 알림, 문서면 N2 문서 검사 알림
|
||||
Bash 직후 ──> post-bash ──> desktop에서 pnpm·게이트를 돌렸으면 N5 기록을 비운다
|
||||
턴 끝 ──> stop ──> N5 desktop이 확인해야 할 파일을 고쳤는데 desktop 실행이 없으면 한 번 알린다
|
||||
```
|
||||
|
||||
## 1. 원칙
|
||||
|
||||
- 막지 않는다. 모두 알리기만 한다(넛지). 알림은 종료 코드 0이고, 모델 컨텍스트에 몇 줄(최대 5줄)만 더한다. 이 repo 안에서 편집 하나가 되돌릴 수 없는 일을 하지 않아서, 편집 전 차단 훅은 없다. 되돌릴 수 없는 명령 차단(force push, 범위 밖 `rm -rf`, DB·볼륨 삭제)과 비밀 값 알림은 repo가 아니라 소유자 전역 훅과 하네스 플러그인 `harness@claude-harness` 몫이다.
|
||||
- 훅은 게이트의 일부만 본다. 정본은 게이트(desktop `check:architecture`, `lint`, `check:types`, `verify:documentation`)다. 훅이 틀리면 훅을 고치거나 끄고, 게이트는 그대로 둔다.
|
||||
- 노트북에서 pnpm·node·eslint·브라우저를 돌리지 않는다. 포맷·린트·타입 검사는 desktop의 `scripts/verify.sh`에서 돈다(소유자 결정 2026-11-08, `docs/work/reference/decisions.md`). 그래서 편집 직후 훅은 Python 표준 라이브러리와 git만 쓰는 정적 검사이고, 1초 안에 끝난다.
|
||||
- 받거나 설치하지 않는다. 의존성이 없다.
|
||||
|
||||
## 2. 훅마다
|
||||
|
||||
| ID | 때 | 하는 일 | 결과 |
|
||||
| --- | --- | --- | --- |
|
||||
| N3 | PostToolUse `Edit\|Write\|MultiEdit`, `src/**/*.{ts,tsx}`(`.d.ts` 제외) | 편집한 파일의 import(정적·type-only·re-export·리터럴 dynamic import·require)를 경로로 풀고, `.dependency-cruiser.json`의 `forbidden` 규칙(`from`·`to`의 `path`·`pathNot`, `$1` 치환)에 대 본다. 사이클 규칙은 그래프 전체가 필요해 보지 않는다 | 「꼭 지킬 것 N 의심」 줄(규칙 이름과 import), 정본 게이트 안내 |
|
||||
| N6 | 같은 때, 테스트 파일(`tests/**`, `*.test.*`·`*.spec.*`·`*.stories.*`) | 마지막 커밋(`git show HEAD:<path>`)보다 `.skip`·`.only`·`.fixme`·`.todo`가 늘었는지 센다 | 늘어난 수와 「꼭 지킬 것 4」 |
|
||||
| N6 | 같은 때, 게이트 기준 파일(`config/performance/budgets.json`, `config/scale/`, `config/testing/`, `config/ci/ungated-*.json`, `config/**/*baseline*.json`, `vitest.config.ts`, 스냅숏) | 편집 자체를 알린다 | 「게이트의 기준 파일」 한 줄과 「꼭 지킬 것 4」 |
|
||||
| N2 | 같은 때, `*.md` | `scripts/check-work-docs.py`를 돌린다(작업 매뉴얼의 분량·이력 ID·뼈대·상대 링크) | 실패 줄. 고친 문서를 가리키는 줄이 있으면 그것만 |
|
||||
| N5 | Stop | 이 세션에서 desktop만 확인할 수 있는 파일(아래 밖의 모든 파일)을 고친 뒤 desktop 실행이 없으면 턴을 한 번 막고 이유를 준다 | `decision: block`, 다음 편집 전까지 한 번 |
|
||||
|
||||
- N5가 "desktop 실행"으로 치는 것: `ssh <desktop 호스트> …`로 pnpm·`ci:gate`·`verify.sh`·vitest·playwright·`node scripts/…`를 돌린 명령, 또는 `scripts/verify.sh`를 `docs`·`hooks` 밖 단계로(`--on here` 없이) 돌린 명령.
|
||||
- N5가 세지 않는 파일(노트북에서 확인되는 것): `.claude/`, `scripts/hooks/`, `scripts/tests/`, `scripts/check-work-docs.py`, `docs/ledger/`, `CLAUDE.md`, `src/**/AGENTS.md`·`CLAUDE.md`. 이것들은 `scripts/verify.sh docs`·`hooks`가 노트북에서 본다.
|
||||
- N5가 기억하는 것은 `.claude/hook-state/<session_id>.json`이다(git이 무시한다).
|
||||
- 권한 쪽 차단: `.claude/settings.json`의 `permissions.deny`가 실제 `.env`·`.env.local`·`.env.*.local`·`.env.<mode>` 읽기·쓰기를 막는다. `.env.example`은 막지 않는다.
|
||||
|
||||
## 3. 시험
|
||||
|
||||
```bash
|
||||
scripts/verify.sh hooks
|
||||
```
|
||||
|
||||
- `python3 -m unittest discover -s scripts/tests`와 같다. 노트북에서 돈다.
|
||||
- 고장 낸 입력(배럴 밖 import, kernel 밖 adapter 간 import, 늘어난 `.only`, 깨진 링크)에서 알림이 나오고, 맞는 입력에서 조용한지 본다. N3는 실제 `.dependency-cruiser.json`과 `src/` 전체에서 알림이 0인지도 본다(거짓 양성 시험).
|
||||
- 훅을 고치면 조건을 끈 사본에서도 시험이 실패하는지 본다(변이 시험). 조건 하나를 끄는 것마다 시험 하나 이상이 실패해야 한다.
|
||||
- 이 시험은 아직 CI workflow가 부르지 않는다. 훅·검사기를 고친 PR은 보고에 `scripts/verify.sh hooks` 결과를 적는다.
|
||||
|
||||
## 4. 끄기
|
||||
|
||||
훅이 시끄럽거나 틀리면 `.claude/settings.json`에서 그 항목을 지우고, 이유를 커밋 본문에 쓴다. 개인적으로만 끄려면 `.claude/settings.local.json`(git이 무시한다)에 `"disableAllHooks": true`를 둔다.
|
||||
Executable
+375
@@ -0,0 +1,375 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Claude Code repo hooks: nudge right after an edit, remind at the end of a turn.
|
||||
|
||||
Called by `.claude/settings.json`, one event per invocation, with the hook input JSON on stdin:
|
||||
|
||||
python3 scripts/hooks/hooks.py post-edit # PostToolUse Edit|Write|MultiEdit N3, N6, N2
|
||||
python3 scripts/hooks/hooks.py post-bash # PostToolUse Bash records desktop runs
|
||||
python3 scripts/hooks/hooks.py stop # Stop N5
|
||||
|
||||
What each ID does, and why it nudges instead of blocking, is in scripts/hooks/README.md. A nudge
|
||||
exits 0 and adds at most a few lines to the model's context. No hook blocks an edit: nothing an edit
|
||||
does inside this repository is irreversible, and the commands that are (force push, wide `rm -r`)
|
||||
are the owner's global hook and the harness plugin. No hook runs pnpm, node, eslint or a browser:
|
||||
the owner's laptop never does (docs/work/operate.md 4.1). The format, lint and type checks run on
|
||||
the desktop through scripts/verify.sh. Standard library and git only. The tests are
|
||||
scripts/tests/test_hooks.py.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import shlex
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
RULES = ".dependency-cruiser.json"
|
||||
STATE_DIR = ".claude/hook-state"
|
||||
EDIT_TOOLS = ("Edit", "Write", "MultiEdit")
|
||||
MAX_LINES = 5
|
||||
|
||||
# --- N3: the import rules check:architecture holds, checked on the imports of one edited source -----------
|
||||
SOURCE = re.compile(r"^src/.+\.(?:ts|tsx|mts|cts)$")
|
||||
# Static imports and re-exports (type-only ones too: the architecture graph counts them), side-effect
|
||||
# imports, dynamic import() with a literal and require() with a literal.
|
||||
SPECIFIER = re.compile(
|
||||
r"""(?:^|[\s;}])(?:import|export)\s+[^'"`;]*?\bfrom\s*['"]([^'"\n]+)['"]"""
|
||||
r"""|(?:^|[\s;])import\s*['"]([^'"\n]+)['"]"""
|
||||
r"""|\bimport\s*\(\s*['"]([^'"\n]+)['"]\s*\)"""
|
||||
r"""|\brequire\s*\(\s*['"]([^'"\n]+)['"]\s*\)""",
|
||||
re.M | re.S,
|
||||
)
|
||||
RESOLVE_SUFFIXES = ("", ".ts", ".tsx", ".mts", ".js", ".jsx", "/index.ts", "/index.tsx")
|
||||
# Which of AGENTS.md's "꼭 지킬 것" a broken rule is; every other rule is item 3 (the import rules).
|
||||
RULE_ITEMS = {
|
||||
"adapter-groups-are-reached-through-their-barrel": "꼭 지킬 것 1",
|
||||
"adapters-do-not-know-other-concrete-adapters": "꼭 지킬 것 2",
|
||||
}
|
||||
|
||||
# --- N6: gate standards that an edit can lower -------------------------------------------------------------
|
||||
TEST_SOURCE = re.compile(r"(?:^tests/.+|\.(?:test|spec|stories)\.[cm]?[jt]sx?)$")
|
||||
LOWERING = re.compile(r"\b(?:it|test|describe|suite|bench|context)(?:\.\w+)*\.(skip|only|fixme|todo)\b")
|
||||
# Files whose numbers or lists are the gates' standards: budgets, ceilings, baselines, the ungated
|
||||
# allow-lists, coverage thresholds, snapshots and visual goldens.
|
||||
GATE_STANDARDS = (
|
||||
re.compile(r"^config/performance/budgets\.json$"),
|
||||
re.compile(r"^config/scale/.+\.json$"),
|
||||
re.compile(r"^config/testing/.+\.json$"),
|
||||
re.compile(r"^config/ci/ungated-[^/]+\.json$"),
|
||||
re.compile(r"^config/.*baseline[^/]*\.json$"),
|
||||
re.compile(r"^vitest\.config\.ts$"),
|
||||
re.compile(r"(?:^|/)__snapshots__/"),
|
||||
re.compile(r"\.snap$"),
|
||||
)
|
||||
|
||||
# --- N2: the work-manual check a document edit can break ---------------------------------------------------
|
||||
DOC_CHECK = ("scripts/check-work-docs.py",)
|
||||
DOC_TIMEOUT = 20
|
||||
|
||||
# --- N5: an edit that only the desktop can check, until a desktop run --------------------------------------
|
||||
# Laptop-checkable on their own: the hooks and their tests, the work-manual checker, the ledger, Claude
|
||||
# settings, CLAUDE.md and the folder rule books under src/ (scripts/check-work-docs.py checks them). Everything else is checked by gates that need pnpm.
|
||||
LAPTOP_ONLY = (
|
||||
re.compile(r"^\.claude/"),
|
||||
re.compile(r"^scripts/hooks/"),
|
||||
re.compile(r"^scripts/tests/"),
|
||||
re.compile(r"^scripts/check-work-docs\.py$"),
|
||||
re.compile(r"^docs/ledger/"),
|
||||
re.compile(r"^CLAUDE\.md$"),
|
||||
re.compile(r"^src/(?:.+/)?(?:AGENTS|CLAUDE)\.md$"),
|
||||
)
|
||||
DESKTOP_HOST = re.compile(r"desktop")
|
||||
DESKTOP_WORK = re.compile(r"\b(?:pnpm|ci:gate|verify\.sh|vitest|playwright)\b|\bnode\s+scripts/")
|
||||
VERIFY = re.compile(r"(?:^|[\s;&|(])(?:\./)?scripts/verify\.sh\s+(\S+)(.*)")
|
||||
LAPTOP_STAGES = {"docs", "hooks"}
|
||||
|
||||
|
||||
# ----------------------------------------------------------------------------------------------------
|
||||
# plumbing
|
||||
|
||||
|
||||
def project_root(payload: dict) -> Path:
|
||||
root = os.environ.get("CLAUDE_PROJECT_DIR") or payload.get("cwd") or os.getcwd()
|
||||
return Path(root).resolve()
|
||||
|
||||
|
||||
def relative(root: Path, file_path: str | None) -> str | None:
|
||||
if not file_path:
|
||||
return None
|
||||
path = Path(file_path)
|
||||
if not path.is_absolute():
|
||||
path = root / path
|
||||
try:
|
||||
return path.resolve().relative_to(root).as_posix()
|
||||
except ValueError:
|
||||
return None
|
||||
|
||||
|
||||
def edited_path(payload: dict) -> str | None:
|
||||
if payload.get("tool_name") not in EDIT_TOOLS:
|
||||
return None
|
||||
return relative(project_root(payload), (payload.get("tool_input") or {}).get("file_path"))
|
||||
|
||||
|
||||
def context(event: str, lines: list[str]) -> str:
|
||||
"""The PostToolUse output that adds lines to the model's context without blocking."""
|
||||
text = "\n".join(lines[:MAX_LINES] + ([f"(… {len(lines) - MAX_LINES}줄 더)"] if len(lines) > MAX_LINES else []))
|
||||
return json.dumps({"hookSpecificOutput": {"hookEventName": event, "additionalContext": text}},
|
||||
ensure_ascii=False)
|
||||
|
||||
|
||||
def state_file(root: Path, session_id: str) -> Path:
|
||||
safe = re.sub(r"[^A-Za-z0-9_.-]", "_", session_id or "unknown")
|
||||
return root / STATE_DIR / f"{safe}.json"
|
||||
|
||||
|
||||
def load_state(root: Path, session_id: str) -> dict:
|
||||
try:
|
||||
state = json.loads(state_file(root, session_id).read_text(encoding="utf-8"))
|
||||
except (OSError, ValueError):
|
||||
state = {}
|
||||
state.setdefault("pending", [])
|
||||
state.setdefault("reminded", False)
|
||||
return state
|
||||
|
||||
|
||||
def save_state(root: Path, session_id: str, state: dict) -> None:
|
||||
path = state_file(root, session_id)
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8")
|
||||
|
||||
|
||||
# ----------------------------------------------------------------------------------------------------
|
||||
# N3 — imports of one edited source against the forbidden rules of .dependency-cruiser.json
|
||||
|
||||
|
||||
def load_rules(root: Path) -> list[dict]:
|
||||
try:
|
||||
rules = json.loads((root / RULES).read_text(encoding="utf-8")).get("forbidden", [])
|
||||
except (OSError, ValueError):
|
||||
return []
|
||||
# The cycle rule needs the whole graph; the gate holds it.
|
||||
return [rule for rule in rules if "path" in (rule.get("to") or {})]
|
||||
|
||||
|
||||
def specifiers(source: str) -> list[str]:
|
||||
found = []
|
||||
for groups in SPECIFIER.findall(source):
|
||||
value = next((group for group in groups if group), None)
|
||||
if value and value not in found:
|
||||
found.append(value)
|
||||
return found
|
||||
|
||||
|
||||
def resolve(root: Path, path: str, specifier: str) -> str:
|
||||
"""A relative specifier as a repository path (the file it names when one exists); a package as itself."""
|
||||
if not specifier.startswith("."):
|
||||
return specifier
|
||||
base = os.path.normpath(os.path.join(os.path.dirname(path), specifier)).replace(os.sep, "/")
|
||||
stem = re.sub(r"\.(?:js|jsx|mjs)$", "", base)
|
||||
for candidate in (base, *(stem + suffix for suffix in RESOLVE_SUFFIXES)):
|
||||
if (root / candidate).is_file():
|
||||
return candidate
|
||||
return base
|
||||
|
||||
|
||||
def broken_rules(rules: list[dict], path: str, target: str) -> list[str]:
|
||||
broken = []
|
||||
for rule in rules:
|
||||
origin, to = rule.get("from") or {}, rule.get("to") or {}
|
||||
match = re.search(origin.get("path", ""), path)
|
||||
if match is None or ("pathNot" in origin and re.search(origin["pathNot"], path)):
|
||||
continue
|
||||
group = re.escape(match.group(1)) if match.re.groups and match.group(1) is not None else ""
|
||||
if not re.search(to["path"].replace("$1", group), target):
|
||||
continue
|
||||
if "pathNot" in to and re.search(to["pathNot"].replace("$1", group), target):
|
||||
continue
|
||||
broken.append(rule["name"])
|
||||
return broken
|
||||
|
||||
|
||||
def boundary_findings(root: Path, path: str, source: str) -> list[str]:
|
||||
if not SOURCE.match(path) or path.endswith(".d.ts"):
|
||||
return []
|
||||
rules = load_rules(root)
|
||||
findings = []
|
||||
for specifier in specifiers(source):
|
||||
target = resolve(root, path, specifier)
|
||||
for name in broken_rules(rules, path, target):
|
||||
findings.append(f"- {RULE_ITEMS.get(name, '꼭 지킬 것 3')} 의심: `{name}` — `{specifier}`(→ `{target}`)")
|
||||
if len(findings) > 2:
|
||||
# One wrong import usually breaks several rules; the first two say what to look at.
|
||||
findings = findings[:2] + [f"- 외 {len(findings) - 2}개"]
|
||||
if findings:
|
||||
findings.insert(0, f"경계 알림(N3) {path}")
|
||||
findings.append("정본은 게이트다: desktop `scripts/verify.sh gate FE-GATE-010`(check:architecture). "
|
||||
"kernel 예외를 늘려 풀지 않는다.")
|
||||
return findings
|
||||
|
||||
|
||||
# ----------------------------------------------------------------------------------------------------
|
||||
# N6 — skip·only·fixme·todo added to a test, or a gate standard file changed
|
||||
|
||||
|
||||
def committed(root: Path, path: str) -> str:
|
||||
try:
|
||||
result = subprocess.run(["git", "show", f"HEAD:{path}"], cwd=root, capture_output=True, text=True,
|
||||
timeout=5)
|
||||
except (OSError, subprocess.TimeoutExpired):
|
||||
return ""
|
||||
return result.stdout if result.returncode == 0 else ""
|
||||
|
||||
|
||||
def lowering_counts(source: str) -> dict[str, int]:
|
||||
counts: dict[str, int] = {}
|
||||
for word in LOWERING.findall(source):
|
||||
counts[word] = counts.get(word, 0) + 1
|
||||
return counts
|
||||
|
||||
|
||||
def standard_findings(root: Path, path: str, source: str) -> list[str]:
|
||||
lines = []
|
||||
if any(pattern.search(path) for pattern in GATE_STANDARDS):
|
||||
lines.append(f"게이트 기준 알림(N6) {path}는 게이트의 기준 파일(예산·기준선·ungated 목록·스냅숏)이다.")
|
||||
elif TEST_SOURCE.search(path):
|
||||
before, after = lowering_counts(committed(root, path)), lowering_counts(source)
|
||||
grown = [f"`.{word}` {before.get(word, 0)}→{count}" for word, count in sorted(after.items())
|
||||
if count > before.get(word, 0)]
|
||||
if grown:
|
||||
lines.append(f"게이트 기준 알림(N6) {path}: 마지막 커밋보다 {', '.join(grown)}.")
|
||||
if lines:
|
||||
lines.append("꼭 지킬 것 4: 기준을 낮춰 통과시키지 않는다. 의도한 변경이면 이유와 결정 출처를 커밋 본문에 적는다.")
|
||||
return lines
|
||||
|
||||
|
||||
# ----------------------------------------------------------------------------------------------------
|
||||
# N2 — the work-manual check, failures only
|
||||
|
||||
|
||||
def wants_doc_check(path: str | None) -> bool:
|
||||
return bool(path) and path.endswith(".md") and not path.startswith(STATE_DIR + "/")
|
||||
|
||||
|
||||
def doc_findings(root: Path, path: str) -> list[str]:
|
||||
if not (root / DOC_CHECK[0]).is_file():
|
||||
return []
|
||||
try:
|
||||
result = subprocess.run([sys.executable, *DOC_CHECK], cwd=root, capture_output=True, text=True,
|
||||
timeout=DOC_TIMEOUT)
|
||||
except subprocess.TimeoutExpired:
|
||||
return [f"문서 검사 알림(N2): {DOC_CHECK[0]}가 {DOC_TIMEOUT}초 안에 끝나지 않았다"]
|
||||
if result.returncode == 0:
|
||||
return []
|
||||
lines = [line.strip() for line in result.stderr.splitlines() if line.startswith(" ") and line.strip()]
|
||||
mine = [line for line in lines if path in line]
|
||||
return [f"문서 검사 알림(N2) {path} 편집 뒤 실패 줄:", *[f"- {line}" for line in (mine or lines)]]
|
||||
|
||||
|
||||
# ----------------------------------------------------------------------------------------------------
|
||||
# N5 — something only the desktop can check changed, and the desktop has not run since
|
||||
|
||||
|
||||
def needs_desktop(path: str) -> bool:
|
||||
return not any(pattern.search(path) for pattern in LAPTOP_ONLY)
|
||||
|
||||
|
||||
def ran_on_desktop(command: str) -> bool:
|
||||
"""An `ssh <desktop> …` running pnpm or a gate, or scripts/verify.sh with a stage that goes there."""
|
||||
try:
|
||||
words = shlex.split(command)
|
||||
except ValueError:
|
||||
words = command.split()
|
||||
for position, word in enumerate(words):
|
||||
if word.endswith("ssh"):
|
||||
hosts = [w for w in words[position + 1:position + 5] if not w.startswith("-")][:2]
|
||||
if any(DESKTOP_HOST.search(host) for host in hosts) and DESKTOP_WORK.search(command):
|
||||
return True
|
||||
for match in VERIFY.finditer(command):
|
||||
stage, rest = match.group(1), match.group(2)
|
||||
if stage not in LAPTOP_STAGES and not re.search(r"--on\s+here\b", rest):
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def turn_end_reason(state: dict) -> str | None:
|
||||
edits = state.get("pending") or []
|
||||
if not edits or state.get("reminded"):
|
||||
return None
|
||||
shown = ", ".join(f"`{edit}`" for edit in edits[:3]) + (f" 외 {len(edits) - 3}개" if len(edits) > 3 else "")
|
||||
return (f"[N5 턴 끝 알림] 이 세션에서 파일 {len(edits)}개를 고쳤고({shown}) 그 뒤 desktop 실행이 없다. "
|
||||
"포맷·린트·타입·테스트·문서 검사는 노트북이 아니라 desktop에서 `scripts/verify.sh gate FE-GATE-0NN`이나 "
|
||||
"`scripts/verify.sh merge`로 한다(docs/work/operate.md 4.1절). 이번 턴에 돌릴 수 없으면 완료를 말하지 말고, "
|
||||
"보고의 확인 줄에 돌리지 못한 것과 이유를 적는다(꼭 지킬 것 5). 이 알림은 다음 편집 전까지 한 번만 나온다.")
|
||||
|
||||
|
||||
# ----------------------------------------------------------------------------------------------------
|
||||
# events
|
||||
|
||||
|
||||
def post_edit(payload: dict) -> int:
|
||||
root = project_root(payload)
|
||||
path = edited_path(payload)
|
||||
if path is None or not (root / path).is_file():
|
||||
return 0
|
||||
try:
|
||||
source = (root / path).read_text(encoding="utf-8")
|
||||
except (OSError, UnicodeDecodeError):
|
||||
source = ""
|
||||
lines = boundary_findings(root, path, source) + standard_findings(root, path, source)
|
||||
if wants_doc_check(path):
|
||||
lines += doc_findings(root, path)
|
||||
if needs_desktop(path):
|
||||
state = load_state(root, payload.get("session_id", ""))
|
||||
if path not in state["pending"]:
|
||||
state["pending"].append(path)
|
||||
state["reminded"] = False
|
||||
save_state(root, payload.get("session_id", ""), state)
|
||||
if lines:
|
||||
print(context("PostToolUse", lines))
|
||||
return 0
|
||||
|
||||
|
||||
def post_bash(payload: dict) -> int:
|
||||
command = (payload.get("tool_input") or {}).get("command", "")
|
||||
if ran_on_desktop(command):
|
||||
root = project_root(payload)
|
||||
state = load_state(root, payload.get("session_id", ""))
|
||||
state["pending"] = []
|
||||
state["reminded"] = False
|
||||
save_state(root, payload.get("session_id", ""), state)
|
||||
return 0
|
||||
|
||||
|
||||
def stop(payload: dict) -> int:
|
||||
if payload.get("stop_hook_active"):
|
||||
return 0
|
||||
root = project_root(payload)
|
||||
state = load_state(root, payload.get("session_id", ""))
|
||||
reason = turn_end_reason(state)
|
||||
if reason:
|
||||
state["reminded"] = True
|
||||
save_state(root, payload.get("session_id", ""), state)
|
||||
print(json.dumps({"decision": "block", "reason": reason}, ensure_ascii=False))
|
||||
return 0
|
||||
|
||||
|
||||
EVENTS = {"post-edit": post_edit, "post-bash": post_bash, "stop": stop}
|
||||
|
||||
|
||||
def main(argv: list[str]) -> int:
|
||||
if len(argv) != 1 or argv[0] not in EVENTS:
|
||||
print(f"usage: hooks.py {{{'|'.join(EVENTS)}}} < hook-input.json", file=sys.stderr)
|
||||
return 1
|
||||
try:
|
||||
payload = json.load(sys.stdin)
|
||||
except ValueError:
|
||||
return 0
|
||||
return EVENTS[argv[0]](payload if isinstance(payload, dict) else {})
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main(sys.argv[1:]))
|
||||
@@ -79,6 +79,8 @@ export const REMOVAL_FIXTURE_DOCUMENT_TESTS = Object.freeze([
|
||||
"tests/unit/manual-paired-backend-settings.test.ts",
|
||||
// Reads the marked code blocks of docs/manual.
|
||||
"tests/unit/manual-code-blocks.test.ts",
|
||||
// Reads the README deletable-files table and the docs/README.md index.
|
||||
"tests/unit/template-contract-documents.test.ts",
|
||||
] as const);
|
||||
|
||||
/** The tests a fixture copied from `copyTargets` cannot run. */
|
||||
|
||||
@@ -0,0 +1,128 @@
|
||||
"""scripts/check-work-docs.py의 시험. 이 repo의 작업 매뉴얼이 통과하고, 고장 낸 사본이 실패하는지 본다.
|
||||
|
||||
python3 -m unittest discover -s scripts/tests
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import importlib.util
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
SCRIPTS = Path(__file__).resolve().parent.parent
|
||||
REPO = SCRIPTS.parent
|
||||
CHECKER = SCRIPTS / "check-work-docs.py"
|
||||
_spec = importlib.util.spec_from_file_location("check_work_docs", CHECKER)
|
||||
check = importlib.util.module_from_spec(_spec)
|
||||
_spec.loader.exec_module(check)
|
||||
|
||||
|
||||
def history(line: str) -> tuple[str, str] | None:
|
||||
return check.history_match(line, "")
|
||||
|
||||
|
||||
class HistoryPatternTest(unittest.TestCase):
|
||||
def test_this_repository_history_ids_are_caught(self) -> None:
|
||||
for line in ("1103/11-07처럼 고쳤다", "1105 README 11.4절", "1103 조치의 고침", "결함 패턴 P-43",
|
||||
"0925 라운드 D-14", "소유자 O-12", "4라운드 리뷰", "결정 D8을 따른다", "리뷰 12-03에서",
|
||||
"(05-01, 04-01)", "커밋 ad3a071f"):
|
||||
with self.subTest(line=line):
|
||||
self.assertIsNotNone(history(line))
|
||||
|
||||
def test_ordinary_sentences_are_not_history(self) -> None:
|
||||
for line in ("FE-GATE-013은 desktop에서 실패한다", "소유자 결정 2026-11-05", "P1과 P0~P3", "M0~M4, E0~E4",
|
||||
"결정 대기로 남긴다", "Node 24.14.0", "결함 패턴 G13", "세 라운드를 더", "3라운드마다",
|
||||
"`MMDD/NN-MM` 꼴", "초기 JS 206,848 B", "a11y·e2e", "9~15분"):
|
||||
with self.subTest(line=line):
|
||||
self.assertIsNone(history(line))
|
||||
|
||||
|
||||
class RepositoryManualTest(unittest.TestCase):
|
||||
def test_the_manual_in_this_repository_passes(self) -> None:
|
||||
result = subprocess.run([sys.executable, str(CHECKER)], capture_output=True, text=True, timeout=30)
|
||||
self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
|
||||
|
||||
|
||||
class BrokenCopyTest(unittest.TestCase):
|
||||
"""A copy of the manual with one thing broken at a time; the checker in the copy must fail on it."""
|
||||
|
||||
def setUp(self) -> None:
|
||||
self._directory = tempfile.TemporaryDirectory()
|
||||
self.addCleanup(self._directory.cleanup)
|
||||
self.root = Path(self._directory.name)
|
||||
for path in ("AGENTS.md", "CLAUDE.md", "docs/work", ".claude/rules", ".claude/skills", ".claude/agents"):
|
||||
source = REPO / path
|
||||
target = self.root / path
|
||||
if not source.exists():
|
||||
continue
|
||||
if source.is_dir():
|
||||
shutil.copytree(source, target)
|
||||
else:
|
||||
target.parent.mkdir(parents=True, exist_ok=True)
|
||||
shutil.copy(source, target)
|
||||
(self.root / "scripts").mkdir()
|
||||
shutil.copy(CHECKER, self.root / "scripts/check-work-docs.py")
|
||||
|
||||
def run_checker(self) -> subprocess.CompletedProcess:
|
||||
return subprocess.run([sys.executable, str(self.root / "scripts/check-work-docs.py")], capture_output=True,
|
||||
text=True, timeout=30)
|
||||
|
||||
def append(self, path: str, text: str) -> None:
|
||||
with (self.root / path).open("a", encoding="utf-8") as handle:
|
||||
handle.write(text)
|
||||
|
||||
def test_the_copy_passes_before_it_is_broken(self) -> None:
|
||||
self.assertEqual(self.run_checker().returncode, 0)
|
||||
|
||||
def test_a_long_map_fails(self) -> None:
|
||||
self.append("AGENTS.md", "\n" * 10)
|
||||
self.assertIn("AGENTS.md: ", self.run_checker().stderr)
|
||||
|
||||
def test_claude_md_must_start_with_the_import(self) -> None:
|
||||
text = (self.root / "CLAUDE.md").read_text(encoding="utf-8")
|
||||
(self.root / "CLAUDE.md").write_text("# CLAUDE.md\n" + text, encoding="utf-8")
|
||||
self.assertIn("the first line must be '@AGENTS.md'", self.run_checker().stderr)
|
||||
|
||||
def test_a_history_id_in_a_playbook_or_rule_fails_but_not_in_the_evidence(self) -> None:
|
||||
self.append("docs/work/evidence.md", "\n1103/11-07\n")
|
||||
self.assertEqual(self.run_checker().returncode, 0)
|
||||
for path in ("docs/work/improve.md", ".claude/rules/tests.md", "docs/work/reference/gates.md"):
|
||||
with self.subTest(path=path):
|
||||
original = (self.root / path).read_text(encoding="utf-8")
|
||||
self.append(path, "\n고친 방법은 1105/12-04와 같다.\n")
|
||||
self.assertIn(f"{path}:", self.run_checker().stderr)
|
||||
(self.root / path).write_text(original, encoding="utf-8")
|
||||
|
||||
def test_a_playbook_without_the_skeleton_fails(self) -> None:
|
||||
path = self.root / "docs/work/operate.md"
|
||||
path.write_text(path.read_text(encoding="utf-8").replace("## 6. 하지 말 것", "## 6. 금지"), encoding="utf-8")
|
||||
self.assertIn("sections must be exactly", self.run_checker().stderr)
|
||||
|
||||
def test_a_broken_relative_link_fails(self) -> None:
|
||||
self.append("docs/work/README.md", "\n[x](missing.md)\n")
|
||||
self.assertIn("broken relative link 'missing.md'", self.run_checker().stderr)
|
||||
|
||||
def test_a_folder_rule_book_needs_its_import_beside_it_and_no_history(self) -> None:
|
||||
guide = self.root / "src/adapters/AGENTS.md"
|
||||
guide.parent.mkdir(parents=True)
|
||||
guide.write_text("# AGENTS.md\n\n- 규칙\n", encoding="utf-8")
|
||||
self.assertIn("src/adapters/CLAUDE.md: missing", self.run_checker().stderr)
|
||||
(self.root / "src/adapters/CLAUDE.md").write_text("@AGENTS.md\n", encoding="utf-8")
|
||||
self.assertEqual(self.run_checker().returncode, 0)
|
||||
(self.root / "src/adapters/CLAUDE.md").write_text("@AGENTS.md\n- 둘째 규칙\n", encoding="utf-8")
|
||||
self.assertIn("must be exactly '@AGENTS.md'", self.run_checker().stderr)
|
||||
(self.root / "src/adapters/CLAUDE.md").write_text("@AGENTS.md\n", encoding="utf-8")
|
||||
guide.write_text("# AGENTS.md\n\n- 1105/12-04처럼 고친다\n", encoding="utf-8")
|
||||
self.assertIn("src/adapters/AGENTS.md:3:", self.run_checker().stderr)
|
||||
|
||||
def test_a_missing_reference_fails(self) -> None:
|
||||
(self.root / "docs/work/reference/testing.md").unlink()
|
||||
self.assertIn("docs/work/reference/testing.md: missing", self.run_checker().stderr)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,161 @@
|
||||
"""루트 지침과 `.claude/`의 규칙·스킬·서브에이전트가 소유자 결정(2026-11-07)대로인지 본다.
|
||||
|
||||
결과만 받는 일은 서브에이전트, 파일을 바꾸는 위임은 하위 세션이다(docs/work/delegate.md 4.3절).
|
||||
새 스킬은 모두 모델이 부를 수 있고, 설명에 발동 조건을 문단으로 적는다.
|
||||
|
||||
python3 -m unittest discover -s scripts/tests
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO = Path(__file__).resolve().parent.parent.parent
|
||||
CLAUDE = REPO / ".claude"
|
||||
# Claude Code cuts a skill description at this many characters in the listing.
|
||||
DESCRIPTION_LIMIT = 1536
|
||||
WRITE_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
|
||||
|
||||
|
||||
def front_matter(path: Path) -> tuple[dict[str, str], list[str]]:
|
||||
"""The scalar fields and the list items of a document's YAML front matter."""
|
||||
match = re.match(r"^---\n(.*?)\n---\n", path.read_text(encoding="utf-8"), re.S)
|
||||
if not match:
|
||||
return {}, []
|
||||
fields, items = {}, []
|
||||
for line in match.group(1).splitlines():
|
||||
if line.lstrip().startswith("- "):
|
||||
items.append(line.strip()[2:].strip('"'))
|
||||
continue
|
||||
key, _, value = line.partition(":")
|
||||
fields[key.strip()] = value.strip()
|
||||
return fields, items
|
||||
|
||||
|
||||
class RootInstructionsTest(unittest.TestCase):
|
||||
def test_claude_md_imports_the_map_and_says_how_to_install_the_plugin_non_interactively(self) -> None:
|
||||
text = (REPO / "CLAUDE.md").read_text(encoding="utf-8")
|
||||
self.assertEqual(text.splitlines()[0], "@AGENTS.md")
|
||||
for command in ("claude plugin marketplace add https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git"
|
||||
" --scope project", "claude plugin install harness@claude-harness --scope project"):
|
||||
self.assertIn(command, text)
|
||||
|
||||
def test_the_map_holds_the_five_rules_the_router_and_the_entry_point(self) -> None:
|
||||
text = (REPO / "AGENTS.md").read_text(encoding="utf-8")
|
||||
self.assertEqual(len(re.findall(r"^[1-5]\. ", text.split("## 지도")[0], re.M)), 5)
|
||||
for fragment in ("docs/work/README.md", "scripts/verify.sh", "config/ci/gates.json", ".dependency-cruiser.json",
|
||||
"하위 세션", "서브에이전트"):
|
||||
self.assertIn(fragment, text)
|
||||
|
||||
def test_the_review_criteria_left_the_session_instructions(self) -> None:
|
||||
for path in ("AGENTS.md", "CLAUDE.md"):
|
||||
text = (REPO / path).read_text(encoding="utf-8")
|
||||
self.assertNotIn("28개 관점", text, path)
|
||||
self.assertNotIn("서브에이전트를 병렬로", text, path)
|
||||
|
||||
|
||||
class LayerGuideTest(unittest.TestCase):
|
||||
"""Every top-level src/ folder has its rule book, readable by any agent, and Claude Code imports it."""
|
||||
|
||||
def test_every_layer_folder_has_a_rule_book_and_the_import_beside_it(self) -> None:
|
||||
folders = sorted(path for path in (REPO / "src").iterdir() if path.is_dir() and not path.name.startswith("."))
|
||||
self.assertTrue(folders)
|
||||
for folder in folders:
|
||||
guide = folder / "AGENTS.md"
|
||||
self.assertTrue(guide.is_file(), f"{folder.name}: no AGENTS.md")
|
||||
self.assertTrue(guide.read_text(encoding="utf-8").startswith(f"# AGENTS.md — `src/{folder.name}`"))
|
||||
self.assertEqual((folder / "CLAUDE.md").read_text(encoding="utf-8"), "@AGENTS.md\n", folder.name)
|
||||
|
||||
def test_path_rules_point_at_the_folder_books_instead_of_copying_them(self) -> None:
|
||||
for rule, book in (("adapters", "src/adapters/AGENTS.md"), ("features", "src/features/AGENTS.md")):
|
||||
self.assertIn(f"`{book}`", (CLAUDE / "rules" / f"{rule}.md").read_text(encoding="utf-8"))
|
||||
|
||||
def test_the_owner_forms_exist_and_the_map_points_at_them(self) -> None:
|
||||
for form in ("docs/vision.md", "docs/problem-statement.md"):
|
||||
self.assertIn("(채울 것", (REPO / form).read_text(encoding="utf-8"), form)
|
||||
self.assertIn(f"`{form}`", (REPO / "AGENTS.md").read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
class SubagentTest(unittest.TestCase):
|
||||
AGENTS = CLAUDE / "agents"
|
||||
|
||||
def test_the_agent_tool_is_not_denied(self) -> None:
|
||||
settings = json.loads((CLAUDE / "settings.json").read_text(encoding="utf-8"))
|
||||
deny = settings.get("permissions", {}).get("deny", [])
|
||||
self.assertFalse([rule for rule in deny if rule == "Agent" or rule.startswith("Agent(")])
|
||||
|
||||
def test_each_definition_names_itself_and_says_when_to_use_it(self) -> None:
|
||||
definitions = sorted(self.AGENTS.glob("*.md"))
|
||||
self.assertEqual([path.stem for path in definitions], ["arch-reviewer", "code-simplifier", "verify-app"])
|
||||
for path in definitions:
|
||||
fields, _ = front_matter(path)
|
||||
self.assertEqual(fields.get("name"), path.stem, path)
|
||||
self.assertIn("쓴다", fields.get("description", ""), path)
|
||||
self.assertTrue(fields.get("tools"), f"{path} must list its tools; an empty list inherits every tool")
|
||||
|
||||
def test_no_subagent_can_edit_files(self) -> None:
|
||||
for path in self.AGENTS.glob("*.md"):
|
||||
tools = {tool.strip() for tool in front_matter(path)[0].get("tools", "").split(",")}
|
||||
self.assertFalse(tools & WRITE_TOOLS, f"{path} returns results only; it must not hold {tools & WRITE_TOOLS}")
|
||||
|
||||
def test_the_reviewers_run_nothing_heavy(self) -> None:
|
||||
self.assertNotIn("Bash", front_matter(self.AGENTS / "code-simplifier.md")[0]["tools"])
|
||||
reviewer = (self.AGENTS / "arch-reviewer.md").read_text(encoding="utf-8")
|
||||
self.assertIn("파일을 쓰거나 고치지 않는다", reviewer)
|
||||
self.assertIn("pnpm·node·게이트는 돌리지 않는다", reviewer)
|
||||
|
||||
def test_verify_app_runs_on_the_desktop_under_the_shared_lock(self) -> None:
|
||||
text = (self.AGENTS / "verify-app.md").read_text(encoding="utf-8")
|
||||
for fragment in ("docs/work/operate.md", "scripts/verify.sh", "flock /tmp/claude-gates/heavy.lock",
|
||||
"stash@{0}", "TEST_RUN_ID"):
|
||||
self.assertIn(fragment, text)
|
||||
|
||||
|
||||
class SkillTest(unittest.TestCase):
|
||||
CANON = {"new-feature": "docs/work/new-feature.md", "desktop-gates": "docs/work/operate.md"}
|
||||
|
||||
def test_the_repository_skills_are_the_two_the_manual_names(self) -> None:
|
||||
self.assertEqual(sorted(path.parent.name for path in (CLAUDE / "skills").glob("*/SKILL.md")), sorted(self.CANON))
|
||||
|
||||
def test_each_skill_is_model_invoked_and_says_when_in_its_description(self) -> None:
|
||||
for name in self.CANON:
|
||||
fields, _ = front_matter(CLAUDE / "skills" / name / "SKILL.md")
|
||||
self.assertEqual(fields.get("name"), name)
|
||||
self.assertNotIn("disable-model-invocation", fields)
|
||||
description = fields.get("description", "")
|
||||
self.assertLessEqual(len(description), DESCRIPTION_LIMIT, name)
|
||||
self.assertIn("쓴다", description, f"{name}: say when to use it")
|
||||
self.assertIn("부른다", description, f"{name}: say what the user says that calls it")
|
||||
|
||||
def test_each_skill_points_at_its_canonical_playbook_instead_of_copying_it(self) -> None:
|
||||
for name, canon in self.CANON.items():
|
||||
body = (CLAUDE / "skills" / name / "SKILL.md").read_text(encoding="utf-8")
|
||||
self.assertIn(f"정본은 `{canon}`", body)
|
||||
self.assertIn("정본이 맞다", body)
|
||||
|
||||
|
||||
class PathRuleTest(unittest.TestCase):
|
||||
def test_every_rule_is_scoped_by_paths_that_exist(self) -> None:
|
||||
rules = sorted((CLAUDE / "rules").glob("*.md"))
|
||||
self.assertEqual([path.stem for path in rules], ["adapters", "docs", "features", "gates-and-budgets", "tests"])
|
||||
for path in rules:
|
||||
fields, patterns = front_matter(path)
|
||||
self.assertIn("paths", fields, path)
|
||||
self.assertTrue(patterns, path)
|
||||
for pattern in patterns:
|
||||
# A pattern that matches nothing is a rule nobody reads.
|
||||
self.assertTrue(next(REPO.glob(pattern), None), f"{path}: '{pattern}' matches no file")
|
||||
|
||||
|
||||
class GitignoreTest(unittest.TestCase):
|
||||
def test_the_shared_claude_files_are_tracked_and_session_state_is_not(self) -> None:
|
||||
lines = (REPO / ".gitignore").read_text(encoding="utf-8").splitlines()
|
||||
for line in (".claude/*", "!.claude/settings.json", "!.claude/rules/", "!.claude/agents/", "!.claude/skills/"):
|
||||
self.assertIn(line, lines)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,307 @@
|
||||
"""scripts/hooks/hooks.py의 시험. 고장 낸 입력에서 알림이 나오고, 맞는 입력에서 조용한지 본다.
|
||||
|
||||
python3 -m unittest discover -s scripts/tests
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import importlib.util
|
||||
import io
|
||||
import json
|
||||
import os
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import textwrap
|
||||
import unittest
|
||||
from contextlib import redirect_stderr, redirect_stdout
|
||||
from pathlib import Path
|
||||
from unittest import mock
|
||||
|
||||
SCRIPTS = Path(__file__).resolve().parent.parent
|
||||
REPO = SCRIPTS.parent
|
||||
_spec = importlib.util.spec_from_file_location("hooks", SCRIPTS / "hooks/hooks.py")
|
||||
hooks = importlib.util.module_from_spec(_spec)
|
||||
sys.modules["hooks"] = hooks
|
||||
_spec.loader.exec_module(hooks)
|
||||
|
||||
GIT_ENV = {"GIT_AUTHOR_NAME": "t", "GIT_AUTHOR_EMAIL": "t@example.com", "GIT_COMMITTER_NAME": "t",
|
||||
"GIT_COMMITTER_EMAIL": "t@example.com", "GIT_CONFIG_COUNT": "1", "GIT_CONFIG_KEY_0": "core.hooksPath",
|
||||
"GIT_CONFIG_VALUE_0": "/dev/null"}
|
||||
FILES = {
|
||||
"src/adapters/http/index.ts": "export * from './client.ts';\n",
|
||||
"src/adapters/http/client.ts": "export const client = 1;\n",
|
||||
"src/adapters/auth/index.ts": "export const auth = 1;\n",
|
||||
"src/adapters/auth/session.ts": "export const session = 1;\n",
|
||||
"src/adapters/platform/locks.ts": "export const locks = 1;\n",
|
||||
"src/bootstrap/compose.ts": "export {};\n",
|
||||
"src/presentation/pages/home-page.tsx": "export {};\n",
|
||||
"src/domain/order.ts": "export {};\n",
|
||||
}
|
||||
|
||||
|
||||
class Repository:
|
||||
"""A throwaway git checkout with the real import rules and a few adapter groups."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self._directory = tempfile.TemporaryDirectory()
|
||||
self.root = Path(self._directory.name).resolve()
|
||||
shutil.copy(REPO / hooks.RULES, self.root / hooks.RULES)
|
||||
for path, text in FILES.items():
|
||||
self.write(path, text)
|
||||
self.git("init", "-q")
|
||||
self.git("add", "-A")
|
||||
self.git("commit", "-q", "-m", "base")
|
||||
|
||||
def git(self, *args: str) -> None:
|
||||
subprocess.run(["git", *args], cwd=self.root, check=True, capture_output=True, env={**os.environ, **GIT_ENV})
|
||||
|
||||
def write(self, path: str, text: str) -> Path:
|
||||
target = self.root / path
|
||||
target.parent.mkdir(parents=True, exist_ok=True)
|
||||
target.write_text(text, encoding="utf-8")
|
||||
return target
|
||||
|
||||
def payload(self, path: str, tool: str = "Edit", **extra) -> dict:
|
||||
return {"session_id": "s1", "cwd": str(self.root), "tool_name": tool,
|
||||
"tool_input": {"file_path": str(self.root / path)}, **extra}
|
||||
|
||||
def close(self) -> None:
|
||||
self._directory.cleanup()
|
||||
|
||||
|
||||
def run_event(event: str, payload: dict) -> tuple[int, str, str]:
|
||||
out, err = io.StringIO(), io.StringIO()
|
||||
with mock.patch.dict(os.environ, {}, clear=False), \
|
||||
mock.patch.object(sys, "stdin", io.StringIO(json.dumps(payload))), redirect_stdout(out), redirect_stderr(err):
|
||||
os.environ.pop("CLAUDE_PROJECT_DIR", None)
|
||||
code = hooks.main([event])
|
||||
return code, out.getvalue(), err.getvalue()
|
||||
|
||||
|
||||
def added_context(stdout: str) -> str:
|
||||
return json.loads(stdout)["hookSpecificOutput"]["additionalContext"] if stdout else ""
|
||||
|
||||
|
||||
class RepositoryTestCase(unittest.TestCase):
|
||||
def setUp(self) -> None:
|
||||
self.repo = Repository()
|
||||
self.addCleanup(self.repo.close)
|
||||
|
||||
def edit(self, path: str, text: str) -> str:
|
||||
self.repo.write(path, text)
|
||||
code, out, _ = run_event("post-edit", self.repo.payload(path))
|
||||
self.assertEqual(code, 0)
|
||||
return added_context(out)
|
||||
|
||||
|
||||
class BoundaryNudgeTest(RepositoryTestCase):
|
||||
def test_a_deep_import_past_the_barrel_is_item_1(self) -> None:
|
||||
text = self.edit("src/bootstrap/compose.ts", 'import { client } from "../adapters/http/client.ts";\n')
|
||||
self.assertIn("경계 알림(N3) src/bootstrap/compose.ts", text)
|
||||
self.assertIn("꼭 지킬 것 1 의심: `adapter-groups-are-reached-through-their-barrel`", text)
|
||||
self.assertIn("src/adapters/http/client.ts", text)
|
||||
|
||||
def test_the_barrel_is_quiet(self) -> None:
|
||||
self.assertEqual(self.edit("src/bootstrap/compose.ts", 'import { client } from "../adapters/http/index.ts";\n'), "")
|
||||
|
||||
def test_another_adapter_is_item_2_and_the_kernel_is_allowed(self) -> None:
|
||||
text = self.edit("src/adapters/http/client.ts", textwrap.dedent("""\
|
||||
import { session } from "../auth/session.ts";
|
||||
import { locks } from "../platform/locks.ts";
|
||||
"""))
|
||||
self.assertIn("꼭 지킬 것 2 의심: `adapters-do-not-know-other-concrete-adapters`", text)
|
||||
self.assertNotIn("platform/locks", text)
|
||||
|
||||
def test_a_package_import_is_checked_by_its_name(self) -> None:
|
||||
text = self.edit("src/domain/order.ts", 'import { useState } from "react";\n')
|
||||
self.assertIn("꼭 지킬 것 3 의심: `domain-is-framework-neutral` — `react`", text)
|
||||
|
||||
def test_type_only_reexports_and_dynamic_imports_count(self) -> None:
|
||||
for source in ('export type { Client } from "../../adapters/http/client.ts";\n',
|
||||
'const page = () => import("../../adapters/http/client.ts");\n',
|
||||
'import type {\n Client,\n} from "../../adapters/http/client";\n'):
|
||||
with self.subTest(source=source):
|
||||
self.assertIn("presentation-does-not-know-adapters",
|
||||
self.edit("src/presentation/pages/home-page.tsx", source))
|
||||
|
||||
def test_findings_are_capped_and_keep_the_gate_line(self) -> None:
|
||||
text = self.edit("src/presentation/pages/home-page.tsx",
|
||||
'import { client } from "../../adapters/http/client.ts";\nimport z from "zod";\n')
|
||||
lines = text.splitlines()
|
||||
self.assertLessEqual(len(lines), hooks.MAX_LINES)
|
||||
self.assertRegex(lines[-2], r"^- 외 \d+개$")
|
||||
self.assertIn("FE-GATE-010", lines[-1])
|
||||
|
||||
def test_files_outside_src_and_declarations_are_not_checked(self) -> None:
|
||||
self.assertEqual(self.edit("tests/unit/x.test.ts", 'import { c } from "../../src/adapters/http/client.ts";\n'), "")
|
||||
self.assertEqual(self.edit("src/bootstrap/env.d.ts", 'import { c } from "../adapters/http/client.ts";\n'), "")
|
||||
|
||||
def test_the_real_rules_find_nothing_in_the_real_sources(self) -> None:
|
||||
# A nudge the gate would not raise is noise. The repository passes check:architecture, so every
|
||||
# source file here must be quiet; a new false positive fails this test before it reaches a session.
|
||||
noisy = []
|
||||
for path in sorted((REPO / "src").rglob("*")):
|
||||
if path.suffix in (".ts", ".tsx") and path.is_file():
|
||||
relative = path.relative_to(REPO).as_posix()
|
||||
if hooks.boundary_findings(REPO, relative, path.read_text(encoding="utf-8")):
|
||||
noisy.append(relative)
|
||||
self.assertEqual(noisy, [])
|
||||
|
||||
|
||||
class StandardNudgeTest(RepositoryTestCase):
|
||||
TEST = "tests/unit/orders.test.ts"
|
||||
|
||||
def setUp(self) -> None:
|
||||
super().setUp()
|
||||
self.repo.write(self.TEST, 'it.skip("a", () => {});\nit("b", () => {});\n')
|
||||
self.repo.git("add", "-A")
|
||||
self.repo.git("commit", "-q", "-m", "test")
|
||||
|
||||
def test_skips_and_only_added_since_the_last_commit_are_reported(self) -> None:
|
||||
text = self.edit(self.TEST, 'it.skip("a", () => {});\nit.skip("b", () => {});\ndescribe.only("c", () => {});\n')
|
||||
self.assertIn("게이트 기준 알림(N6) tests/unit/orders.test.ts", text)
|
||||
self.assertIn("`.only` 0→1", text)
|
||||
self.assertIn("`.skip` 1→2", text)
|
||||
self.assertIn("꼭 지킬 것 4", text)
|
||||
|
||||
def test_an_unchanged_or_smaller_count_is_quiet(self) -> None:
|
||||
self.assertEqual(self.edit(self.TEST, 'it.skip("a", () => { expect(1).toBe(1); });\n'), "")
|
||||
self.assertEqual(self.edit(self.TEST, 'it("a", () => {});\n'), "")
|
||||
|
||||
def test_a_new_test_file_counts_from_zero_and_playwright_fixme_counts(self) -> None:
|
||||
text = self.edit("tests/e2e/new.spec.ts", 'test.fixme("x", async () => {});\n')
|
||||
self.assertIn("`.fixme` 0→1", text)
|
||||
|
||||
def test_a_gate_standard_file_edit_is_reported(self) -> None:
|
||||
for path in ("config/performance/budgets.json", "config/ci/ungated-tests.json",
|
||||
"config/scale/feature-shape-ceilings.json", "vitest.config.ts",
|
||||
"tests/unit/__snapshots__/x.test.ts.snap"):
|
||||
with self.subTest(path=path):
|
||||
self.assertIn("게이트의 기준 파일", self.edit(path, "{}\n"))
|
||||
|
||||
def test_source_text_that_looks_like_a_skip_is_not_counted(self) -> None:
|
||||
self.assertEqual(self.edit("src/domain/order.ts", 'export const note = "use it.only when";\n'), "")
|
||||
|
||||
|
||||
class DocumentNudgeTest(RepositoryTestCase):
|
||||
def checker(self, code: int, stderr_lines: list[str]) -> None:
|
||||
body = "import sys\n" + "".join(f"print({line!r}, file=sys.stderr)\n" for line in stderr_lines)
|
||||
self.repo.write(hooks.DOC_CHECK[0], body + f"sys.exit({code})\n")
|
||||
|
||||
def test_failures_naming_the_edited_document_come_back_first(self) -> None:
|
||||
self.checker(1, ["", "FAILED: 2 problem(s)", " docs/work/improve.md:3: history ID '1103/11-07'",
|
||||
" docs/work/README.md:9: broken relative link 'x.md'"])
|
||||
text = self.edit("docs/work/improve.md", "# x\n")
|
||||
self.assertIn("문서 검사 알림(N2) docs/work/improve.md", text)
|
||||
self.assertIn("1103/11-07", text)
|
||||
self.assertNotIn("broken relative link", text)
|
||||
|
||||
def test_failures_elsewhere_are_shown_when_none_names_the_document(self) -> None:
|
||||
self.checker(1, [" AGENTS.md: 41 lines, limit 40"])
|
||||
self.assertIn("AGENTS.md: 41 lines", self.edit("docs/manual/README.md", "# x\n"))
|
||||
|
||||
def test_a_passing_check_adds_nothing(self) -> None:
|
||||
self.checker(0, [])
|
||||
self.assertEqual(self.edit("docs/work/improve.md", "# x\n"), "")
|
||||
|
||||
|
||||
class TurnEndNudgeTest(RepositoryTestCase):
|
||||
def stop(self, **extra) -> dict | None:
|
||||
_, out, _ = run_event("stop", {"session_id": "s1", "cwd": str(self.repo.root), **extra})
|
||||
return json.loads(out) if out else None
|
||||
|
||||
def bash(self, command: str) -> None:
|
||||
run_event("post-bash", {"session_id": "s1", "cwd": str(self.repo.root), "tool_name": "Bash",
|
||||
"tool_input": {"command": command}})
|
||||
|
||||
def test_an_edit_blocks_the_turn_end_once_with_the_reason(self) -> None:
|
||||
self.edit("src/domain/order.ts", "export const a = 1;\n")
|
||||
first = self.stop()
|
||||
self.assertEqual(first["decision"], "block")
|
||||
self.assertIn("src/domain/order.ts", first["reason"])
|
||||
self.assertIn("scripts/verify.sh", first["reason"])
|
||||
self.assertIsNone(self.stop())
|
||||
|
||||
def test_a_desktop_run_clears_the_pending_edits(self) -> None:
|
||||
for command in ("ssh desktop 'cd ~/workspace/x && corepack pnpm -s lint'",
|
||||
"scripts/verify.sh merge --log fe-x",
|
||||
"./scripts/verify.sh gate FE-GATE-005",
|
||||
"cd /w && scripts/verify.sh script verify:documentation 2>&1 | tail"):
|
||||
with self.subTest(command=command):
|
||||
self.edit("src/domain/order.ts", "export const a = 2;\n")
|
||||
self.bash(command)
|
||||
self.assertIsNone(self.stop())
|
||||
|
||||
def test_laptop_commands_and_other_hosts_do_not_count(self) -> None:
|
||||
for command in ("corepack pnpm lint", "ssh build-box 'corepack pnpm lint'", "scripts/verify.sh docs",
|
||||
"scripts/verify.sh hooks", "scripts/verify.sh gate FE-GATE-005 --on here",
|
||||
"ssh desktop uptime"):
|
||||
with self.subTest(command=command):
|
||||
self.edit("src/domain/order.ts", "export const a = 3;\n")
|
||||
self.bash(command)
|
||||
self.assertIsNotNone(self.stop())
|
||||
|
||||
def test_files_the_laptop_checks_do_not_need_the_desktop(self) -> None:
|
||||
for path in (".claude/rules/x.md", "scripts/hooks/hooks.py", "scripts/tests/test_x.py", "CLAUDE.md",
|
||||
"docs/ledger/estimates.jsonl", "scripts/check-work-docs.py", "src/adapters/AGENTS.md",
|
||||
"src/features/CLAUDE.md"):
|
||||
self.repo.write(path, "x\n")
|
||||
run_event("post-edit", self.repo.payload(path))
|
||||
self.assertIsNone(self.stop())
|
||||
|
||||
def test_a_new_edit_after_the_reminder_reminds_again(self) -> None:
|
||||
self.edit("src/domain/order.ts", "export const a = 4;\n")
|
||||
self.stop()
|
||||
self.edit("docs/work/README.md", "# x\n")
|
||||
self.assertIsNotNone(self.stop())
|
||||
|
||||
def test_an_active_stop_hook_never_blocks_again(self) -> None:
|
||||
self.edit("src/domain/order.ts", "export const a = 5;\n")
|
||||
self.assertIsNone(self.stop(stop_hook_active=True))
|
||||
|
||||
|
||||
class SettingsWiringTest(unittest.TestCase):
|
||||
SETTINGS = REPO / ".claude/settings.json"
|
||||
|
||||
def setUp(self) -> None:
|
||||
self.settings = json.loads(self.SETTINGS.read_text(encoding="utf-8"))
|
||||
|
||||
def commands(self, event: str, matcher: str | None) -> list[str]:
|
||||
return [hook["command"] for entry in self.settings["hooks"].get(event, [])
|
||||
if entry.get("matcher") == matcher for hook in entry["hooks"]]
|
||||
|
||||
def test_every_event_calls_its_hook(self) -> None:
|
||||
self.assertEqual(self.commands("PostToolUse", "Edit|Write|MultiEdit"),
|
||||
['python3 "$CLAUDE_PROJECT_DIR"/scripts/hooks/hooks.py post-edit'])
|
||||
self.assertEqual(self.commands("PostToolUse", "Bash"),
|
||||
['python3 "$CLAUDE_PROJECT_DIR"/scripts/hooks/hooks.py post-bash'])
|
||||
self.assertEqual(self.commands("Stop", None), ['python3 "$CLAUDE_PROJECT_DIR"/scripts/hooks/hooks.py stop'])
|
||||
self.assertNotIn("PreToolUse", self.settings["hooks"])
|
||||
|
||||
def test_real_env_files_are_denied_and_the_example_is_not(self) -> None:
|
||||
deny = self.settings["permissions"]["deny"]
|
||||
for tool in ("Read", "Edit"):
|
||||
self.assertIn(f"{tool}(**/.env)", deny)
|
||||
self.assertIn(f"{tool}(**/.env.local)", deny)
|
||||
self.assertFalse([rule for rule in deny if "example" in rule or rule in ("Read(**/.env.*)", "Edit(**/.env.*)")])
|
||||
|
||||
def test_the_harness_plugin_is_enabled_from_its_marketplace(self) -> None:
|
||||
self.assertEqual(self.settings["enabledPlugins"], {"harness@claude-harness": True})
|
||||
source = self.settings["extraKnownMarketplaces"]["claude-harness"]["source"]
|
||||
self.assertEqual(source, {"source": "git",
|
||||
"url": "https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git"})
|
||||
|
||||
def test_the_hook_script_runs_from_the_command_line(self) -> None:
|
||||
for event in hooks.EVENTS:
|
||||
result = subprocess.run([sys.executable, str(SCRIPTS / "hooks/hooks.py"), event], input="{}",
|
||||
capture_output=True, text=True, timeout=10, cwd=tempfile.gettempdir())
|
||||
self.assertEqual(result.returncode, 0, event + result.stderr)
|
||||
result = subprocess.run([sys.executable, str(SCRIPTS / "hooks/hooks.py"), "nope"], input="{}",
|
||||
capture_output=True, text=True, timeout=10)
|
||||
self.assertEqual(result.returncode, 1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,59 @@
|
||||
"""docs/ledger/estimates.jsonl의 줄이 docs/ledger/README.md 형식인지 본다. 빈 파일(복사한 프로젝트)도 통과한다.
|
||||
|
||||
python3 -m unittest discover -s scripts/tests
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import unittest
|
||||
from datetime import datetime
|
||||
from pathlib import Path
|
||||
|
||||
REPO = Path(__file__).resolve().parent.parent.parent
|
||||
LEDGER = REPO / "docs/ledger/estimates.jsonl"
|
||||
KINDS = {"estimate", "actual", "retro"}
|
||||
COMMON = ("schema", "kind", "task", "recorded_at")
|
||||
RANGES = ("minutes", "calls", "output_tokens")
|
||||
|
||||
|
||||
def lines() -> list[dict]:
|
||||
if not LEDGER.exists():
|
||||
return []
|
||||
return [json.loads(line) for line in LEDGER.read_text(encoding="utf-8").splitlines() if line.strip()]
|
||||
|
||||
|
||||
class LedgerTest(unittest.TestCase):
|
||||
def test_lines_merge_by_union(self) -> None:
|
||||
self.assertIn("docs/ledger/estimates.jsonl merge=union",
|
||||
(REPO / ".gitattributes").read_text(encoding="utf-8").splitlines())
|
||||
|
||||
def test_every_line_is_json_with_the_common_fields(self) -> None:
|
||||
for number, entry in enumerate(lines(), start=1):
|
||||
self.assertTrue(set(COMMON) <= entry.keys(), f"line {number}: {sorted(set(COMMON) - entry.keys())}")
|
||||
self.assertEqual(entry["schema"], 1, number)
|
||||
self.assertIn(entry["kind"], KINDS, number)
|
||||
datetime.fromisoformat(entry["recorded_at"])
|
||||
|
||||
def test_an_estimate_has_ordered_ranges_and_a_basis(self) -> None:
|
||||
for entry in (e for e in lines() if e["kind"] == "estimate"):
|
||||
for field in RANGES:
|
||||
values = entry[field]
|
||||
self.assertLessEqual(values["p30"], values["p50"], (entry["task"], field))
|
||||
self.assertLessEqual(values["p50"], values["p80"], (entry["task"], field))
|
||||
self.assertTrue(entry["basis"].strip(), entry["task"])
|
||||
|
||||
def test_an_actual_follows_its_estimate_and_names_the_band_it_fell_in(self) -> None:
|
||||
entries = lines()
|
||||
for position, entry in enumerate(entries):
|
||||
if entry["kind"] != "actual":
|
||||
continue
|
||||
estimates = [e for e in entries[:position] if e["kind"] == "estimate" and e["task"] == entry["task"]]
|
||||
self.assertTrue(estimates, f"{entry['task']}: an actual line needs an earlier estimate line")
|
||||
bands = estimates[-1]["minutes"]
|
||||
expected = next((band for band in ("p30", "p50", "p80") if entry["active_minutes"] <= bands[band]), "over")
|
||||
self.assertEqual(entry["within"], expected, entry["task"])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,150 @@
|
||||
"""scripts/verify.sh의 시험. 단계를 계약 파일에서 읽는지, 잘못된 인자를 원격에 보내기 전에 거절하는지,
|
||||
지금 트리를 원격 worktree로 옮겨 같은 트리에서 돌리고 지우는지를 표준 라이브러리와 git·bash·flock으로 본다.
|
||||
원격은 가짜 ssh(호스트를 무시하고 이 기계에서 실행)다. pnpm은 돌리지 않는다.
|
||||
|
||||
python3 -m unittest discover -s scripts/tests
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import shutil
|
||||
import subprocess
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
REPO = Path(__file__).resolve().parent.parent.parent
|
||||
VERIFY = REPO / "scripts/verify.sh"
|
||||
GIT_ENV = {"GIT_AUTHOR_NAME": "t", "GIT_AUTHOR_EMAIL": "t@example.com", "GIT_COMMITTER_NAME": "t",
|
||||
"GIT_COMMITTER_EMAIL": "t@example.com", "GIT_CONFIG_COUNT": "1", "GIT_CONFIG_KEY_0": "core.hooksPath",
|
||||
"GIT_CONFIG_VALUE_0": "/dev/null"}
|
||||
|
||||
|
||||
def sh(args: list[str], cwd: Path, env: dict | None = None, check: bool = True) -> subprocess.CompletedProcess:
|
||||
result = subprocess.run(args, cwd=cwd, env={**os.environ, **GIT_ENV, **(env or {})}, capture_output=True,
|
||||
text=True, timeout=60)
|
||||
if check and result.returncode != 0:
|
||||
raise AssertionError(f"{args} → {result.returncode}\n{result.stdout}\n{result.stderr}")
|
||||
return result
|
||||
|
||||
|
||||
def gates() -> dict:
|
||||
return json.loads((REPO / "config/ci/gates.json").read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
class StagePlanTest(unittest.TestCase):
|
||||
def test_a_stage_runs_every_gate_the_contract_lists(self) -> None:
|
||||
for stage in gates()["stages"]:
|
||||
with self.subTest(stage=stage["id"]):
|
||||
result = sh([str(VERIFY), stage["id"], "--dry-run"], cwd=REPO)
|
||||
planned = [line.split(":")[0] for line in result.stdout.splitlines()]
|
||||
self.assertEqual(planned, stage["gateIds"])
|
||||
self.assertIn(f"ci:gate {stage['gateIds'][0]}", result.stdout)
|
||||
|
||||
def test_parts_runs_each_command_of_the_gate(self) -> None:
|
||||
contract = gates()
|
||||
gate = next(g for g in contract["gates"] if g["id"] == "FE-GATE-013")
|
||||
scripts = {c["id"]: c["script"] for c in contract["commands"]}
|
||||
result = sh([str(VERIFY), "parts", "FE-GATE-013", "--dry-run"], cwd=REPO)
|
||||
self.assertEqual([line.split(": ", 1)[1] for line in result.stdout.splitlines()],
|
||||
[f"corepack pnpm -s {scripts[c]}" for c in gate["commandIds"]])
|
||||
|
||||
def test_arguments_after_the_separator_go_to_the_one_script_or_command_as_given(self) -> None:
|
||||
result = sh([str(VERIFY), "script", "test:sample-removal", "--dry-run", "--", "--feature=invoice-feature"],
|
||||
cwd=REPO)
|
||||
self.assertEqual(result.stdout.strip(),
|
||||
"test:sample-removal: corepack pnpm -s test:sample-removal --feature=invoice-feature")
|
||||
result = sh([str(VERIFY), "exec", "--dry-run", "--", "node", "scripts/run-vitest.ts", "run", "tests/a b.test.ts"],
|
||||
cwd=REPO)
|
||||
self.assertEqual(result.stdout.strip(), r"exec node: node scripts/run-vitest.ts run tests/a\ b.test.ts")
|
||||
|
||||
def test_wrong_arguments_are_refused_here_before_anything_is_sent(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as folder:
|
||||
calls = Path(folder) / "calls"
|
||||
fake_ssh = Path(folder) / "ssh"
|
||||
fake_ssh.write_text(f'#!/bin/sh\necho "$@" >> {calls}\n', encoding="utf-8")
|
||||
fake_ssh.chmod(0o755)
|
||||
for args in (["nope"], ["gate", "FE-GATE-999"], ["parts"], ["gate"], ["merge", "extra"], ["docs", "x"],
|
||||
["script", "a", "b", "--", "--x"], ["exec"], ["exec", "--"], ["script", "--", "x"]):
|
||||
with self.subTest(args=args):
|
||||
result = sh([str(VERIFY), *args], cwd=REPO, env={"VERIFY_SSH": str(fake_ssh)}, check=False)
|
||||
self.assertEqual(result.returncode, 2, result.stderr)
|
||||
self.assertFalse(calls.exists(), "a refused command must not reach the remote host")
|
||||
|
||||
|
||||
class CiEnvironmentTest(unittest.TestCase):
|
||||
def test_the_ci_env_names_the_head_commit_and_its_time(self) -> None:
|
||||
# parts and script run the gate commands without ci:gate, which would otherwise set SOURCE_DATE_EPOCH.
|
||||
script = (f'eval "$(sed -n "/^ci_env()/,/^}}/p" {VERIFY})"; ci_env; '
|
||||
'echo "$CI $VITE_COMMIT_SHA $SOURCE_DATE_EPOCH $CI_RUNNER_IMAGE"')
|
||||
ci, sha, epoch, image = sh(["bash", "-c", script], cwd=REPO).stdout.split()
|
||||
self.assertEqual(ci, "true")
|
||||
self.assertEqual(sha, sh(["git", "rev-parse", "HEAD"], cwd=REPO).stdout.strip())
|
||||
self.assertEqual(epoch, sh(["git", "log", "-1", "--format=%ct"], cwd=REPO).stdout.strip())
|
||||
self.assertRegex(image, r"@sha256:[0-9a-f]{64}$")
|
||||
|
||||
|
||||
class RemoteTransportTest(unittest.TestCase):
|
||||
"""--on <호스트>: the patch lands in a fresh worktree, the tree matches, the run is logged, the worktree goes."""
|
||||
|
||||
def test_the_working_tree_is_run_remotely_on_the_same_tree_and_cleaned_up(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as folder:
|
||||
base = Path(folder)
|
||||
project, bare, remote, logs = (base / name for name in ("project", "origin.git", "remote", "logs"))
|
||||
(project / "scripts").mkdir(parents=True)
|
||||
(project / "config/ci").mkdir(parents=True)
|
||||
shutil.copy(VERIFY, project / "scripts/verify.sh")
|
||||
shutil.copy(REPO / "config/ci/gates.json", project / "config/ci/gates.json")
|
||||
shutil.copy(REPO / ".nvmrc", project / ".nvmrc")
|
||||
(project / "scripts/check-work-docs.py").write_text("print('docs checked')\n", encoding="utf-8")
|
||||
sh(["git", "init", "-q", "-b", "main"], cwd=project)
|
||||
sh(["git", "add", "-A"], cwd=project)
|
||||
sh(["git", "commit", "-q", "-m", "init"], cwd=project)
|
||||
sh(["git", "clone", "-q", "--bare", str(project), str(bare)], cwd=base)
|
||||
sh(["git", "remote", "add", "origin", str(bare)], cwd=project)
|
||||
sh(["git", "fetch", "-q", "origin"], cwd=project)
|
||||
sh(["git", "clone", "-q", str(bare), str(remote)], cwd=base)
|
||||
(project / "notes.md").write_text("커밋 안 한 새 파일\n", encoding="utf-8")
|
||||
with (project / "scripts/check-work-docs.py").open("a", encoding="utf-8") as handle:
|
||||
handle.write("print('changed here')\n")
|
||||
fake_ssh = base / "fake-ssh"
|
||||
fake_ssh.write_text('#!/bin/sh\nshift\nexec bash -c "$*"\n', encoding="utf-8")
|
||||
fake_ssh.chmod(0o755)
|
||||
env = {"VERIFY_SSH": str(fake_ssh), "VERIFY_REMOTE_REPO": str(remote), "VERIFY_LOCK": str(base / "lock"),
|
||||
"VERIFY_LOG_ROOT": str(logs), "VERIFY_NODE_BIN": "/nonexistent"}
|
||||
temp_index = base / "index"
|
||||
shutil.copy(project / ".git/index", temp_index)
|
||||
sh(["git", "add", "-A"], cwd=project, env={"GIT_INDEX_FILE": str(temp_index)})
|
||||
here = sh(["git", "write-tree"], cwd=project, env={"GIT_INDEX_FILE": str(temp_index)}).stdout.strip()
|
||||
|
||||
result = sh(["scripts/verify.sh", "docs", "--on", "build-host", "--log", "t"], cwd=project, env=env,
|
||||
check=False)
|
||||
|
||||
self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
|
||||
summary = (logs / "t/summary.txt").read_text(encoding="utf-8")
|
||||
self.assertTrue(summary.startswith(f"tree {here} commit "), summary)
|
||||
self.assertIn("rc=0", summary)
|
||||
self.assertIn("changed here", (logs / "t/run.log").read_text(encoding="utf-8"))
|
||||
self.assertFalse((logs / "t/install.log").exists(), "a laptop stage installs nothing")
|
||||
worktrees = sh(["git", "worktree", "list"], cwd=remote).stdout.strip().splitlines()
|
||||
self.assertEqual(len(worktrees), 1, worktrees)
|
||||
self.assertEqual(sh(["git", "status", "--porcelain"], cwd=remote).stdout, "")
|
||||
self.assertEqual((logs / "t/changes.patch").read_text(encoding="utf-8"), "")
|
||||
|
||||
made = sh(["scripts/verify.sh", "exec", "--on", "build-host", "--log", "t2", "--apply-back", "--", "bash", "-c",
|
||||
"echo made > made.txt && echo more >> notes.md"], cwd=project,
|
||||
env={**env, "VERIFY_INSTALL": "0"}, check=False)
|
||||
self.assertEqual(made.returncode, 0, made.stdout + made.stderr)
|
||||
self.assertEqual((project / "made.txt").read_text(encoding="utf-8"), "made\n")
|
||||
self.assertEqual((project / "notes.md").read_text(encoding="utf-8"), "커밋 안 한 새 파일\nmore\n")
|
||||
self.assertIn("2개를 이 작업 트리에 얹었다", made.stderr)
|
||||
|
||||
missing = sh(["scripts/verify.sh", "docs", "--on", "build-host"], cwd=project,
|
||||
env={**env, "VERIFY_REMOTE_REPO": str(base / "missing")}, check=False)
|
||||
self.assertEqual(missing.returncode, 4)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Executable
+321
@@ -0,0 +1,321 @@
|
||||
#!/usr/bin/env bash
|
||||
# 검증 진입점. 사람·CI·에이전트가 같은 명령을 쓴다(docs/work/reference/gates.md).
|
||||
#
|
||||
# scripts/verify.sh <단계> [대상…] [--on here|<호스트>] [--log <이름>] [--apply-back] [--dry-run] [-- 인자…]
|
||||
#
|
||||
# 단계 무엇 기본 위치
|
||||
# docs 작업 매뉴얼 검사(check-work-docs.py)와 장부 형식 여기
|
||||
# hooks repo 훅·검사기·장부 시험(python3 unittest) 여기
|
||||
# gate <FE-GATE-NNN>… 게이트마다 `corepack pnpm ci:gate <ID>`, CI env로 desktop
|
||||
# parts <FE-GATE-NNN> 그 게이트의 명령을 하나씩 끝까지(첫 실패에서 멈추지 않음) desktop
|
||||
# script <이름>… [-- 인자] package script를 하나씩. `--` 뒤 인자는 script가 하나일 때만 desktop
|
||||
# exec -- <명령…> 명령 하나(예: node scripts/run-vitest.ts run <파일>) desktop
|
||||
# <stage id> config/ci/gates.json stages의 gateIds 전부(merge 등) desktop
|
||||
#
|
||||
# 게이트·stage는 실패가 있어도 끝까지 돌고, 끝에 게이트마다 rc와 초를 적는다. 실패가 하나라도 있으면 rc=1.
|
||||
# --on <호스트>: 지금 작업 트리(커밋 안 된 변경 포함)를 패치로 그 호스트에 옮긴다. 기준 커밋에서 새 worktree를
|
||||
# 만들어 패치를 적용하고 트리 해시가 여기와 같은지 본 뒤, 그 트리를 커밋 하나로 만들어(깨끗한 HEAD) 의존성을
|
||||
# 오프라인으로 설치하고 잠금 아래에서 같은 단계를 돌린다. 로그를 남기고 worktree를 지운다. push하지 않는다.
|
||||
# 원격에서 바뀐 파일은 로그 폴더의 changes.patch에 남는다. --apply-back이면 그 패치를 여기 작업 트리에 얹는다
|
||||
# (create:feature, 기준선 다시 쓰기처럼 파일을 만드는 명령). VERIFY_SNAPSHOT=1이면 artifacts·dist·test-results를
|
||||
# 로그 폴더의 snapshot/에 복사한다(리뷰어가 함께 읽는 사본).
|
||||
# 환경 변수: VERIFY_HOST(desktop 단계의 --on 기본값, 기본 desktop), VERIFY_REMOTE_REPO(원격 checkout, 기본
|
||||
# workspace/<repo 이름>, 홈 기준), VERIFY_BASE_REF(기본 origin/main), VERIFY_LOCK(기본 /tmp/claude-gates/heavy.lock),
|
||||
# VERIFY_LOG_ROOT(원격 로그 폴더, 기본 /tmp/claude-gates), VERIFY_SSH(기본 ssh), VERIFY_NODE_BIN(원격 node 폴더,
|
||||
# 기본 ~/.nvm/versions/node/v<.nvmrc>/bin), VERIFY_INSTALL(0이면 원격 의존성 설치를 건너뛴다).
|
||||
# 종료 코드: 0 통과, 1 실패, 2 사용법, 4 원격 준비 실패.
|
||||
set -euo pipefail
|
||||
|
||||
ROOT=$(git rev-parse --show-toplevel)
|
||||
cd "$ROOT"
|
||||
TMP_FILES=()
|
||||
trap '[ ${#TMP_FILES[@]} -eq 0 ] || rm -f "${TMP_FILES[@]}"' EXIT # 빈 배열 + set -u는 옛 bash에서 오류다
|
||||
DRY_RUN=0
|
||||
APPLY_BACK=0
|
||||
|
||||
usage() {
|
||||
sed -n '2,26p' "$0" | sed 's/^# \{0,1\}//' >&2
|
||||
exit 2
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------- config/ci/gates.json 읽기
|
||||
|
||||
gates_json() {
|
||||
python3 - "$@" <<'PY'
|
||||
import json, sys
|
||||
contract = json.load(open("config/ci/gates.json", encoding="utf-8"))
|
||||
kind, *names = sys.argv[1:]
|
||||
if kind == "stages":
|
||||
print("\n".join(stage["id"] for stage in contract["stages"]))
|
||||
elif kind == "stage":
|
||||
found = [stage for stage in contract["stages"] if stage["id"] == names[0]]
|
||||
if not found:
|
||||
sys.exit(1)
|
||||
print("\n".join(found[0]["gateIds"]))
|
||||
elif kind == "gate":
|
||||
if not any(gate["id"] == names[0] for gate in contract["gates"]):
|
||||
sys.exit(1)
|
||||
elif kind == "scripts":
|
||||
gate = next((gate for gate in contract["gates"] if gate["id"] == names[0]), None)
|
||||
if gate is None:
|
||||
sys.exit(1)
|
||||
commands = {command["id"]: command for command in contract["commands"]}
|
||||
for command_id in gate["commandIds"]:
|
||||
command = commands[command_id]
|
||||
print(f'{command["script"]}\t{command.get("expect", "pass")}\t{command.get("expectedExitCode", "")}')
|
||||
PY
|
||||
}
|
||||
|
||||
is_stage() { gates_json stages | grep -qx -- "$1"; }
|
||||
|
||||
# ---------------------------------------------------------------- 단계 본문
|
||||
|
||||
run_docs() {
|
||||
local rc=0
|
||||
python3 scripts/check-work-docs.py || rc=1
|
||||
if [ -s docs/ledger/estimates.jsonl ] && ! python3 -c '
|
||||
import json, sys
|
||||
for number, line in enumerate(open(sys.argv[1], encoding="utf-8"), 1):
|
||||
if line.strip():
|
||||
json.loads(line)
|
||||
' docs/ledger/estimates.jsonl; then
|
||||
echo "docs/ledger/estimates.jsonl에 JSON이 아닌 줄이 있다." >&2
|
||||
rc=1
|
||||
fi
|
||||
return "$rc"
|
||||
}
|
||||
|
||||
run_hooks() { python3 -m unittest discover -s scripts/tests; }
|
||||
|
||||
# CI workflow의 전역 env(.gitea/workflows/quality-gates.yml)와 같은 꼴. CI=true가 있어야 빌드 식별값을 엄격하게 본다.
|
||||
ci_env() {
|
||||
local sha
|
||||
sha=$(git rev-parse HEAD)
|
||||
export CI=true VITE_COMMIT_SHA="$sha" VITE_BUILD_ID="gitea-${VERIFY_RUN:-1}-1" \
|
||||
RELEASE_ID="refs/heads/${VERIFY_REF:-verify}-${VERIFY_RUN:-1}-1" \
|
||||
CI_RUNNER_IMAGE="local/runner@sha256:$(printf 'a%.0s' $(seq 64))" \
|
||||
SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)"
|
||||
# ci:gate makes SOURCE_DATE_EPOCH from HEAD itself; parts and script call the commands directly.
|
||||
}
|
||||
|
||||
# 한 줄 결과: "<이름> rc=<n> <초>s". 로그는 VERIFY_STEP_LOGS가 있으면 그 폴더에 이름별로.
|
||||
step() {
|
||||
local name=$1 rc start log
|
||||
shift
|
||||
if [ "$DRY_RUN" = 1 ]; then
|
||||
local shown
|
||||
shown=$(printf '%q ' "$@")
|
||||
echo "$name: ${shown% }"
|
||||
return 0
|
||||
fi
|
||||
start=$(date +%s)
|
||||
log=${VERIFY_STEP_LOGS:+$VERIFY_STEP_LOGS/$(printf '%s' "$name" | tr ' /:' '___').log}
|
||||
set +e
|
||||
if [ -n "$log" ]; then "$@" > "$log" 2>&1; else "$@"; fi
|
||||
rc=$?
|
||||
set -e
|
||||
echo "$name rc=$rc $(( $(date +%s) - start ))s" | tee -a "${VERIFY_SUMMARY:-/dev/null}"
|
||||
return "$rc"
|
||||
}
|
||||
|
||||
run_gates() {
|
||||
local failed=0 gate
|
||||
[ "$DRY_RUN" = 1 ] || ci_env
|
||||
for gate in "$@"; do
|
||||
gates_json gate "$gate" || { echo "verify: config/ci/gates.json에 없는 게이트: $gate" >&2; return 2; }
|
||||
step "$gate" corepack pnpm -s ci:gate "$gate" || failed=1
|
||||
done
|
||||
return "$failed"
|
||||
}
|
||||
|
||||
run_parts() {
|
||||
local gate=$1 failed=0 script expect code rc
|
||||
[ "$DRY_RUN" = 1 ] || ci_env
|
||||
gates_json scripts "$gate" > /dev/null || { echo "verify: config/ci/gates.json에 없는 게이트: $gate" >&2; return 2; }
|
||||
while IFS=$'\t' read -r script expect code; do
|
||||
rc=0
|
||||
step "$gate $script" corepack pnpm -s "$script" || rc=$?
|
||||
# expect=fail인 명령(음성 fixture)은 정해진 종료 코드로 실패해야 통과다.
|
||||
if [ "$expect" = fail ]; then
|
||||
[ "$DRY_RUN" = 1 ] || [ "$rc" = "${code:-1}" ] || failed=1
|
||||
elif [ "$rc" != 0 ]; then
|
||||
failed=1
|
||||
fi
|
||||
done < <(gates_json scripts "$gate")
|
||||
return "$failed"
|
||||
}
|
||||
|
||||
# script 이름들, 그 뒤에 `--`와 인자(script가 하나일 때만, check_args가 본다).
|
||||
run_scripts() {
|
||||
local failed=0 names=() script
|
||||
while [ $# -gt 0 ] && [ "$1" != -- ]; do names+=("$1"); shift; done
|
||||
[ $# -eq 0 ] || shift
|
||||
for script in "${names[@]}"; do
|
||||
step "$script" corepack pnpm -s "$script" "$@" || failed=1
|
||||
done
|
||||
return "$failed"
|
||||
}
|
||||
|
||||
run_exec() {
|
||||
[ "${1:-}" = -- ] && shift
|
||||
step "exec $1" "$@"
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------- 실행 위치
|
||||
|
||||
laptop_stage() { [ "$1" = docs ] || [ "$1" = hooks ]; }
|
||||
|
||||
# 원격으로 보내기 전에 여기서 사용법을 본다. 잘못된 단계 때문에 desktop에 worktree를 만들지 않는다.
|
||||
check_args() {
|
||||
local stage=$1 gate
|
||||
shift
|
||||
case "$stage" in
|
||||
docs | hooks) [ $# -eq 0 ] || usage ;;
|
||||
gate) [ $# -gt 0 ] || usage
|
||||
for gate in "$@"; do gates_json gate "$gate" || { echo "verify: config/ci/gates.json에 없는 게이트: $gate" >&2; exit 2; }; done ;;
|
||||
parts) [ $# -eq 1 ] || usage
|
||||
gates_json gate "$1" || { echo "verify: config/ci/gates.json에 없는 게이트: $1" >&2; exit 2; } ;;
|
||||
script)
|
||||
local names=0
|
||||
while [ $# -gt 0 ] && [ "$1" != -- ]; do names=$((names + 1)); shift; done
|
||||
[ "$names" -gt 0 ] || usage
|
||||
# 인자는 script 하나에만 준다. 여럿에 같은 인자를 주면 뜻이 갈린다.
|
||||
[ $# -le 1 ] || [ "$names" -eq 1 ] || usage ;;
|
||||
exec) { [ "${1:-}" = -- ] && [ $# -gt 1 ]; } || usage ;;
|
||||
*) is_stage "$stage" || usage; [ $# -eq 0 ] || usage ;;
|
||||
esac
|
||||
}
|
||||
|
||||
run_here() {
|
||||
local stage=$1
|
||||
shift
|
||||
case "$stage" in
|
||||
docs | hooks) [ $# -eq 0 ] || usage; [ "$DRY_RUN" = 1 ] && { echo "$stage"; return 0; }; "run_$stage" ;;
|
||||
gate) [ $# -gt 0 ] || usage; run_gates "$@" ;;
|
||||
parts) [ $# -eq 1 ] || usage; run_parts "$1" ;;
|
||||
script) [ $# -gt 0 ] || usage; run_scripts "$@" ;;
|
||||
exec) run_exec "$@" ;;
|
||||
*)
|
||||
is_stage "$stage" || usage
|
||||
[ $# -eq 0 ] || usage
|
||||
# shellcheck disable=SC2046 # 게이트 ID는 공백 없는 낱말이다
|
||||
run_gates $(gates_json stage "$stage")
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
run_remote() {
|
||||
local host=$1 log=$2 ssh=${VERIFY_SSH:-ssh}
|
||||
shift 2
|
||||
local name base tree tmp_index patch id remote_repo lock log_root node_bin args ref install=${VERIFY_INSTALL:-1} rc=0 back
|
||||
name=$(basename "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")")
|
||||
remote_repo=${VERIFY_REMOTE_REPO:-"workspace/$name"}
|
||||
lock=${VERIFY_LOCK:-/tmp/claude-gates/heavy.lock}
|
||||
log_root=${VERIFY_LOG_ROOT:-/tmp/claude-gates}
|
||||
node_bin=${VERIFY_NODE_BIN:-"\$HOME/.nvm/versions/node/v$(tr -d '[:space:]' < .nvmrc)/bin"}
|
||||
base=$(git merge-base HEAD "${VERIFY_BASE_REF:-origin/main}")
|
||||
ref=$(git branch --show-current | tr '/' '-')
|
||||
laptop_stage "$1" && install=0
|
||||
tmp_index=$(mktemp)
|
||||
patch=$(mktemp)
|
||||
TMP_FILES+=("$tmp_index" "$patch")
|
||||
cp "$(git rev-parse --git-path index)" "$tmp_index"
|
||||
GIT_INDEX_FILE=$tmp_index git add -A
|
||||
tree=$(GIT_INDEX_FILE=$tmp_index git write-tree)
|
||||
git diff --binary "$base" "$tree" > "$patch"
|
||||
id="verify-$(date +%s)-$$"
|
||||
# The stage first, then --on here, then the rest: an option after `--` would reach the command instead.
|
||||
args="$(printf '%q' "$1") --on here"
|
||||
[ $# -lt 2 ] || args+=" $(printf '%q ' "${@:2}")"
|
||||
echo "verify: $host에서 '$*' (기준 ${base:0:12}, 트리 ${tree:0:12}, 로그 $log_root/$log/)" >&2
|
||||
$ssh "$host" "cat > /tmp/$id.patch" < "$patch"
|
||||
$ssh "$host" bash -s <<EOF || rc=$?
|
||||
set -u
|
||||
export PATH="$node_bin:\$PATH"
|
||||
trap 'rm -f /tmp/$id.patch' EXIT
|
||||
cd $remote_repo || exit 4
|
||||
repo=\$(pwd)
|
||||
git cat-file -e $base^{commit} 2>/dev/null || git fetch -q origin || exit 4
|
||||
git cat-file -e $base^{commit} || { echo "기준 커밋 ${base:0:12}이 원격에 없다. 그 커밋을 push한다." >&2; exit 4; }
|
||||
wt=\$(mktemp -d /tmp/$id.XXXXXX)
|
||||
logs=$log_root/$log
|
||||
git worktree add -q --detach "\$wt" $base || exit 4
|
||||
cleanup() {
|
||||
cp -r "\$wt/artifacts/quality/gates" "\$logs/gate-artifacts" 2>/dev/null
|
||||
if [ "${VERIFY_SNAPSHOT:-0}" = 1 ]; then
|
||||
mkdir -p "\$logs/snapshot"
|
||||
for kept in artifacts dist test-results; do cp -r "\$wt/\$kept" "\$logs/snapshot/" 2>/dev/null; done
|
||||
fi
|
||||
cd "\$repo"
|
||||
git worktree remove --force "\$wt"
|
||||
rm -f /tmp/$id.patch
|
||||
}
|
||||
trap cleanup EXIT
|
||||
cd "\$wt"
|
||||
if [ -s /tmp/$id.patch ]; then git apply --binary --index /tmp/$id.patch || exit 4; fi
|
||||
got=\$(git write-tree)
|
||||
if [ "\$got" != "$tree" ]; then echo "트리 해시가 다르다: 원격 \$got, 여기 $tree" >&2; exit 4; fi
|
||||
# 게이트는 깨끗한 HEAD(커밋 식별값 = 트리)를 본다. 훅을 거치지 않는 commit-tree로 이 worktree에만 만든다.
|
||||
commit=\$(git -c user.name=verify -c user.email=verify@localhost commit-tree "\$got" -p HEAD -m "verify $id")
|
||||
git checkout -q --detach "\$commit"
|
||||
mkdir -p "\$(dirname $lock)" "\$logs"
|
||||
: > "\$logs/summary.txt"
|
||||
echo "tree $tree commit \$commit \$(date '+%F %T') load \$(cut -d' ' -f1 /proc/loadavg)" >> "\$logs/summary.txt"
|
||||
if [ $install = 1 ]; then
|
||||
CI=true corepack pnpm install --frozen-lockfile --offline > "\$logs/install.log" 2>&1 \
|
||||
|| CI=true corepack pnpm install --frozen-lockfile >> "\$logs/install.log" 2>&1 \
|
||||
|| { echo "의존성 설치 실패: \$logs/install.log" >&2; exit 4; }
|
||||
fi
|
||||
export VERIFY_SUMMARY="\$logs/summary.txt" VERIFY_STEP_LOGS="\$logs" VERIFY_REF="$ref"
|
||||
flock $lock ./scripts/verify.sh $args 2>&1 | tee "\$logs/run.log"
|
||||
rc=\${PIPESTATUS[0]}
|
||||
git status --porcelain > "\$logs/status-after.txt"
|
||||
git add -A > /dev/null 2>&1
|
||||
git diff --cached --binary HEAD > "\$logs/changes.patch"
|
||||
echo "rc=\$rc" >> "\$logs/summary.txt"
|
||||
exit \$rc
|
||||
EOF
|
||||
if [ "$APPLY_BACK" = 1 ]; then
|
||||
back=$(mktemp)
|
||||
TMP_FILES+=("$back")
|
||||
$ssh "$host" "cat $log_root/$log/changes.patch" > "$back" 2>/dev/null || :
|
||||
if [ ! -s "$back" ]; then
|
||||
echo "verify: 원격에서 바뀐 파일이 없다." >&2
|
||||
elif git apply --binary "$back"; then
|
||||
echo "verify: 원격에서 바뀐 파일 $(grep -c '^diff --git' "$back")개를 이 작업 트리에 얹었다(git status로 본다)." >&2
|
||||
else
|
||||
echo "verify: 원격 변경을 얹지 못했다. 패치는 $host:$log_root/$log/changes.patch" >&2
|
||||
[ "$rc" != 0 ] || rc=4
|
||||
fi
|
||||
fi
|
||||
return "$rc"
|
||||
}
|
||||
|
||||
main() {
|
||||
local stage=${1:-} on="" log="" rest=()
|
||||
[ -n "$stage" ] || usage
|
||||
shift
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--on) on=${2:?--on 뒤에 호스트}; shift 2 ;;
|
||||
--log) log=${2:?--log 뒤에 이름}; shift 2 ;;
|
||||
--dry-run) DRY_RUN=1; shift ;;
|
||||
--apply-back) APPLY_BACK=1; shift ;;
|
||||
--) rest+=("$@"); break ;;
|
||||
-*) usage ;;
|
||||
*) rest+=("$1"); shift ;;
|
||||
esac
|
||||
done
|
||||
check_args "$stage" ${rest[@]+"${rest[@]}"}
|
||||
if [ -z "$on" ]; then
|
||||
if laptop_stage "$stage"; then on=here; else on=${VERIFY_HOST:-desktop}; fi
|
||||
fi
|
||||
if [ "$on" = here ] || [ "$DRY_RUN" = 1 ]; then
|
||||
run_here "$stage" ${rest[@]+"${rest[@]}"}
|
||||
else
|
||||
log=${log:-"$(git branch --show-current | tr '/' '-')-$stage"}
|
||||
run_remote "$on" "${log:-detached}" "$stage" ${rest[@]+"${rest[@]}"}
|
||||
fi
|
||||
}
|
||||
|
||||
main "$@"
|
||||
@@ -0,0 +1,18 @@
|
||||
# AGENTS.md — `src/adapters` (재사용 capability runtime)
|
||||
|
||||
application 포트를 구현하는 HTTP, 인증, 저장소, query cache, telemetry, worker 등이다. 그룹마다 `src/adapters/<그룹>/index.ts`(배럴)가 공개 경계다.
|
||||
|
||||
## 지킬 것
|
||||
|
||||
- 그룹 밖에서는 배럴로만 들어온다. 2단계 `index.ts`는 공개 배럴이 아니다(예외 `storage/indexeddb`, `storage/opfs`).
|
||||
- 다른 adapter 그룹을 import하지 않는다(`adapters-do-not-know-other-concrete-adapters`). 예외는 kernel 셋(`src/adapters/platform/` 폴더 전체, `browser-file-storage/result.ts`, `cross-context-invalidation/index.ts`)뿐이고 새 파일 단위 예외를 만들지 않는다. 새 공유 프리미티브는 `src/adapters/platform/`에 둔다.
|
||||
- presentation·bootstrap을 import하지 않는다(`adapters-do-not-know-presentation`). 일반 worker는 네트워크·자격 증명 adapter를 모른다. Service Worker 입구는 페이지 코드가 아니다.
|
||||
- 실패 분류는 status와 code를 함께 본다. 짝 백엔드 쓰기 응답 판정은 `src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE` 하나다.
|
||||
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
|
||||
|
||||
## 검사
|
||||
|
||||
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
|
||||
- `check:adapter-inventory`(FE-GATE-010 안): 파일을 더하거나 옮기면 `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다(이 파일도 거기 행이 있다)
|
||||
- `check:browser-file-storage-boundaries`·`check:realtime-boundaries`(FE-GATE-010 안)
|
||||
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/integration`, `tests/contract`에 둔다(`.claude/rules/tests.md`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,16 @@
|
||||
# AGENTS.md — `src/application` (일반 유스케이스와 포트)
|
||||
|
||||
유스케이스, 포트, 정책, view-model이 있다. 구체 runtime을 모른다.
|
||||
|
||||
## 지킬 것
|
||||
|
||||
- presentation·adapters·bootstrap·React·TanStack을 import하지 않는다(`application-does-not-know-concrete-runtime`).
|
||||
- 포트는 추가만 한다. 시그니처를 깨야 하면 결정을 받고 BREAKING으로 커밋한다.
|
||||
- 결과 불명 쓰기의 재전송 판정은 한 곳에 둔다(`docs/manual/02-decision-tables.md` 3·4절).
|
||||
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
|
||||
|
||||
## 검사
|
||||
|
||||
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
|
||||
- `test:unit`(FE-GATE-005)
|
||||
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/unit`, 포트 소비자 계약은 `tests/contract`에 둔다(`.claude/rules/tests.md`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,15 @@
|
||||
# AGENTS.md — `src/apps` (배포 단위)
|
||||
|
||||
앱마다 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다.
|
||||
|
||||
## 지킬 것
|
||||
|
||||
- adapter를 직접 import하지 않는다(`feature-and-app-roots-do-not-reach-adapters`). 조립은 `src/bootstrap`이 한다.
|
||||
- 선언은 작은 리터럴 머리다. `scripts/generate-product-feature-index.ts`가 읽어 `src/.generated/`를 만든다. 선언 모양을 바꾸면 그 생성기와 함께 고친다.
|
||||
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
|
||||
|
||||
## 검사
|
||||
|
||||
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
|
||||
- `check:scale:pr`(FE-GATE-005 안): 앱·context 예산
|
||||
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/unit`에 둔다(`.claude/rules/tests.md`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,17 @@
|
||||
# AGENTS.md — `src/bootstrap` (조립 뿌리)
|
||||
|
||||
런타임 설정을 읽고, 구체 adapter를 만들어 application 포트에 끼우고, React를 붙이는 곳이다. 구체 adapter를 조립하는 곳은 여기 하나다.
|
||||
|
||||
## 지킬 것
|
||||
|
||||
- 업무 규칙을 두지 않는다. 판정·정책은 `src/application`·`src/platform`·기능 폴더에 둔다.
|
||||
- 선택하지 않은 realtime·web-push runtime을 조립하지 않는다(`unselected-realtime-runtime-is-not-composed`). 기능 runtime은 `src/features/loaded-feature-runtimes.ts`만 불러온다(`boot-does-not-load-every-feature-runtime`).
|
||||
- 제품마다 다른 조립은 제품 소유 파일 `src/bootstrap/product-composition.ts`에 둔다. 템플릿 소유 파일을 고쳐야 하면 결함이다.
|
||||
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
|
||||
|
||||
## 검사
|
||||
|
||||
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
|
||||
- `build`(FE-GATE-011), `check:bundle`(FE-GATE-012): 초기 JS·파일 수 예산
|
||||
- 런타임 설정 키를 바꾸면 루트 `README.md` 런타임 변수 표와 `verify:documentation`
|
||||
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/integration`(조립된 경계), `tests/e2e`에 둔다(`.claude/rules/tests.md`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,16 @@
|
||||
# AGENTS.md — `src/contexts` (bounded context)
|
||||
|
||||
context마다 `context-module.ts`가 앱, 라우트 뿌리, 기능 예산을 선언한다. 생성 명령 `create:feature`가 새 context를 만든다.
|
||||
|
||||
## 지킬 것
|
||||
|
||||
- context끼리 import하지 않는다(`contexts-do-not-import-other-contexts`). adapter를 직접 import하지 않는다(`feature-and-app-roots-do-not-reach-adapters`).
|
||||
- context 폴더를 손으로 만들거나 경계를 바꾸는 일은 크기가 큼이다(`docs/work/new-feature.md` 3절).
|
||||
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
|
||||
|
||||
## 검사
|
||||
|
||||
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
|
||||
- `check:scale:pr`(FE-GATE-005 안): 기능 예산
|
||||
- FE-GATE-020: 기능을 더하고 지운 사본
|
||||
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/unit`에 둔다(`.claude/rules/tests.md`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,17 @@
|
||||
# AGENTS.md — `src/contracts` (공유 어휘와 레지스트리)
|
||||
|
||||
여러 계층, worker, 빌드·릴리스 스크립트가 함께 읽는 타입·스키마·레지스트리다. 공유 타입을 어디 둘지는 `docs/architecture/contract-ownership.md` 「Decision rule」이다.
|
||||
|
||||
## 지킬 것
|
||||
|
||||
- application·features·presentation·bootstrap을 import하지 않는다(`contracts-do-not-know-application`, `contracts-do-not-know-presentation-or-bootstrap`). zod는 여기의 `zod.ts`로만 들어간다.
|
||||
- 레지스트리 행은 원본(스키마, descriptor)에서 뽑는다. 손으로 다시 적으면 대조 테스트를 같이 둔다.
|
||||
- 제품마다 다른 계약은 제품 소유 파일 `src/contracts/product-contracts.ts`에 둔다.
|
||||
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
|
||||
|
||||
## 검사
|
||||
|
||||
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
|
||||
- `check:registries`(FE-GATE-010 안), `test:runtime-schema`(FE-GATE-004)
|
||||
- 짝 백엔드 계약 pin `config/contracts/backend-contract-pin.json`과 대조 테스트(FE-GATE-007)
|
||||
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/runtime-schema`, `tests/unit`에 둔다(`.claude/rules/tests.md`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,19 @@
|
||||
# AGENTS.md — `src/features` (지울 수 있는 기능)
|
||||
|
||||
기능 하나는 `src/features/<id>/{domain,application,contracts,adapters,presentation}`이고 기능 폴더째 지울 수 있다. 이 폴더 바로 아래의 `*.ts`는 설치된 기능 목록(카탈로그)이다.
|
||||
새 기능은 `corepack pnpm create:feature <id>`로 만들고 `docs/manual/` 순서로 채운다(스킬 `new-feature`).
|
||||
|
||||
## 지킬 것
|
||||
|
||||
- 기능끼리 import하지 않는다(`features-do-not-import-other-features`). 공용이 필요하면 `src/contracts/`나 kernel로 옮기는 일을 따로 묻는다.
|
||||
- 기능 안 방향: domain은 framework·runtime을 모르고, application은 adapter·presentation을 모르고, presentation은 바깥 adapter를 모르고, adapters는 presentation을 모른다(`feature-*` 규칙 넷).
|
||||
- 기능 밖 adapter는 기능의 `adapters/`나 `feature-adapter-contribution.ts`로만 닿는다(`feature-and-app-roots-do-not-reach-adapters`). presentation은 직접 fetch하지 않는다(`presentation-does-not-fetch-directly`).
|
||||
- 기능 테스트는 `tests/features/<id>/`에 둔다. 플랫폼 테스트를 기능에 묶지 않는다.
|
||||
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
|
||||
|
||||
## 검사
|
||||
|
||||
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
|
||||
- FE-GATE-020: 생성한 기능을 더하고 지운 사본, 기능 제거는 `test:sample-removal -- --feature=<id>`
|
||||
- 초기 JS 기록(`config/scale/feature-shape-ceilings.json`)은 생성 출력 `Next:`의 명령으로 다시 쓴다
|
||||
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/features/<id>/`에 둔다(`.claude/rules/tests.md`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,15 @@
|
||||
# AGENTS.md — `src/platform` (제품과 무관한 프리미티브)
|
||||
|
||||
예산, 실행 문맥, 회복력, telemetry 파이프라인, 오류 봉투, 릴리스 일관성처럼 어느 폴더든 쓰는 것이다. adapter kernel(`src/adapters/platform/`)과는 다른 폴더다.
|
||||
|
||||
## 지킬 것
|
||||
|
||||
- features·contexts·apps·adapters·bootstrap·presentation·application을 import하지 않는다(`platform-kernel-is-product-neutral`, 예외 `platform/routing/`).
|
||||
- 확인하지 못한 판정은 `PASS`가 아니라 `UNVERIFIED`다. 상수 `true` 판정을 두지 않는다.
|
||||
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
|
||||
|
||||
## 검사
|
||||
|
||||
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
|
||||
- `test:unit`(FE-GATE-005)
|
||||
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/unit`에 둔다(`.claude/rules/tests.md`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -0,0 +1,17 @@
|
||||
# AGENTS.md — `src/presentation` (일반 UI와 들어오는 adapter)
|
||||
|
||||
라우트, 레이아웃, 디자인 시스템, 페이지, provider가 있다. 제품 기능이 아닌 일반 UI다.
|
||||
|
||||
## 지킬 것
|
||||
|
||||
- adapter·bootstrap을 import하지 않는다(`presentation-does-not-know-adapters`, 예외 `presentation/adapters/query`). 직접 fetch하지 않는다(`presentation-does-not-fetch-directly`).
|
||||
- 페이지 템플릿은 레이아웃만 가진다(`page-templates-own-layout-only`). 설치된 제품 기능은 정해진 파일만 조립한다(`generic-presentation-does-not-compose-the-product`). apps·contexts를 import하지 않는다(라우터 하나 예외).
|
||||
- 디자인 시스템은 `src/presentation/design-system/index.ts`로만 들어간다. 토큰 밖 색·간격을 쓰지 않는다(`docs/styling/design-tokens.md`).
|
||||
- 모든 `src/` 폴더에 걸리는 규칙(adapter는 배럴로만, zod는 `src/contracts/zod.ts`로만, 아이콘 vendor·디자인 시스템·외부 계약 패키지·관측 vendor는 정해진 입구로만)은 루트 `AGENTS.md` 꼭 지킬 것과 `docs/architecture/layers.md`다.
|
||||
|
||||
## 검사
|
||||
|
||||
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
|
||||
- `check:design-system`·`check:i18n`(FE-GATE-010 안)
|
||||
- `test:component`(FE-GATE-006), e2e·접근성(FE-GATE-008·009), 시각 골든(`tests/visual/`)
|
||||
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/component`, `tests/e2e`, `tests/visual`에 둔다(`.claude/rules/tests.md`).
|
||||
@@ -0,0 +1 @@
|
||||
@AGENTS.md
|
||||
@@ -11,6 +11,8 @@ import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts";
|
||||
* `docs/reviews/adapters/INVENTORY.md`. The removal fixtures rely on the same
|
||||
* promise: they do not copy `docs/`. A test that opens a review document broke
|
||||
* all three removal checks (fix of 11-04), so the promise is checked here.
|
||||
* The root instruction files left the list on 2026-11-07: they are the
|
||||
* template's contract, which a copy keeps (template-contract-documents.test.ts).
|
||||
*/
|
||||
// The history-free set of config/repository-layout.json (R2). The registry
|
||||
// itself names every root item, history documents included (R1); naming a
|
||||
@@ -30,7 +32,6 @@ const DELETABLE = [
|
||||
new RegExp(["docs", "superpowers"].join("/"), "u"),
|
||||
new RegExp(["docs", "history"].join("/"), "u"),
|
||||
new RegExp(`\\b${"SPEC"}\\.md\\b`, "u"),
|
||||
new RegExp(`\\b${"CLAUDE"}\\.md\\b`, "u"),
|
||||
];
|
||||
/**
|
||||
* 1101/14-01. A section number without a document name cannot be followed,
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
import { readFile } from "node:fs/promises";
|
||||
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
/**
|
||||
* Owner decision 2026-11-07 (docs/work/reference/decisions.md): the root
|
||||
* AGENTS.md and CLAUDE.md, `.claude/` and `docs/work/` are the template's
|
||||
* contract, which a copy keeps. So the README table of files a copy may delete
|
||||
* must not list them, and docs/README.md section 1 links the rule book and the
|
||||
* work manual, which makes verify:documentation check the paths, scripts and
|
||||
* gate IDs they name.
|
||||
*/
|
||||
const CONTRACT = Object.freeze(["AGENTS.md", "CLAUDE.md", ".claude", "docs/work"]);
|
||||
// Built from pieces: deletable-history-documents.test.ts fails on code that
|
||||
// names a folder a copy may delete.
|
||||
const PAST_PLANS = ["docs", "superpowers"].join("/");
|
||||
/** A row only the deletable-files table has; found by content so a translated heading still finds it. */
|
||||
const DELETABLE_ROW = `| \`${PAST_PLANS}/\` |`;
|
||||
|
||||
/** The paths in the first cells of the README table that holds DELETABLE_ROW. */
|
||||
function deletablePaths(readme: string): string[] {
|
||||
const lines = readme.split("\n");
|
||||
const row = lines.findIndex((line) => line.startsWith(DELETABLE_ROW));
|
||||
if (row === -1) throw new Error(`README.md has no table row starting with ${DELETABLE_ROW}`);
|
||||
let start = row;
|
||||
while (start > 0 && lines[start - 1]?.startsWith("|")) start -= 1;
|
||||
let end = row;
|
||||
while (lines[end + 1]?.startsWith("|")) end += 1;
|
||||
return lines
|
||||
.slice(start + 2, end + 1)
|
||||
.flatMap((line) => [...(line.split("|")[1] ?? "").matchAll(/`([^`]+)`/gu)].map(([, entry = ""]) => entry))
|
||||
.map((entry) => entry.replace(/\/$/u, ""));
|
||||
}
|
||||
|
||||
describe("template contract documents", () => {
|
||||
it("are not in the README table of files a copy may delete", async () => {
|
||||
const listed = deletablePaths(await readFile("README.md", "utf8"));
|
||||
expect(listed).toContain(PAST_PLANS);
|
||||
expect(listed.filter((entry) => CONTRACT.some((kept) => entry === kept || entry.startsWith(`${kept}/`))))
|
||||
.toEqual([]);
|
||||
});
|
||||
|
||||
it("are linked from the current-contract section of docs/README.md", async () => {
|
||||
const index = await readFile("docs/README.md", "utf8");
|
||||
const section = /^## 1\.[\s\S]*?(?=^## )/mu.exec(index)?.[0] ?? "";
|
||||
const links = [...section.matchAll(/\]\(([^)#\s]+)\)/gu)].map(([, target = ""]) => target);
|
||||
expect(links).toEqual(expect.arrayContaining(["../AGENTS.md", "work/", "work/reference/"]));
|
||||
});
|
||||
});
|
||||
@@ -23,7 +23,7 @@ import { REMOVAL_FIXTURE_COPY_TARGETS } from "../../scripts/lib/removal-fixture.
|
||||
*/
|
||||
const CHECKER = "scripts/verify-documentation-readiness.ts";
|
||||
/** What verify:documentation reads besides the code. */
|
||||
const DOCUMENTS = Object.freeze(["README.md", "CHANGELOG.md", "docs"]);
|
||||
const DOCUMENTS = Object.freeze(["README.md", "CHANGELOG.md", "docs", "AGENTS.md"]);
|
||||
|
||||
const LISTED_SAMPLE = Object.freeze({
|
||||
featureId: "listed-sample-feature",
|
||||
|
||||
Reference in New Issue
Block a user