From e9d9c3694f59b453bedaaa077913c8f90dbb1adb Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:33:03 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EB=A6=AC=EB=B7=B0=20=EC=A0=88=EC=B0=A8?= =?UTF-8?q?=EA=B0=80=20merge=20=EB=8B=A8=EA=B3=84=20=EA=B2=8C=EC=9D=B4?= =?UTF-8?q?=ED=8A=B8=20=EC=A0=84=EB=B6=80=EB=A5=BC=20ci:gate=EB=A1=9C=20?= =?UTF-8?q?=EB=8F=8C=EB=A6=B0=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: CLAUDE.md 전체 리뷰 절차 2단계가 돌릴 명령 11개를 손으로 적는다. 이 목록은 merge 단계 명령 87개 중 10개만 돌리고, merge 게이트 14개 중 7개(001, 008, 009, 011, 012, 013, 020)는 전혀 돌지 않는다. 명령을 직접 부르면 ci:gate가 하는 로그·증거 검사, 음성 fixture의 기대 실패, workflow env도 빠진다. 2026-11-03 리뷰가 실제 CI에서 항상 실패하던 merge 게이트 둘(1103/11-06, 12-09)을 놓친 경로다. 고른 방법: 2단계를 "config/ci/gates.json의 merge 단계 gateIds 전부를 workflow env로 ci:gate 하나씩, verify:documentation은 따로"로 바꾸고 목록을 손으로 적지 않는다. 자세한 방법은 개선 매뉴얼 07장 3절을 가리킨다. 매뉴얼 01·07장과 부록 P-01에서 옛 목록을 전제로 쓴 문장을 같이 고친다. 줄 수는 그대로라 매뉴얼의 CLAUDE.md 줄 참조는 맞다. 버린 대안: 목록에 빠진 명령을 더 적기(다음에 게이트가 바뀌면 다시 갈라진다). merge 단계를 읽는 명령(ci:gate:stage merge)은 이 작업 범위 밖이라 더하지 않았다. 위험·한계: 리뷰 시작 비용이 커진다(FE-GATE-020만 약 20분). 실행 위치와 잠금은 매뉴얼 07장 7절을 따른다. 추적하지 않는 AGENTS.md는 이 변경을 받지 않는다. 검증: 로컬 정적 대조(매뉴얼의 경로·script·FE-GATE ID 문제 0건). desktop의 verify:documentation과 문서 unit 테스트는 이 커밋을 보내 돌린다. Refs: 1105/12-03 --- CLAUDE.md | 2 +- docs/improvement/01-procedures.md | 7 ++++--- docs/improvement/07-verification-gates.md | 4 ++-- docs/improvement/appendix-defect-patterns.md | 2 +- 4 files changed, 8 insertions(+), 7 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 883cdd57..79ebac65 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,7 +24,7 @@ ### 전체 리뷰 절차 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`. +2. 게이트를 직접 실행하고 결과를 기록한다. `config/ci/gates.json`의 merge 단계 `gateIds` 전부(지금 14개)를 workflow와 같은 env(`CI=true`, `VITE_COMMIT_SHA`, `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE`)로 `corepack pnpm ci:gate -- FE-GATE-0NN` 하나씩 돌린다. documentation 단계의 `verify:documentation`(FE-GATE-017)은 따로 돌린다. 명령 목록을 여기 손으로 적지 않는다(방법은 `docs/improvement/07-verification-gates.md` 3절). 3. 영역별로 서브에이전트를 병렬로 띄운다. 영역 분할은 가장 최근 `docs/reviews/*-maturity-review/README.md`의 영역 표를 재사용한다. 4. 각 에이전트는 `docs/reviews/-maturity-review/NN-<영역>.md`에 결과를 쓴다. 5. 오케스트레이터는 High 이상 발견을 코드에서 직접 재확인한 뒤 같은 폴더의 `README.md`에 범위(36.1), 28개 관점 판정표(36.2), 최종 요약(36.5), 발견 색인을 쓴다. diff --git a/docs/improvement/01-procedures.md b/docs/improvement/01-procedures.md index 355f5234..e9fa8e3b 100644 --- a/docs/improvement/01-procedures.md +++ b/docs/improvement/01-procedures.md @@ -67,9 +67,10 @@ 2. **전제를 채운다.** 전체 리뷰면 가이드 0.1절 전제 표를 채운다. 이 repo의 고정 전제는 `CLAUDE.md` 「이 repo의 리뷰 전제」 네 줄이다. 템플릿에는 요청량·데이터량 목표가 없으므로 그 칸은 "기능 수 증가 축과 lab·번들 예산으로 판정"처럼 적는다(1105 README 0절). -3. **게이트를 한 번 돌린다.** `CLAUDE.md` 2단계의 명령 목록에 더해 `config/ci/gates.json`의 merge 단계 `gateIds` - 14개를 workflow env로 돌린다(07장 3절). `CLAUDE.md` 목록만 돌리면 merge 게이트 일부가 빠진다. 그렇게 해서 실제 - 러너에서 항상 실패하는 게이트 두 개를 놓친 적이 있다(1103 README 10.5절 마지막 행). +3. **게이트를 한 번 돌린다.** `CLAUDE.md` 2단계대로 `config/ci/gates.json`의 merge 단계 `gateIds` 14개를 workflow + env로 `ci:gate`를 통해 돌리고, `verify:documentation`을 따로 돌린다(07장 3절). 예전에는 2단계가 명령 11개를 손으로 + 적었고, 그 목록만 돌려 실제 러너에서 항상 실패하는 게이트 두 개를 놓친 적이 있다(1103 README 10.5절 마지막 행, + 1105/12-03). 4. **결과를 함께 읽는다.** 게이트 출력과 `artifacts/`·`dist/`·`test-results/`를 읽기 전용 사본으로 떠 두고, 모든 리뷰어가 그 사본을 읽는다. 리뷰어마다 따로 돌리지 않는다(09장 4절). 5. **영역을 나눈다.** 가장 최근 리뷰 README의 영역 표를 다시 쓴다. 지금은 16개 영역이다(1103 README 10.2절, diff --git a/docs/improvement/07-verification-gates.md b/docs/improvement/07-verification-gates.md index 0e2ed20a..f5243951 100644 --- a/docs/improvement/07-verification-gates.md +++ b/docs/improvement/07-verification-gates.md @@ -10,7 +10,7 @@ 커밋 전 빠른 게이트 8개 (2절, SPEC.md 31줄) 레인 끝·통합 + 5개 (2절, SPEC.md 32줄) merge 판정 ci:gate로 merge 단계 14개, workflow env (3절) -리뷰 시작 CLAUDE.md 목록 11개 + merge 단계 14개 (3절) +리뷰 시작 merge 단계 14개 + verify:documentation (3절, CLAUDE.md 리뷰 절차 2단계) ``` 게이트 ID·단계·명령의 정본은 `config/ci/gates.json`이다. 이 장은 그 목록을 다시 적지 않는다. @@ -34,7 +34,7 @@ merge 판정 ci:gate로 merge 단계 14개, workflow env (3절) | 레인 끝·통합 | 위에 더해 `check:ci`, `check:adapter-inventory`, `verify:documentation`, `test:sample-removal`, `build` | `SPEC.md` 32줄 | | 브랜치를 합칠 때마다 | 커밋 전 8개. 합친 뒤에만 생긴 실패는 기록한다 | 1103 README 14.1·14.3절 | | merge 가능이라고 말하기 전 | merge 단계 14개(3절) | 사용자 지시 | -| 리뷰 시작 | `CLAUDE.md` 27줄의 11개와 merge 단계 14개 | `CLAUDE.md` 27줄, 1103 README 10.5절 | +| 리뷰 시작 | merge 단계 14개(3절)와 `verify:documentation`(FE-GATE-017) | `CLAUDE.md` 27줄. 손으로 적은 명령 목록만 돌리다 merge 게이트 둘을 놓친 일(1103 README 10.5절)로 목록을 merge 단계로 바꿨다(1105/12-03) | | 라우트 로딩·청크·초기 화면을 바꿀 때 | merge 단계에 더해 `check:bundle`(FE-GATE-012)과 lab 게이트 `test:performance`(FE-GATE-026) | 06장 2절 | | 공급망·release 경로를 바꿀 때 | release 단계 게이트(`config/ci/gates.json`의 `stages` 중 `release`) | 4절 | diff --git a/docs/improvement/appendix-defect-patterns.md b/docs/improvement/appendix-defect-patterns.md index 0c559c95..c273ac3c 100644 --- a/docs/improvement/appendix-defect-patterns.md +++ b/docs/improvement/appendix-defect-patterns.md @@ -21,7 +21,7 @@ Critical은 다섯 라운드 모두 0건이다. 패턴에 들지 않은 High는 | ID | 패턴 | 모양 | 대표 발견 | 막는 기준 | 관점 | | --- | --- | --- | --- | --- | --- | -| P-01 | 돌리는 게이트 목록이 stage 전체가 아니거나, 게이트가 늦은 단계에서만 돈다 | 리뷰·드릴이 손으로 적은 명령 목록을 돌려 merge 게이트 일부가 빠진다. release 단계 게이트를 아무도 안 돌린다. CI가 꺼져 있다 | 0925/12-01, 0925/12-02, 1101/15-01, 1103/12-02, 1105/12-03 | 07장 2·3절. `CLAUDE.md` 27줄의 리뷰 목록이 merge 단계와 다르다는 발견(1105/12-03)은 미조치 | 21, 10, 26 | +| P-01 | 돌리는 게이트 목록이 stage 전체가 아니거나, 게이트가 늦은 단계에서만 돈다 | 리뷰·드릴이 손으로 적은 명령 목록을 돌려 merge 게이트 일부가 빠진다. release 단계 게이트를 아무도 안 돌린다. CI가 꺼져 있다 | 0925/12-01, 0925/12-02, 1101/15-01, 1103/12-02, 1105/12-03 | 07장 2·3절. 리뷰 절차의 게이트 목록은 merge 단계 `gateIds` 전부를 `ci:gate`로 돌리는 것으로 바꿨다(`CLAUDE.md` 27줄, 1105/12-03) | 21, 10, 26 | | P-02 | 게이트·수정 확인이 템플릿 원래 상태와 작은 입력만 본다 | 기능 0개, 제품 파일이 빈 상태, 객체 0~1개에서만 맞다. 기능을 더하거나 제품 파일을 채운 다운스트림에서 깨진다 | 0925/09-01, 1103/12-01, 1103/16-09, 1105/09-01, 1105/16-03 | 01장 2절 5단계, 05장 3.3절 | 10, 21, 25, 3, 20 | | P-05 | workflow env에서만 나는 게이트 실패 | `CI=true`·빌드 식별값이 테스트 기대값·dev server·테스트 안 빌드로 새어 실제 CI에서만 실패 | 1103/11-06, 1103/11-07, 1103/11-08 | 07장 3·4절, 04장 6절 | 21, 10, 18, 19 | | P-06 | 고정 출력 경로·포트·추적 파일에 쓴다 | `dist/`, `artifacts/`, 고정 포트, 커밋된 파일에 써서 한 checkout의 두 실행이 부딪히고 추적 파일이 바뀐다 | 1105/12-04, 1103/12-08, 1105/16-01, 0929/14-01, 0925/00-01 | 실행 격리는 결정 대기(08장 5.1절 D6). 그동안 09장 4절 방식으로 하나씩 돈다. 실행 뒤 `git status`가 비어야 한다 | 20, 25, 12, 10 |