docs: 살아 있는 문서의 낡은 문장을 지금 코드와 정본에 맞춘다
2026-11-07~08의 정리(문서 이동, 참조 기능 삭제, CI 재편) 뒤 살아 있는 문서가 지금 코드와 다른 말을 한다. - 현재 계약 문서 둘과 스타터 문서가 기록(docs/design/)을 정본으로 가리킨다. 정본을 frontend-application-foundation.md·src/bootstrap/, 패턴 표·계층 규칙으로 바꾸고 설계서는 배경으로 둔다(1112/02-06). - 실시간 대응표 둘(짝 백엔드 출구, poll attempt 결과)이 기록에만 있었다. optional-adapter-recipes.md로 옮기고 코드 주석·매뉴얼 03·설계서 머리 블록이 옮긴 곳을 가리킨다(1112/09-02). - 실행 격리 변수 목록을 설계 기록이 아니라 scripts/lib/run-isolation.ts로 가리킨다(1112/08-17). - 계약 소유 절 이름(「판단 규칙」), pin 대조 시험의 게이트(005·007), drift 검사 범위(1112/02-07). INVENTORY 머리의 손 숫자와 지킬 수 없는 꼬리 문장(1112/02-08). - 검증 안내: 검사기를 바꾸면 FE-GATE-029, 문서면 desktop verify:documentation(1112/08-05, 08-04). FE-GATE-012는 merge 단계다 (08-16). N6이 알리는 파일을 좁혀 적는다(08-10). 한 파일 시험은 verify.sh exec(08-11). 문서 검사 범위의 손 사본을 정본 한 곳으로(08-07). - create:feature 참조의 Next: 3과 되돌리기(08-08), 손으로 옮긴 숫자 (08-19), 라운드 없는 리뷰 ID 17곳에 0925를 붙인다(08-15). - secret scan 범위 설명(1112/07-03), lab이 기능 라우트를 읽는 문장 (1103/16-06), README 동기화 기준점·제품 소유 파일·선택 기능 결함 몫 (0929/14-02, 14-03, 13-10), 커밋을 다시 지은 모든 통합의 해시 대조 (1106/14-02). 고른 방법: 문장을 코드에 맞춘다. 표는 옮기고 숫자는 정본을 가리킨다. 버린 대안: 기록 문서 본문 고치기(기록은 머리 블록만 고친다). 위험·한계: 문서 검사 범위 목록을 지운 ci-quality-gates.md는 이제 docs/README.md 5절과 gates.md 7절을 읽어야 한다. 매뉴얼 02 7절 업로드 예의 declare module 문제(1112/09-01)는 고치는 방향이 check:architecture 규칙과 부딪쳐 결정 대기로 남긴다. 검증: scripts/verify.sh docs(노트북) 통과. desktop verify:documentation과 FE-GATE-005(문서를 읽는 시험)는 PR 본문에 적는다. Refs: 1112/02-06, 1112/02-07, 1112/02-08, 1112/07-03, 1112/08-04, 1112/08-05, 1112/08-07, 1112/08-08, 1112/08-10, 1112/08-11, 1112/08-15, 1112/08-16, 1112/08-17, 1112/08-19, 1112/09-02, 1103/16-06, 0929/14-02, 0929/14-03, 0929/13-10, 1106/14-02
This commit is contained in:
+1
-1
@@ -70,6 +70,6 @@
|
||||
|
||||
## 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/`는 상한이 없다.
|
||||
- 분량 상한이 있다: 지도(루트 `AGENTS.md`), 루트 `CLAUDE.md`, 폴더 지역 규칙(`src/**/AGENTS.md`, 옆에 `@AGENTS.md` 한 줄 `CLAUDE.md`), 이 README, playbook, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나). 줄 수의 정본은 `scripts/check-work-docs.py`의 상수이고, 넘으면 그 검사가 상한과 함께 알린다. `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)다.
|
||||
|
||||
@@ -77,7 +77,7 @@
|
||||
### 4.4 수정 라운드와 묶음
|
||||
|
||||
- 통합 브랜치 `fix/maturity-review-<YYYY-MM-DD>`(리뷰 날짜)를 만들고, 영역별 수정은 각자 worktree의 브랜치에서 한다. 다른 수정에 기대는 묶음은 그 수정이 합쳐진 뒤 시작한다. CHANGELOG·문서는 마지막에 한 세션이 다시 쓴다.
|
||||
- 총괄이 브랜치를 `--no-ff`로 하나씩 합치고, 합칠 때마다 커밋 전 게이트를 돌린다. 합친 뒤에만 생긴 실패는 README 「통합에서 생긴 것」에 적는다. 합친 트리에서 merge 단계를 돌리고 회차별 결과를 표로 남긴다.
|
||||
- 총괄이 브랜치를 `--no-ff`로 하나씩 합치고, 합칠 때마다 커밋 전 게이트를 돌린다. 합친 뒤에만 생긴 실패는 README 「통합에서 생긴 것」에 적는다. 합친 트리에서 merge 단계를 돌리고 회차별 결과를 표로 남긴다. 통합에서 커밋을 다시 지었으면(fixup 접기, rebase) 커밋 본문과 CHANGELOG가 적은 해시를 `git merge-base --is-ancestor <해시> <브랜치 끝>`으로 하나씩 대조하고, 결과를 PR 본문 「검증」에 적는다. 리뷰 라운드가 아닌 정리·기능 통합도 같다.
|
||||
- 큰 라운드는 작은 PR로 나눈다. 자기완결적인 변경 하나에 PR 하나(대략 100줄, 1,000줄이면 너무 크다). 리팩터링과 동작 변경은 PR을 나눈다. 병합은 소유자가 한다. 라운드 사이에 새 기능이나 큰 구조 변경을 넣지 않는다(발견 수가 줄어드는지 볼 수 없다).
|
||||
|
||||
### 4.5 멈춤 기준 — 이 repo는 하나다
|
||||
|
||||
@@ -94,7 +94,7 @@
|
||||
|
||||
## 9. 자주 하는 실수
|
||||
|
||||
- 노트북 checkout에서 한 파일 테스트쯤은 괜찮다고 돌린다. 한 파일도 desktop에서 `scripts/verify.sh script`나 `ssh desktop`으로 돌린다.
|
||||
- 노트북 checkout에서 한 파일 테스트쯤은 괜찮다고 돌린다. 한 파일도 desktop에서 `scripts/verify.sh exec -- node scripts/run-vitest.ts run <파일>`로 돌린다(4.1절).
|
||||
- 한 테스트 파일을 `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`에서 숫자를 옮긴다.
|
||||
|
||||
@@ -49,9 +49,10 @@ scripts/verify.sh <단계> [대상…] [--on here|<호스트>] [--log <이름>]
|
||||
| 브랜치를 합칠 때마다 | 커밋 전 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) |
|
||||
| 라우트 로딩·청크·초기 화면을 바꿀 때 | 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` |
|
||||
| 작업 매뉴얼·훅을 바꿀 때 | 노트북 `scripts/verify.sh docs`, `scripts/verify.sh hooks`. 문서(작업 매뉴얼, `.claude/` 아래 문서, `AGENTS.md`·`CLAUDE.md` 포함)를 바꿨으면 desktop `scripts/verify.sh script verify:documentation`도 |
|
||||
| 검사 script·그 fixture를 바꿀 때 | merge에 더해 `scripts/verify.sh gate FE-GATE-029`(검사기 자기 시험은 main 단계에 있다) |
|
||||
|
||||
release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회귀가 147커밋 동안 아무 게이트에도 걸리지 않은 일이 있다. 바꾼 것이 release 단계 게이트가 지키는 것에 닿으면 그 게이트도 돌린다.
|
||||
|
||||
@@ -103,7 +104,7 @@ release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회
|
||||
|
||||
`verify:documentation`(FE-GATE-017, documentation 단계)이 문서를 검사하는 범위와 방법의 정본은 `scripts/verify-documentation-readiness.ts`, `scripts/lib/docs-system.ts`와 `docs/README.md` 5절이다.
|
||||
|
||||
- **범위:** 살아 있는 문서 전부(루트 `AGENTS.md`·`README.md`, `docs/` 아래 기록 밖 문서, `src/`의 `AGENTS.md`·모듈 README, `.claude/` 아래 문서). 기록(`docs/design/`, `docs/history/`, `docs/adr/`)은 머리 블록만 본다.
|
||||
- **범위:** 살아 있는 문서 전부(루트 `AGENTS.md`·`README.md`, `docs/` 아래 기록 밖 문서, `src/`의 `AGENTS.md`·모듈 README, `.claude/` 아래 문서). 기록(`docs/design/`, `docs/history/`)은 머리 블록만 보고, 결정 기록(`docs/adr/`)은 본문의 언어·문체도 본다.
|
||||
- **보는 것:** 언어(한국어인가), 문체(「~한다」), 숫자 복사, 기록의 머리 블록, 문서 지도와 루트 README 필수 절. 그리고 백틱 안의 repo 경로(`:줄` 꼬리는 떼고 본다), 셸 코드 블록과 백틱 안 명령의 경로 인자, 마크다운 링크, `corepack pnpm <script>`와 백틱 안 `<prefix>:<name>` 꼴의 package script, `FE-GATE-0NN` ID가 실제로 있는가. 설명·수치가 코드와 맞는지는 보지 않는다.
|
||||
- **예외:** git이 무시하는 생성 산출물, 복사한 프로젝트가 지운 작업 이력(루트 `README.md`의 지워도 되는 파일 표)은 없어도 된다.
|
||||
- **짝 백엔드 경로:** `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리에서 찾는다. 옆 checkout이 없거나 그 커밋이 없으면 실패가 아니라 "확인 못 함"으로 남긴다.
|
||||
|
||||
@@ -21,7 +21,7 @@ src/ 최상위 폴더 ── 역할: docs/architecture/layers.md 표
|
||||
| 규칙 예외의 이유·담당·재검토 조건 | 그 규칙의 `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/architecture/contract-ownership.md` 「판단 규칙」 | 사람이 본다 |
|
||||
| 기능 폴더의 모양 | `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`) | 사람이 본다 |
|
||||
@@ -84,7 +84,7 @@ src/ 최상위 폴더 ── 역할: docs/architecture/layers.md 표
|
||||
|
||||
- **repo 안:** 스키마 메타, 레지스트리 행, 허용 키 목록, 빌드 입력 목록, 저장 키를 원본(zod 스키마, descriptor, registry)에서 뽑는다. 손으로 다시 적어야 하면 원본과 대조하는 테스트를 같이 둔다. 두 검사기가 같은 산출물을 다른 키 목록으로 읽어 merge 게이트가 항상 실패한 일이 있다(결함 패턴 S1).
|
||||
- **이미 갈라진 복사본은 하나로 합친다.** 갈라진 recipe port는 지우고 `src` port를 다시 내보낸다.
|
||||
- **두 템플릿 사이:** 짝 백엔드의 프로토콜·오류 code·응답 모양·생성기 규칙을 옮길 때는 백엔드 문서만 보지 않고 **코드까지 따라간다**(백엔드 생성기, 프론트 폼까지). 판정 표를 백엔드 계약 문서만으로 정해 High를 만든 일이 있다. 옮긴 사실은 기준 커밋(`config/contracts/backend-contract-pin.json`)과 대조 테스트로 묶는다. pin과 drift 검사는 아직 계약 문서 글자만 비교하고, 답 표 JSON과 생성기 사실은 대조 밖이다(결함 패턴 S2).
|
||||
- **두 템플릿 사이:** 짝 백엔드의 프로토콜·오류 code·응답 모양·생성기 규칙을 옮길 때는 백엔드 문서만 보지 않고 **코드까지 따라간다**(백엔드 생성기, 프론트 폼까지). 판정 표를 백엔드 계약 문서만으로 정해 High를 만든 일이 있다. 옮긴 사실은 기준 커밋(`config/contracts/backend-contract-pin.json`)과 대조 테스트로 묶는다. drift 검사(`check:backend-contract-drift`)는 계약 문서 글자, 답 표 JSON(pin 사본과), 생성기 원본 파일이 pin 뒤에 바뀌었는지를 본다. 옮긴 사실의 내용 자체는 대조하지 않는다(결함 패턴 S2).
|
||||
- 짝 백엔드 repo는 읽기만 한다. 백엔드가 바꿔야 할 것은 "백엔드에 넘길 것"으로 적는다.
|
||||
|
||||
## 9. 코드 기준 — 지우거나 바꿀 때
|
||||
|
||||
Reference in New Issue
Block a user