From ed6fad9cb9f7ccc5c3446877fa929b0b34807d02 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:15:22 +0900 Subject: [PATCH 01/10] =?UTF-8?q?docs(improvement):=20=EA=B0=9C=EC=84=A0?= =?UTF-8?q?=20=EC=9E=91=EC=97=85=20=EB=A7=A4=EB=89=B4=EC=96=BC=EC=9D=98=20?= =?UTF-8?q?=EC=A0=95=EB=B3=B8=20=ED=91=9C=EC=99=80=20=EC=9D=BD=EB=8A=94=20?= =?UTF-8?q?=EC=88=9C=EC=84=9C=EB=A5=BC=20=EB=91=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 리뷰·수정·리팩터링·최적화를 할 때 기준으로 삼을 이 repo 전용 문서가 없다. 기준이 CLAUDE.md, 리뷰 가이드, SPEC.md, gates.json, 리뷰 README 곳곳과 세션 기록에 흩어져 있어, 작업마다 다시 찾고 이미 정한 것을 다시 묻는다. 고른 방법: docs/improvement/README.md에 목적, 적용 범위, 정본 표 (무엇의 정본이 어디인가), 읽는 순서, 근거 표기, 결정 기록 M-1~M-10을 둔다. 규칙을 다시 쓰지 않고 정본을 가리킨다. 장 번호·파일 이름은 짝 백엔드 매뉴얼과 같게 맞췄다. 버린 대안: docs/reviews/ 안에 두기 (복사본이 지우는 작업 이력과 섞인다), docs/manual/ 뒤에 장 추가 (독자가 다르다). 위험·한계: 정본과 설명이 맞는지는 검사하지 않는다. 4라운드 리뷰는 아직 main에 없어 그 경로를 백틱 없이 적었다. 합쳐지면 바꿔야 한다. 검증: 로컬 정적 대조로 백틱 경로·script·FE-GATE ID가 있음을 확인했다. verify:documentation과 문서 unit 테스트는 연결 커밋 뒤 desktop에서 돌린다. --- docs/improvement/README.md | 152 +++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 docs/improvement/README.md diff --git a/docs/improvement/README.md b/docs/improvement/README.md new file mode 100644 index 00000000..3b3649c8 --- /dev/null +++ b/docs/improvement/README.md @@ -0,0 +1,152 @@ +# 개선 작업 매뉴얼 — 이 repo를 리뷰·수정·리팩터링·최적화할 때의 기준 + +## 핵심 + +이 매뉴얼은 **이미 있는 코드를 평가하거나 고치는 사람**이 읽는다. 사람과 AI 에이전트가 같은 기준을 쓴다. +새 기능을 만드는 순서는 [`docs/manual/`](../manual/README.md)이 맡는다. 두 매뉴얼은 독자가 다르다. + +개선 작업 하나는 다음 흐름을 탄다. 괄호 안 숫자는 이 매뉴얼의 장이다. + +```text +리뷰(02) ──> 발견 색인 ──> 수정 묶음(01·03·04·05·06) ──> 검증(07) + ^ | + | v + └── 다음 라운드 리뷰: 지난 발견 재판정 + 새 발견(02) <── 멈출 조건을 채웠나?(09) + | 새 High 0 · 새 P1 0 · merge 게이트 14개 통과 + v + 그 라운드의 Medium·Low를 고친다 ──> 결정·결과 기록(08) ──> 보고 +``` + +- **리뷰**는 결함을 찾고 적는다. 코드를 고치지 않는다(`CLAUDE.md` 「리뷰 기준」). +- **수정 묶음**은 결함을 테스트로 먼저 재현하고(RED) 고친다(GREEN). +- **다음 라운드 리뷰**는 지난 발견이 정말 고쳐졌는지 다시 판정하고, 수정이 만든 새 결함을 찾는다. + 4라운드 리뷰의 새 발견 48건 중 상당수가 지난 수정에서 나왔다(1105 README 4절 끝 목록). +- 멈추는 조건과 그 뒤에 할 일은 09장 5절이 정한다. + +## 적용 범위 + +| 작업 | 이 매뉴얼 | 다른 문서 | +| --- | --- | --- | +| 리뷰(전체·영역·PR·diff) | 01장 1절, 02장 | `CLAUDE.md` 「리뷰 기준」, 리뷰 가이드(아래) | +| 결함 수정 | 01장 2절, 04·05장 | `SPEC.md` 「공통 완료 기준」 | +| 리팩터링(동작을 바꾸지 않는 구조 변경) | 01장 3절, 04장 | 리뷰 가이드 39절 | +| 성능 최적화 | 01장 4절, 06장 | `docs/operations/performance-evidence.md` | +| 폴더·모듈 구조 변경 | 01장 5절, 03장 | `docs/architecture/layers.md`, `.dependency-cruiser.json` | +| 테스트 구조 개선 | 01장 6절, 05장 | `docs/testing/taxonomy.md` | +| 새 기능 추가 | 아님 | [`docs/manual/`](../manual/README.md) | +| 운영 장애 대응 | 아님 | `docs/runbooks/`, `docs/operations/` | + +## 정본 표 + +이 매뉴얼은 규칙을 다시 쓰지 않고 **정본을 가리킨다**. 매뉴얼과 정본이 다르면 정본이 맞고, 매뉴얼을 고친다. +맨 아래 「이 매뉴얼이 정본」 행만 이 매뉴얼이 처음이자 유일한 기록이다. + +| 무엇 | 정본 | 이 매뉴얼에서 | +| --- | --- | --- | +| 리뷰 기준, 이 repo의 리뷰 전제 4개, 전체 리뷰 절차 5단계 | 루트 `CLAUDE.md` 7~30줄. 루트 `AGENTS.md`는 추적하지 않는 사본이다(08장 결정 M-10) | 01장 1절, 02장이 가리킴 | +| 28개 관점, 판정 체계(성격·심각도·우선순위·통제·증거), 발견·요약·판정표 양식 | `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` 0~36절, 실행 순서는 `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md` | 02장이 이 repo에 맞춤 | +| 수정 라운드의 공통 완료 기준 9개 | `SPEC.md` 27~37줄 | 01장 2절, 07장이 가리킴 | +| 최상위 `src/` 폴더의 역할, 계층 규칙, adapter kernel | `docs/architecture/layers.md` | 03장이 가리킴 | +| import 규칙과 kernel 예외 | `.dependency-cruiser.json`(`check:architecture`가 읽는다) | 03장이 가리킴 | +| adapter 목록 | `docs/reviews/adapters/INVENTORY.md`(`check:adapter-inventory`, FE-GATE-010) | 03장이 가리킴 | +| 게이트 ID·단계·명령 | `config/ci/gates.json`, 설명은 `docs/operations/ci-quality-gates.md` | 07장이 언제·어디서 돌릴지 정함 | +| 테스트 층과 테스트 위치 | `docs/testing/taxonomy.md`, 넓은 설계는 `docs/testing/frontend-platform-testing-strategy.md` | 05장이 가리킴 | +| 성능 예산과 기준선 | `config/performance/budgets.json`, `docs/operations/performance-evidence.md` | 06장이 측정 조건을 더함 | +| 규모 설계(예산·실행·텔레메트리) | `docs/architecture/scale-architecture.md` | 04·06장이 `scale-architecture.md §N`으로 가리킴 | +| 새 기능 만드는 순서 | `docs/manual/` | 가리킴 | +| 문서 색인과 문서 검사 범위 | `docs/README.md`, 검사 규칙은 `scripts/verify-documentation-readiness.ts` | 07장이 가리킴 | +| 커밋·PR 형식 | `design-docs/conventions/commit-and-pr.md`(repo 밖, 이 repo 옆 `design-docs` repo) | 08장이 이 repo에서 쓰는 꼬리말을 덧붙임 | +| 소유자 결정 원문 | 각 리뷰 README의 「결정이 필요한 것」「조치」 절, `SPEC.md` 「결정」, `docs/architecture/decisions/` | 08장은 색인 | +| **이 매뉴얼이 정본** | 작업 종류별 절차(01), 이 repo의 리뷰 점검 항목·결함 판정 예·리뷰 문서 형식(02), 반복 결함 패턴과 막는 기준(04·05·부록), 성능 측정 조건(06), 무거운 실행 위치와 merge 판정 방법(07), 결정 기록법(08), 세션 분업·리뷰 중 실행 방식·반복 종료 조건(09) | | + +## 읽는 순서 + +처음이면 이 README → 01 → 09 → 07을 읽는다. 그다음은 맡은 작업의 장만 읽는다. + +| 장 | 파일 | 언제 읽나 | +| --- | --- | --- | +| 01 작업 종류별 절차 | [01-procedures.md](01-procedures.md) | 어떤 작업이든 시작할 때. 시작 조건·단계·산출물·완료 기준 | +| 02 리뷰 기준 | [02-review-criteria.md](02-review-criteria.md) | 리뷰하거나 리뷰 결과를 읽을 때 | +| 03 폴더·모듈 구조 기준 | [03-folder-module-structure.md](03-folder-module-structure.md) | `src/` 폴더·adapter 그룹·기능 폴더·문서 위치를 바꿀 때 | +| 04 코드 구조 기준 | [04-code-structure.md](04-code-structure.md) | 결함을 고치거나 리팩터링할 때 | +| 05 테스트 구조 기준 | [05-test-structure.md](05-test-structure.md) | 테스트를 쓰거나 옮기거나, 가끔 떨어지는 테스트를 조사할 때 | +| 06 성능·최적화 기준 | [06-performance.md](06-performance.md) | 성능을 재거나 고칠 때 | +| 07 검증과 게이트 | [07-verification-gates.md](07-verification-gates.md) | 무엇을 언제 어디서 돌릴지, merge 가능을 어떻게 판정할지 정할 때 | +| 08 결정과 기록 | [08-decisions-records.md](08-decisions-records.md) | 결정이 필요해 보일 때, 커밋·PR을 쓸 때 | +| 09 작업 진행 방식 | [09-working-method.md](09-working-method.md) | 여러 세션으로 나눠 일할 때, 반복을 멈출지 정할 때 | +| 부록 결함 패턴 카탈로그 | [appendix-defect-patterns.md](appendix-defect-patterns.md) | 리뷰 전에 훑어볼 목록이 필요할 때 | + +## 백엔드 매뉴얼과 같은 뼈대 + +짝 백엔드 템플릿(`clean-architecture-backend-template`)도 같은 장 번호와 같은 파일 이름으로 개선 매뉴얼을 둔다. +장 번호가 같으면 "두 repo의 05장"처럼 같은 주제를 바로 비교할 수 있다. 이 repo는 장을 합치거나 더하지 않았다. +장 이름과 파일 이름은 2026-11-05 백엔드 매뉴얼 초안의 「읽는 순서」 표에 맞췄다(결정 M-2). + +백엔드와 내용이 다른 곳은 정본이 달라서다. 예: 백엔드의 규칙 정본은 `AGENTS.md`와 registry지만, 이 repo의 정본은 +`CLAUDE.md`·`SPEC.md`·`config/ci/gates.json`·`.dependency-cruiser.json`이다. + +## 리뷰 가이드와의 관계 + +리뷰 기준은 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`(이하 「가이드」)다. Backend·Frontend·Platform 공용 +일반론이고, 예시는 이 repo의 코드가 아니다. + +- 이 매뉴얼은 가이드를 **복사하지 않는다**. 「가이드 35.5절」처럼 절 번호로 가리킨다. +- 02장은 가이드의 28개 관점과 판정 체계를 **이 repo의 경로·명령·지난 결함**으로 바꿔 적는다. +- 가이드는 복사한 프로젝트가 지워도 되는 `docs/reviews/` 안에 있다(루트 `README.md` 「Files you can delete after + copying」). 가이드를 지운 프로젝트도 02장만으로 판정할 수 있게 썼다. + +## 근거 표기 + +- 경로는 repo 루트 기준이다. 코드 근거는 `file:line`, 문서 근거는 「문서 N절」로 적는다. +- 리뷰 ID는 가이드 36.3절의 라운드 밖 표기 `MMDD/NN-MM`을 쓴다. 이 매뉴얼에서 쓰는 줄임말: + + | 줄임말 | 뜻 | + | --- | --- | + | `0925/03-01` | `docs/reviews/2026-09-25-maturity-review/`의 발견 03-01 | + | `0929/03-03` | `docs/reviews/2026-09-29-maturity-review/`의 발견 | + | `1101/12-04` | `docs/reviews/2026-11-01-maturity-review/`의 발견. 「1101 README」는 그 폴더의 `README.md` | + | `1103/11-07` | `docs/reviews/2026-11-03-maturity-review/`의 발견 | + | `1105/12-04` | 4라운드 리뷰(2026-11-05)의 발견. 이 매뉴얼을 쓸 때 main에 없고 브랜치 docs/maturity-review-2026-11-05의 커밋 `e85c836`에만 있다. 합쳐지면 docs/reviews/2026-11-05-maturity-review/에 놓인다 | + | 「가이드 N절」 | `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`의 N절 | + | 「커밋 규칙 N절」 | repo 밖 `design-docs/conventions/commit-and-pr.md`의 N절 | + +- 백틱 안의 repo 경로는 `verify:documentation`이 있는지 검사한다(07장 6절). 아직 main에 없는 4라운드 리뷰의 경로만 + 백틱 없이 쓴다. 참조 기능과 함께 지워지는 경로는 이름을 쓰지 않고 그 경로를 소유한 문서의 절을 가리킨다. +- `file:line`은 낡는다(부록 P-43). 이 매뉴얼은 줄 번호를 잘 바뀌지 않는 정본(`CLAUDE.md`, `SPEC.md`, 가이드)과 리뷰 + 기록(고치지 않는 문서)에 주로 쓴다. 자주 바뀌는 코드 파일은 파일과 심볼 이름으로 가리킨다. +- **리뷰 ID는 출처 표시다.** 규칙 문장은 리뷰 문서 없이도 뜻이 통하게 썼다. 복사한 프로젝트가 `docs/reviews/`를 + 지워도 기준은 남는다. +- 이 repo에서 근거를 찾지 못한 기준은 **[제안]**으로 표시했다. 제안은 소유자가 받기 전까지 규칙이 아니다. + +## 결정 기록 + +이 매뉴얼을 만들며 정한 것이다. 소유자가 뒤집을 수 있다. 소유자 결정 전체의 색인은 08장이다. + +| # | 결정 | 이유 | 버린 대안 | +| --- | --- | --- | --- | +| M-1 | 위치는 `docs/improvement/` | 독자가 `docs/manual/`(새 기능 작성자)과 다르다. `docs/reviews/`는 지워도 되는 작업 이력이라, 기준서를 섞으면 어느 문서가 현재 기준인지 흐려지고 복사본에서 함께 지워진다 | `docs/reviews/` 안에 두기, `docs/manual/` 뒤에 장 추가 | +| M-2 | 장 번호·이름·파일 이름은 백엔드 매뉴얼과 같다 | 두 repo의 같은 장을 바로 비교하게 한다. 백엔드 총괄 세션에 2026-11-05 알렸다 | 07·09 합치기, 프론트만의 장 추가 | +| M-3 | `docs/README.md` §1에서 이 폴더를 링크한다 | `verify:documentation`이 이 폴더 `.md`의 repo 경로·package script·FE-GATE ID가 있는지 검사하게 된다. 같은 검사가 FE-GATE-005·020 안에서도 돌므로 merge 때마다 확인된다. 정본을 가리키는 문서라 가리킨 곳이 없어지면 바로 알아야 한다. 대가: main에 없는 경로와 샘플과 함께 지워지는 경로는 백틱으로 쓸 수 없다 | §3 작업 이력에 두기(검사 밖), 검사 코드에 목록 추가(이 작업은 문서만 바꾼다) | +| M-4 | 복사 뒤 지워도 되는 문서 목록에 넣지 않는다 | 복사한 프로젝트도 리뷰·수정·최적화를 한다. 소유자 환경에 묶인 규칙은 07장 7절과 09장 7절 「소유자 환경」에만 두어, 복사본은 그 두 절만 바꾸면 된다 | 루트 `README.md` 삭제 목록에 추가 | +| M-5 | 심각도 체계는 가이드 35.2절(Critical~Low)과 35.3절(P0~P3) 하나만 쓴다 | 이 repo의 다섯 라운드가 모두 이 체계로 적혔다. 백엔드는 확인 리뷰에 Critical/Important/Minor를 더 쓰지만, 이 repo에는 그 이력이 없다. 소유자 지시의 "Minor"는 Low로 읽는다(09장 5절) | 백엔드처럼 두 체계 | +| M-6 | 08장의 결정 표는 색인이다. 한 줄 요약과 출처만 둔다 | 결정 원문을 옮겨 쓰면 갈라진 복사본이 된다(부록 P-14) | 결정 원문 이동 | +| M-7 | 반복 종료 조건은 소유자 문장 그대로 쓴다(09장 5.2절) | 2026-11-04 사용자 결정의 문장이다. 백엔드는 "발견 0까지 확인 리뷰"를 쓴다. 2026-11-05 소유자 결정 「각자 유지」가 repo마다 자기 기준을 따르고 하나로 맞추지 않게 정했다 | 백엔드 문장으로 통일 | +| M-8 | repo 밖 문서(커밋 규칙, 백엔드 매뉴얼)는 링크 대신 평문이나 코드 표기 | `verify:documentation`은 repo 밖 링크를 옆 checkout에서 찾는다. 옆 checkout이 없거나 다른 커밋이면 결과가 기계마다 달라진다(1105/12-02) | 상대 링크 | +| M-9 | "Low도 고친다", "총괄은 하위 세션에 맡긴다", "리뷰 중 실행은 한 번 돌리고 함께 읽는다"는 2026-11-03~05 사용자 지시다. 09장이 이 규칙들의 repo 안 정본이 된다 | 규칙이 세션 기록과 리뷰 README 곳곳에만 있었다 | | +| M-10 | 루트 `AGENTS.md`는 건드리지 않는다 | main checkout에 추적하지 않는 파일로 있고(`git ls-files AGENTS.md`가 비어 있다) 내용은 `CLAUDE.md`와 같다. 추적 대상이 아니라 이 작업의 범위 밖이다 | `AGENTS.md`도 고치기 | + +## 이 매뉴얼을 고칠 때 + +- 정본이 바뀌면 이 매뉴얼의 해당 문장을 고친다. 설명이 정본과 맞는지는 검사하지 않는다. `verify:documentation`은 + 경로·script·게이트 ID가 있는지만 본다(`docs/README.md` §1 끝 문단). +- 리뷰 라운드에서 새 반복 패턴이 나오면 부록에 행을 더하고, 막는 기준이 생기면 04·05·07장에 넣는다. +- 새 소유자 결정이 생기면 08장 색인에 한 줄을 더한다. +- 4라운드 리뷰가 main에 합쳐지면 위 줄임말 표의 `1105` 행과 08장 출처를 실제 경로로 바꾼다. + +## 지금 이해하면 되는 것 + +- 새 기능은 `docs/manual/`, 이미 있는 코드를 평가·수정하는 일은 이 매뉴얼. +- 규칙의 정본은 `CLAUDE.md`·가이드·`SPEC.md`·`config/ci/gates.json`·`.dependency-cruiser.json`이다. 이 매뉴얼은 + 가리키고, 절차·점검 항목·패턴·실행 방식·기록법만 소유한다. +- 리뷰 → 수정 → 다음 라운드 리뷰를, 새 High 0·새 P1 0·merge 게이트 14개 통과까지 돈다. 그 라운드의 Medium·Low를 + 고치고 멈춘다. -- 2.54.0 From 44961d7561b7d8b4c869be7f6f634a8b00b843ba Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:15:22 +0900 Subject: [PATCH 02/10] =?UTF-8?q?docs(improvement):=20=EC=9E=91=EC=97=85?= =?UTF-8?q?=20=EC=A2=85=EB=A5=98=EB=B3=84=20=EC=A0=88=EC=B0=A8=EC=99=80=20?= =?UTF-8?q?=EC=84=B8=EC=85=98=20=EB=B6=84=EC=97=85=C2=B7=EB=B0=98=EB=B3=B5?= =?UTF-8?q?=20=EC=A2=85=EB=A3=8C=20=EC=A1=B0=EA=B1=B4=EC=9D=84=20=EC=A0=81?= =?UTF-8?q?=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 리뷰·결함 수정·리팩터링·성능·구조·테스트 개선마다 시작 조건과 완료 기준이 어디에도 한곳에 없다. 총괄 세션 운영, 리뷰 중 실행 방식, 수정→리뷰 반복의 멈춤 조건은 사용자 지시와 리뷰 README에만 있다. 고른 방법: 01장에 여섯 작업의 시작 조건·단계·산출물·완료 기준을, 09장에 역할, brief, 리뷰 라운드 운영, "게이트는 한 번 돌리고 함께 읽는다", 멈춤 조건(새 High 0·새 P1 0·merge 14개 통과 뒤 그 라운드 Medium·Low 수정), 수정 라운드 운영, 총괄이 자주 한 실수를 적는다. 소유자 환경에 묶인 것은 09장 7절에만 둔다. 위험·한계: 스킬 기록 규칙과 대기 종료 조건 일반화는 [제안]으로 표시했다. 멈춤 기준의 3라운드 상한은 그동안 repo 밖 메모에만 있었다. 검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤. --- docs/improvement/01-procedures.md | 251 ++++++++++++++++++++++++++ docs/improvement/09-working-method.md | 153 ++++++++++++++++ 2 files changed, 404 insertions(+) create mode 100644 docs/improvement/01-procedures.md create mode 100644 docs/improvement/09-working-method.md diff --git a/docs/improvement/01-procedures.md b/docs/improvement/01-procedures.md new file mode 100644 index 00000000..355f5234 --- /dev/null +++ b/docs/improvement/01-procedures.md @@ -0,0 +1,251 @@ +# 01. 작업 종류별 절차 + +## 핵심 + +개선 작업은 여섯 종류다. 리뷰, 결함 수정, 리팩터링, 성능 최적화, 구조 변경, 테스트 구조 개선. +종류마다 **시작 조건 → 단계 → 산출물 → 완료 기준**을 같은 틀로 적는다. 시작 조건이 안 맞으면 다른 종류의 작업이다. + +종류를 고르는 기준은 "동작이 바뀌는가"와 "무엇을 근거로 시작하는가"다. + +| 질문 | 답 | 작업 | +| --- | --- | --- | +| 아직 무엇이 틀렸는지 모른다 | 찾는다 | 리뷰 | +| 계약과 다른 동작이 확인됐다 | 동작을 계약에 맞춘다 | 결함 수정 | +| 동작은 맞는데 구조 비용이 크다 | 동작을 그대로 두고 모양을 바꾼다 | 리팩터링 | +| 숫자로 잰 비용이 크다 | 같은 동작을 더 싸게 | 성능 최적화 | +| 최상위 폴더·adapter 그룹·기능 폴더·import 규칙이 바뀐다 | 경계를 바꾼다 | 구조 변경 | +| 테스트가 주장을 증명하지 못하거나 가끔 떨어진다 | 테스트를 고친다 | 테스트 구조 개선 | + +## 0. 모든 작업의 공통 단계 + +1. **기준 커밋을 고정한다.** `git rev-parse HEAD`를 산출물 첫머리에 적는다. 리뷰 문서는 모두 기준 커밋으로 + 시작한다(`CLAUDE.md` 26줄, 1105 README 머리말). +2. **이전 기록을 읽는다.** 가장 최근 리뷰 README의 「결정이 필요한 것」「조치」「남은 문제」 절과 08장 색인을 읽는다. + 이미 정한 것을 다시 묻지 않는다(08장 3절). +3. **위험을 정한다.** 위험은 파일 수가 아니라 바뀌는 경계로 정한다. 사용자 데이터(결과 불명 쓰기, OPFS 개인 파일), + 공개 포트, merge 게이트, 짝 백엔드 계약을 건드리면 높다. 높으면 설계와 대안을 먼저 적는다(가이드 41절). +4. **스킬을 고른다.** 소유자 규칙이다: 리뷰·수정에 스킬을 쓴다(2026-11-03~05 사용자 지시, 08장 표 O-3). 아래 표에서 + 고른다. +5. **격리된 곳에서 일한다.** 자기 worktree와 브랜치를 쓴다. 리뷰어는 코드를 고치지 않는다. 의심 결함은 임시 + 테스트로 확인하고 그 코드는 리뷰 문서나 scratchpad에만 남긴다(`CLAUDE.md` 15줄). +6. **무거운 실행 위치를 지킨다.** 테스트·게이트·빌드는 노트북에서 돌리지 않는다(07장 7절 「소유자 환경」). +7. **보고 전에 검증한다.** 돌리지 못한 검증은 이유와 함께 "확인" 줄에 적는다. 돌린 것처럼 쓰지 않는다. + +### 스킬 고르기 + +스킬을 불렀다는 사실보다 **그 스킬의 기준으로 무엇을 봤는지**가 증거다. 리뷰어는 불러온 스킬과 적용한 기준을 리뷰 +문서 「범위」 절에 한 줄씩 적는다 **[제안]** — 지난 다섯 라운드의 리뷰 문서에는 스킬 기록이 없다. + +| 작업 | 절차 스킬 | 영역 스킬(바뀌는 경계에 맞춰) | +| --- | --- | --- | +| 리뷰 | `superpowers:requesting-code-review` | `clean-architecture`, `codebase-design`, `api-and-interface-design`, `security-and-hardening`, `performance-optimization`, `playwright-best-practices`, `ci-cd-and-automation`, `frontend-ui-engineering`, `documentation-and-adrs`, `doubt-driven-development` | +| 리뷰 결과를 받아 고칠 때 | `superpowers:receiving-code-review` | — | +| 결함 수정 | `superpowers:systematic-debugging` → `superpowers:test-driven-development` | 바뀌는 경계의 영역 스킬 | +| 리팩터링 | `refactor`, `codebase-design` | `clean-architecture`, `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` | +| 문서·결정 기록 | `documentation-and-adrs` | — | +| 완료 주장 전 | `superpowers:verification-before-completion` | — | + +기능 개발 단계별 스킬은 `docs/manual/01-add-a-feature.md`가 단계마다 「쓸 스킬」로 적는다. 이 표는 그 표기를 따른다. + +## 1. 리뷰 + +**시작 조건** + +- 대상이 정해졌다: 전체, 영역, PR, 또는 커밋 범위(`..`). +- 기준 커밋과 지난 라운드의 결정·남은 문제를 읽었다. + +**단계** + +전체 리뷰의 뼈대는 `CLAUDE.md` 「전체 리뷰 절차」 1~5단계다(26~30줄). 아래는 그 단계를 지난 라운드에서 겪은 대로 +구체화한 것이다. + +1. **범위를 고정한다.** 기준 커밋, 브랜치, 확인 시점, 노트북 worktree와 desktop checkout이 깨끗한지 적는다 + (1105 README 11절 표). +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절 마지막 행). +4. **결과를 함께 읽는다.** 게이트 출력과 `artifacts/`·`dist/`·`test-results/`를 읽기 전용 사본으로 떠 두고, 모든 + 리뷰어가 그 사본을 읽는다. 리뷰어마다 따로 돌리지 않는다(09장 4절). +5. **영역을 나눈다.** 가장 최근 리뷰 README의 영역 표를 다시 쓴다. 지금은 16개 영역이다(1103 README 10.2절, + 1105 README 11.2절). 영역마다 서브에이전트나 하위 세션 하나(09장). +6. **영역을 읽는다.** 영역 문서는 「지난 발견 재판정」부터 쓴다. 지난 라운드가 "고침"이라고 한 것도 코드로 다시 + 본다. 4라운드는 1103 조치의 "고침" 13건을 "일부"로 정정했다(1105 README 3.1절). +7. **더 필요한 실험은 목록으로 낸다.** 리뷰어가 직접 돌리지 않는다. 총괄이 모아 같은 명령은 한 번만, 실험마다 + 작업 폴더를 되돌리며 일괄로 돌린다(09장 4절). +8. **발견을 02장 형식으로 적는다.** 같은 결함을 두 영역이 적으면 색인에서 하나로 합치고 「합친 중복」 표에 + 남긴다(1105 README 11.3절). +9. **총괄이 다시 확인한다.** High 이상과 새 P1은 총괄이 코드를 직접 읽거나 실행해 확인하고, 재확인 칸에 그 사실을 + 적는다(`CLAUDE.md` 30줄, 1105 README 2.2절 「재확인」 칸). +10. **README를 쓴다.** 02장 6절 형식. 총괄 자신의 실수도 적는다(1103 README 10.5절, 1105 README 11.5절). + +PR·diff 리뷰는 3·4·5단계를 줄인다. 바뀐 파일의 영역만 읽고, 그 diff가 건드린 게이트만 돌린다. 판정 체계와 발견 +형식은 같다. + +**산출물** + +- 전체 리뷰: `docs/reviews/-maturity-review/README.md`와 영역 문서 `NN-<영역>.md`(`CLAUDE.md` 29줄). +- 리뷰 문서는 리뷰 시점 기록이다. 고친 뒤에도 영역 문서를 고치지 않는다. 처리 결과는 같은 README의 「조치」 절에 + 적는다(1103 README 14절). 틀린 문장이 남아도 리뷰 기록은 고치지 않고, 현재 문서(CHANGELOG 등)에서 바로잡는다 + (1103 README 14.7절 끝). + +**완료 기준** + +- 모든 발견이 02장 형식이고 성격·심각도·우선순위·통제·증거가 따로 적혀 있다. +- 지난 라운드 발견 전부의 지금 상태가 표 하나에 있다(1105 README 13절). +- 미검증 목록과 확인 방법이 있다. +- 결정이 필요한 항목마다 선택지와 결정할 사람이 있다(1105 README 7절). +- 리뷰 중 코드를 고치지 않았고, 끝에 desktop checkout의 `git status`가 비었다. + +## 2. 결함 수정 + +**시작 조건** + +- 리뷰 문서의 발견 ID가 있다. 발견 없이 고치면 그 고침이 무엇을 막는지 아무도 모른다. +- 그 발견의 「완료 기준」 칸을 읽었다. 완료 기준의 기준은 그 칸이다(`SPEC.md` 13줄). + +**단계** + +1. **재현 테스트를 먼저 쓴다(RED).** 동작을 바꾸는 수정은 재현 테스트가 먼저 실패하고, 고친 뒤 통과한다. 브라우저 + 없이 재현할 수 없으면 fake·fixture로 조건을 만든다(`SPEC.md` 29줄). +2. **검출력을 확인한다.** 테스트 검출력이 문제였던 발견(변이 생존)은 리뷰에 적힌 변이를 다시 넣어 새 테스트가 + 실패하는지 본다(`SPEC.md` 30줄). +3. **고친다(GREEN).** 공개 포트는 추가만 한다. 기존 시그니처를 깨야 하면 결정 표에 적는다(`SPEC.md` 35줄). 공용 + 로직은 `src/adapters/platform/` 또는 `src/contracts/`에 둔다. 새 파일 단위 예외를 만들지 않는다(`SPEC.md` 34줄). +4. **수정이 새로 가정하는 것을 적는다.** 커밋 본문 「위험·한계」에 쓴다. 4라운드 새 발견의 상당수가 지난 수정에서 + 나왔고, 수정마다 이 질문을 하는 단계가 없었다(1105 README 6절 원인 5). +5. **템플릿 원래 상태 밖에서도 확인한다.** 기능 하나를 더한 상태, 예제 기능을 지운 상태, 입력이 셋 이상인 상태로 + 한 번씩 돌린다. 템플릿 원래 상태나 작은 입력으로만 확인한 수정이 다시 결함이 됐다(1105 README 6절 원인 1, + 부록 P-02). +6. **커밋한다.** 논리적 변경 하나에 커밋 하나, 커밋 메시지에 발견 ID, 그 작업이 바꾼 파일만 스테이징한다(`SPEC.md` + 36줄, 08장 5절). +7. **빠른 게이트를 돌린다.** 작업마다 `SPEC.md` 31줄의 8개, 레인이 끝날 때와 통합 때는 32줄의 5개를 더 돌린다(07장 + 2절). +8. **adapter 파일을 더하거나 옮기면** `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다(`SPEC.md` 33줄). + +**산출물** + +- 커밋(`Refs:` 꼬리말에 발견 ID, 08장 5절). +- 리뷰 README의 「조치」 절: 방법, 결정, 통합에서 생긴 것, 발견별 상태, 검증, 남은 문제(1103 README 14.1~14.7절 + 구성). +- CHANGELOG 미출시 절의 행. + +**완료 기준** + +- 발견의 「완료 기준」 칸을 관찰했다. +- 가이드 35.6절의 다섯 연결이 있다: 원래 위험, 바꾼 코드, 그 위험을 잡는 검증, 검증한 버전·환경·결과, 남은 제한. +- 발견별 상태가 「고침 / 일부 / 결정 대기」 중 하나다. 「일부」와 「결정 대기」는 남은 것과 이유를 적는다(1103 README + 14.4절). 「결정 대기」 외에는 남기지 않는다(09장 5절). +- merge 판정이 필요하면 07장 3절 방법으로 14개를 통과했다. + +## 3. 리팩터링 + +**시작 조건** + +- 동작이 맞다. 바꾸려는 이유가 이해 비용·변경 비용이다(가이드 4·9·22·23절). +- 지켜야 할 동작·타입·실패·진단 계약을 적을 수 있다. 적을 수 없으면 리팩터링이 아니라 설계 변경이다. + +**단계** + +1. **보존 조건을 먼저 적는다.** 가이드 36.3절 「단순화의 보존 조건」, 39.9절. +2. **기존 테스트가 그 조건을 지키는지 본다.** 못 지키면 테스트부터 더한다(5절이 아니라 이 작업 안에서). +3. **바꾼다.** 이 repo의 고정 전제를 지킨다. + - 소비자 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이다. 지우지 않는다(`CLAUDE.md` 19줄). + - 갈라진 중복 복사본은 하나로 합친다(같은 줄, 부록 P-14). + - adapter 배럴(`src/adapters/*/index.ts`)이 공개 경계다. 배럴 밖으로 공개 표면을 늘리지 않는다(`CLAUDE.md` 20줄). +4. **같은 테스트가 그대로 통과한다.** 테스트를 고쳐야 통과하면 동작이 바뀐 것이다. 결함 수정이나 설계 변경으로 + 다시 분류한다. + +**산출물** + +- `refactor(): ...` 커밋. 본문에 보존 조건과 버린 대안(커밋 규칙 3.3절). + +**완료 기준** + +- 테스트 변경 없이 빠른 게이트 8개가 통과한다. +- 줄어든 이해 비용을 한 문장으로 말할 수 있다(읽을 파일 수, 알아야 할 규약 수 등). + +## 4. 성능 최적화 + +**시작 조건** + +- 같은 조건에서 두 번 이상 잰 숫자가 있고, 예산을 넘거나 회귀했다(06장 2절). +- 그 숫자를 만든 측정 조건(위치·부하·반복 수·빌드)을 안다. + +**단계** + +1. 기준선을 06장 3절 조건으로 다시 잰다. 예전 측정값을 기준선으로 쓰지 않는다. +2. 원인을 좁힌다. 무엇이 비용을 만드는지 네트워크 waterfall·청크 목록·trace로 확인한다. +3. 바꾼다. 초기 JS 예산·초기 파일 수 상한·lab 예산을 함께 본다. 하나를 줄이며 다른 하나를 넘기지 않는다(06장 4절). +4. 같은 조건으로 다시 잰다. 대조군(바꾸기 전 커밋)을 같은 세션에서 함께 잰다. +5. 기준선 파일을 고쳐야 하면 06장 5절 절차를 따른다. + +**산출물** + +- 전후 숫자와 측정 조건(06장 3절 항목 전부). `perf(): ...` 커밋. + +**완료 기준** + +- `check:bundle`(FE-GATE-012)과 lab 게이트(`test:performance`, FE-GATE-026)가 통과한다. +- 전후 차이가 측정 잡음보다 크다. 잡음 크기를 함께 적는다. + +## 5. 구조 변경 + +**시작 조건** + +- 최상위 `src/` 폴더, adapter 그룹, 기능·context 경계, import 규칙 중 하나가 바뀐다. + +**단계** + +1. 설계와 대안을 먼저 적는다(`superpowers:brainstorming` → `superpowers:writing-plans`). 가이드 41절의 일곱 질문. +2. 03장의 구조 기준을 확인한다. 특히 새 파일 단위 kernel 예외를 만들지 않는다(`CLAUDE.md` 21줄). +3. 규칙과 문서를 코드와 같은 커밋에서 바꾼다. + - import 규칙: `.dependency-cruiser.json`. + - 최상위 폴더: `docs/architecture/layers.md` 표 한 행. 같은 설명을 루트 `README.md`, `docs/architecture/overview.md`, + `docs/architecture/frontend-application-foundation.md`에도 그대로 적어야 `verify:documentation`이 통과한다 + (`scripts/verify-documentation-readiness.ts` 101~152줄). + - adapter 파일: `docs/reviews/adapters/INVENTORY.md`. +4. 제거 드릴을 돌린다. 지울 수 있는 단위(참조 기능, recipe, runtime)가 바뀌면 FE-GATE-020의 드릴이 그 변화를 안다 + (03장 6절). + +**산출물** + +- 설계 문서(커밋 범위가 크면 `docs/superpowers/plans/`), 코드·규칙·문서를 함께 바꾼 커밋. + +**완료 기준** + +- `check:architecture`, `check:adapter-inventory`, `verify:documentation`, FE-GATE-020이 통과한다. + +## 6. 테스트 구조 개선 + +**시작 조건** + +- 테스트가 주장을 증명하지 못한다(변이가 살아남는다, 템플릿 원래 상태만 본다). 또는 가끔 떨어진다. + +**단계** + +1. 가끔 떨어지는 테스트는 05장 5절 절차로 원인을 찾는다. 재시도·timeout 늘리기·worker 줄이기로 덮지 않는다. +2. 테스트 위치를 `docs/testing/taxonomy.md`의 층 기준으로 정한다. 프레임워크가 아니라 필요한 실행 환경이 층을 + 정한다(taxonomy 85~99줄). +3. 검출력은 변이로 확인한다. 고친 테스트가 원래 결함 변이를 잡는지 본다(`SPEC.md` 30줄). +4. 바뀐 테스트가 속한 게이트를 돌린다. 브라우저 테스트는 같은 조건에서 반복 실행 결과를 함께 적는다(05장 5절). + +**산출물** + +- `test(): ...` 또는 `fix(test): ...` 커밋. 본문에 원인, 결정적 재현 방법, 반복 실행 결과. + +**완료 기준** + +- 변이 또는 결정적 재현이 고친 뒤 기대대로 실패·통과한다. +- 반복 실행에서 실패 0이다. 횟수를 적는다(1103/11-10은 고친 뒤 30회 반복, 660/660 통과). + +## 지금 이해하면 되는 것 + +- 작업 종류는 "동작이 바뀌는가"와 "무엇을 근거로 시작하는가"로 고른다. +- 결함 수정은 RED 먼저, 발견 ID와 함께, 템플릿 원래 상태 밖에서도 확인한다. +- 리뷰는 코드를 고치지 않고, 게이트는 한 번 돌려 모두가 함께 읽는다. diff --git a/docs/improvement/09-working-method.md b/docs/improvement/09-working-method.md new file mode 100644 index 00000000..53c116ee --- /dev/null +++ b/docs/improvement/09-working-method.md @@ -0,0 +1,153 @@ +# 09. 작업 진행 방식 + +## 핵심 + +큰 개선 작업은 **총괄 세션 하나와 하위 세션·서브에이전트 여럿**으로 나눈다. 총괄은 맡기고, 모으고, 다시 확인하고, +멈출지 정한다. 하위 세션은 맡은 영역 하나를 끝까지 한다. + +```text +총괄(오케스트레이터) + ├─ 리뷰 라운드: 게이트 1회 실행 → 사본 공유 → 영역 리뷰어 16개 → 실험 목록 → 일괄 실행 → README + ├─ 수정 라운드: 영역별 수정 세션(격리 worktree·브랜치) → 통합 브랜치에 합침 → merge 게이트 14개 + └─ 멈출 조건 판정 → 마지막 Medium·Low 수정 → 보고 +``` + +이 장의 규칙은 2026-11-03~05 사용자 지시와 그때 리뷰 README에 남은 운영 기록이 출처다. 이 장이 그 규칙들의 repo 안 +정본이다(README 결정 M-9). + +## 1. 역할 + +| 역할 | 하는 일 | 하지 않는 일 | +| --- | --- | --- | +| 총괄 세션 | 범위·기준 커밋 고정, 게이트 실행, 영역 분할과 brief, 결과 통합, High·새 P1 재확인, 결정 정리, 멈춤 판정, 보고 | 영역 작업을 직접 다 하기. 총괄은 하위 세션에 맡긴다(사용자 지시) | +| 하위 세션 | 맡은 영역의 리뷰 또는 수정. 자기 worktree·브랜치에서 일하고 결과를 보고 | 다른 영역 파일 수정, push·PR, 범위 밖 수정 | +| 서브에이전트 | 한 번에 끝나는 조사·추출·리뷰. 결과를 파일로 남기고 짧게 보고 | 결정, 커밋 | + +- 하위 세션이 결정이 필요한 것을 만나면 총괄에 한 번 묻고 기다린다. 스스로 정하지 않는다. +- 짝 백엔드 repo(`clean-architecture-backend-template`)는 읽기만 한다. stage·commit·push하지 않는다(사용자 지시). + 백엔드에 넘길 것은 리뷰 README 「남은 문제」에 "백엔드에 넘길 것"으로 적는다(1103 README 14.7절). + +## 2. brief 쓰는 법 + +하위 세션이 아는 것은 brief뿐이다. 다음을 넣는다. + +1. 목표 한 문장과 끝났다고 볼 조건. +2. 기준 커밋·브랜치·작업 위치(worktree 경로). +3. 읽을 정본과 지난 기록의 위치(이 매뉴얼 장 번호로). +4. 하지 말 것: 리뷰면 코드 수정, 수정이면 범위 밖 파일·push·PR, 공통으로 짝 백엔드 쓰기. +5. 실행 위치와 잠금(07장 7절). +6. 보고 형식: 바꾼 것, 확인한 것(명령과 결과), 남은 것. 결론을 미리 주지 않는다. 총괄이 만든 변경을 리뷰시킬 때는 + 코드만 주고 결론은 주지 않는다(1103 README 10.5절 머리말). + +## 3. 리뷰 라운드 운영 + +1. 총괄이 기준 커밋을 고정하고 게이트를 **한 번** 돌린다(07장 3절). +2. 출력과 `artifacts/`·`dist/`·`test-results/`를 읽기 전용 사본으로 뜬다. 4라운드는 desktop의 + /tmp/claude-gates/r4/snap/ 에 두었다(1105 README 11.4절). +3. 영역 리뷰어를 병렬로 띄운다. 영역 표는 가장 최근 README의 것을 다시 쓴다(16개 영역, 1105 README 11.2절). +4. 리뷰어는 코드와 사본만으로 판정하고, 더 필요한 실험을 목록으로 낸다(4절). +5. 총괄이 실험을 일괄로 돌리고 결과를 영역에 돌려준다. +6. 총괄이 High 이상·새 P1을 직접 다시 확인하고 README를 쓴다(02장 6절). + +## 4. 리뷰 중 실행 — 한 번 돌리고 함께 읽는다 + +사용자 결정이다: 필요할 때만, 묶어서, 실행마다 환경을 되돌린다(1105 README 11.4절, 2026-11-05). + +- **게이트는 한 번.** 리뷰어마다 같은 빌드·테스트를 다시 돌리지 않는다. 4라운드 처음에 영역 리뷰어 16개가 각자 + desktop에서 실행하게 했다가 잠금 줄에 30여 건이 섰고 32건을 취소했다(1105 README 11.5절 첫 행). +- **추가 실험은 목록으로.** 항목마다 ID, 명령, env, 시간 상한, 필요하면 변이 패치를 적는다. +- **같은 명령은 한 번만.** 두 영역이 같은 변이를 원하면 한 번 돌리고 결과를 함께 쓴다(1105 README 11.4절 셋째 줄). +- **실험마다 작업 폴더를 되돌린다.** 항목 앞뒤로 추적 파일을 기준 커밋으로 되돌리고 추적 안 된 파일을 지운다 + (`node_modules`는 둔다). 4라운드 78항목 모두 `restore=clean`이었다. +- **복제본을 늘려 해결하지 않는다.** 한 checkout에서 두 실행이 부딪히는 원인은 고정 출력 경로·고정 포트라는 템플릿 + 결함이다(1105/12-04, 부록 P-06). 복제본을 늘리면 그 결함을 가리고 디스크·설치 비용만 는다. + +4라운드의 일괄 실행기와 그 사용법은 같은 세션 그룹의 공유 노트에 있다(07장 7절). + +## 5. 반복과 종료 + +### 5.1 반복 + +리뷰 → 수정 → 다음 라운드 리뷰를 반복한다(2026-11-04 사용자 결정). 라운드 하나의 순서: + +1. 수정을 통합 브랜치에 합친다(6절). +2. merge 게이트 14개를 돌린다(07장 3절). +3. 전체 리뷰를 한 번 더 한다. 지난 발견 전부를 ID별로 다시 판정하고 새 발견을 찾는다. 수정 세션의 "고침" 보고를 + 그대로 믿지 않는다. 1103 조치에서 "고침"으로 적은 것 중 13건이 4라운드에서 "일부"로 정정됐다 + (1105 README 3.1절). +4. 발견을 고친다. + +- 라운드 사이에 새 기능이나 큰 구조 변경을 넣지 않는다. 넣으면 발견 수가 줄어드는지 볼 수 없다. +- 라운드마다 새 발견 수를 High·Medium·Low와 P1로 나눠 앞 라운드와 비교한다(1105 README 4절 표). + +### 5.2 멈출 조건 + +다음 셋을 모두 채운 라운드에서 멈춘다(2026-11-04 사용자 결정). + +1. 그 라운드의 **새 High 0**. +2. 그 라운드의 **새 P1 0**. +3. **merge 게이트 14개 통과**(07장 3절 방법. 고른 스크립트 목록으로 판정하지 않는다). + +조건을 채워도 바로 끝내지 않는다. **그 라운드의 Medium·Low를 고치고** 멈춘다. 4라운드(1105)는 새 High 0이지만 새 +P1이 3건이고 FE-GATE-013이 desktop에서 실패해 조건을 채우지 못했다(1105 README 2.2절, 11.1절). + +멈춤 기준은 repo마다 자기 정본을 따른다. 백엔드는 "발견 0까지 확인 리뷰"를 쓴다. 두 기준을 하나로 맞추지 않는다 +(2026-11-05 소유자 결정 「각자 유지」, README 결정 M-7). + +### 5.3 남은 문제 0으로 보고한다 + +- 리뷰 발견은 Low까지 고친다. 보고의 "남은 문제"는 0이어야 한다(사용자 지시). +- 고칠 수 없는 것은 **결정 대기**로 남긴다. 이유, 선택지, 결정할 사람을 적는다(08장 4절 형식). "나중에", "범위 밖" + 같은 이유 없는 이월은 남기지 않는다. +- 개선 제안(결함이 아닌 것)도 열린 채 두지 않는다. 받아서 하거나, 하지 않는 이유를 결정으로 남긴다. + +### 5.4 반복 상한 + +1103 수정 라운드 뒤로 세 라운드를 더 돌아도 멈출 조건에 닿지 않으면 멈추고, 왜 수렴하지 않는지 소유자에게 +보고한다(2026-11-04 사용자 결정). 4라운드(1105)가 그 첫째다. 이 상한은 그동안 repo 밖 작업 메모에만 있었다. + +## 6. 수정 라운드 운영 + +1. 통합 브랜치를 만든다: `fix/maturity-review-`(리뷰 날짜). 예: `fix/maturity-review-2026-11-03` + (1103 README 14.1절). +2. 영역별 수정 세션이 격리 worktree의 `fix/r-<이름>` 브랜치에서 RED 테스트부터 고치고 커밋한다(wave 1). + 다른 수정에 기대는 묶음은 그 수정이 합쳐진 뒤 시작한다(wave 2). CHANGELOG·문서는 마지막에 한 세션이 다시 쓴다 + (wave 3). +3. 총괄이 브랜치를 `--no-ff`로 하나씩 합치고, 합칠 때마다 빠른 게이트를 돌린다(07장 2절). 합친 뒤에만 생긴 실패는 + README 「통합에서 생긴 것」에 커밋과 함께 적는다(1103 README 14.3절). +4. 통합 브랜치에서 merge 게이트 14개를 돌린다. `ci:gate`는 첫 실패에서 멈추므로 고칠 때마다 다시 돌리고, 회차별 + 결과를 표로 남긴다(1103 README 14.5절). +5. push·PR 본문·최종 보고는 총괄(또는 리뷰를 맡긴 세션)이 한다. 수정 세션은 하지 않는다(1103 README 14절 머리말). + +공통 지시(모든 수정 세션의 brief에 넣는다): RED 먼저, 논리적 변경 하나에 커밋 하나, 커밋 규칙, AI 꼬리말 금지, +`corepack pnpm`, 무거운 실행은 공유 잠금(1103 README 14.1절 셋째 줄). + +## 7. 소유자 환경 + +이 절은 이 repo 소유자의 도구에 묶인 규칙이다. 복사한 프로젝트는 이 절을 자기 환경으로 바꾼다(README 결정 M-4). + +- 세션 도구: Claude Code 데스크톱 앱. 총괄은 하위 세션을 띄우고, 하위 세션은 막힐 때 총괄에 한 번 묻는다. +- 공유 노트: 같은 세션 그룹은 repo 밖 공유 노트 폴더에 큰 발견과 인계 메모를 남긴다. 메시지에 길게 붙이지 않는다. + 예: 4라운드 리뷰 위치·일괄 실행기 사용법, FE-GATE-008 원인 조사 두 건. +- 실행 위치와 잠금: 07장 7절. +- 보고: 작업 완료 보고는 "변경 / 확인 / 남은 문제" 세 줄이다. 소유자의 전역 지시가 정본이다(repo 밖). + +## 8. 총괄이 자주 한 실수 + +리뷰 README의 「오케스트레이터 자신의 실수」 절에서 모았다. 같은 실수를 막는 규칙은 오른쪽 장에 있다. + +| 실수 | 결과 | 막는 규칙 | +| --- | --- | --- | +| 게이트 목록을 지난 라운드 목록에서 가져왔다 | 실제 러너에서 항상 실패하는 merge 게이트 둘을 놓쳤다(1103 README 10.5절) | 07장 3절: merge 단계 `gateIds`로 돌린다 | +| 판정 표를 짝 백엔드 문서만으로 정했다 | 업무 거절이 트랜잭션 전에 난다는 사실을 놓쳐 High를 만들었다(1103/03-01) | 04장 4절: 짝 사실은 코드까지 따라간다 | +| 다운스트림 파일을 열지 않고 이름으로 추정했다 | CHANGELOG에 틀린 이행 안내(1103/14-02) | 08장 4절: 확인하지 않은 것은 "미확인"으로 | +| 지운 코드의 실행 동작만 찾았다 | 지운 검사·테스트가 지키던 동작을 놓쳤다(1103/07-01, 10-04) | 04장 5절: 지울 때는 그 코드가 지키던 것을 찾는다 | +| 영역 리뷰어마다 desktop에서 실행하게 했다 | 잠금 줄 30여 건, 32건 취소(1105 README 11.5절) | 4절 | +| `verify:documentation`을 옆 checkout 없는 임시 worktree에서 `pnpm`으로 돌렸다 | pnpm이 재설치를 시도하다 TTY 없음으로 멈춰 결과가 무효(1105 README 11.5절) | 07장 6절 | +| 제거 드릴을 `npm run`으로 돌렸다 | 모든 검사가 `Unknown command`로 실패, 결과를 버렸다(1103 README 10.4절) | 07장 1절: `corepack pnpm`만 쓴다 | + +## 지금 이해하면 되는 것 + +- 총괄은 맡기고 모으고 다시 확인한다. 영역 작업은 하위 세션이 한다. +- 리뷰 중 실행은 총괄이 한 번 돌리고 모두가 함께 읽는다. 추가 실험은 목록으로 모아 일괄로 돌린다. +- 새 High 0·새 P1 0·merge 14개 통과면 그 라운드의 Medium·Low를 고치고 멈춘다. 못 고친 것은 결정 대기로 남긴다. -- 2.54.0 From 01b44952146a99d0dbc80a30adf3bd491e35e1fe Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:15:22 +0900 Subject: [PATCH 03/10] =?UTF-8?q?docs(improvement):=20=EC=9D=B4=20repo?= =?UTF-8?q?=EC=9D=98=20=EA=B2=B0=ED=95=A8=20=EC=A0=95=EC=9D=98=EC=99=80=20?= =?UTF-8?q?28=EA=B0=9C=20=EA=B4=80=EC=A0=90=20=EC=A0=90=EA=B2=80=20?= =?UTF-8?q?=EC=9C=84=EC=B9=98=EB=A5=BC=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 가이드는 공용 일반론이라 이 repo에서 무엇을 결함으로 보고 어떤 등급을 줄지, 28개 관점마다 어디를 볼지 정해져 있지 않다. 라운드마다 같은 모양의 등급 조정을 다시 했다. 고른 방법: 이 repo가 스스로 한 약속(지원 범위, 현재 계약, 게이트, 생성 명령, 제거 가능성, 짝 계약)으로 결함을 정의하고, 지난 라운드의 등급 판정 예(게이트가 틀린 답을 내면 Medium·P1 등), 증거 규칙, 28개 관점별 볼 곳·검사·대표 발견, 지난 발견 재판정 방법, README·영역 문서 절 순서를 적는다. 심각도 체계는 가이드 35.2·35.3 하나만 쓴다. 위험·한계: 관점별 "볼 곳"은 지난 리뷰의 판정표에서 뽑은 것이라 빠진 곳이 있을 수 있다. 검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤. --- docs/improvement/02-review-criteria.md | 172 +++++++++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 docs/improvement/02-review-criteria.md diff --git a/docs/improvement/02-review-criteria.md b/docs/improvement/02-review-criteria.md new file mode 100644 index 00000000..58c45bdc --- /dev/null +++ b/docs/improvement/02-review-criteria.md @@ -0,0 +1,172 @@ +# 02. 리뷰 기준 + +## 핵심 + +리뷰의 규칙은 `CLAUDE.md` 「리뷰 기준」(7~30줄)과 가이드가 정한다. 이 장은 그 규칙을 **이 repo의 경로·게이트·지난 +결함으로 바꿔** 적는다. 무엇을 결함으로 보는지, 등급을 어떻게 매기는지, 28개 관점마다 어디를 보는지, 리뷰 문서를 어떤 +모양으로 쓰는지. + +```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. 결함으로 보는 것 + +결함은 **이 repo가 스스로 한 약속**을 어기는 것이다. 약속은 다음에 있다. + +| 약속 | 어디에 | +| --- | --- | +| 지원 범위와 상태 값 | 루트 `README.md` 「Support scope」 | +| 현재 계약 | `docs/README.md` §1이 링크한 문서 | +| 게이트가 지키는 것 | `config/ci/gates.json`과 각 검사 스크립트 | +| 생성 명령으로 기능을 더하면 템플릿 파일을 고치지 않고 merge를 통과한다 | `docs/manual/README.md` 6줄, `docs/manual/reference/create-feature.md` | +| 지울 수 있다고 한 것은 지워도 게이트가 통과한다 | 루트 `README.md` 「Files you can delete after copying」, FE-GATE-020 | +| 짝 백엔드와 맞춘 계약 | `docs/architecture/backend-api-and-server-state-contract.md` 4.1·6·6.1절, `config/contracts/backend-contract-pin.json` | + +결함으로 보지 않는 것(`CLAUDE.md` 「이 repo의 리뷰 전제」, 가이드 0.1절 「지원·비지원」): + +- 소비자 없는 코드와 빈 레지스트리(다운스트림용 확장 지점). +- 지원 범위 밖이라고 적힌 기능이 없는 것(예: SSR, bulk `results`). 없는 기능을 결함으로 세지 않는다. +- 서버 메모리 상태·다중 인스턴스 경쟁. 실행 형태가 브라우저 SPA라 적용하지 않는다. 탭 사이 경쟁은 본다. +- 인터페이스가 많다, kernel이 크다는 사실만으로(가이드 35.2절 끝 문단). + +헷갈리는 경우: + +| 경우 | 판정 | 예 | +| --- | --- | --- | +| 게이트가 코드와 무관하게 항상 실패하거나, 실패 이유를 숨긴다 | 결함. 사용자 피해가 없으면 Medium, merge·release를 막으면 P1 | 1103/02-06, 1105/12-01, 1105/13-01 | +| 게이트가 PASS인데 그 뒤 단계가 실패한다 | 결함(검사가 거짓 PASS를 낸다) | 1105/12-01, 1103/11-04 | +| 문서 문장이 코드와 다르다 | 결함. 코드가 맞다. 문장이 사용자를 틀린 행동으로 이끌면 등급을 올린다 | 1103/14-02(틀린 이행 안내) | +| 같은 사실을 여러 곳에 손으로 적었고 아직 같다 | 구조적 위험 | 1103 README 5절 원인 4 | +| 같은 사실의 손 사본이 이미 서로 다르다 | 확인된 결함 | 1105/01-02 | +| 수정이 템플릿 원래 상태에서만 맞다 | 결함. 지원 구성(기능 추가·예제 제거)에서 재현하면 확인된 결함 | 1105/09-01 | + +## 2. 심각도와 우선순위 — 이 repo의 판정 예 + +가이드 35.2·35.3절을 지난 라운드가 이렇게 적용했다. 같은 모양이면 같은 등급을 준다. 등급을 영역 제안과 다르게 +매기면 README 「심각도 조정」 표에 이유를 남긴다(1103 README 2.3절, 1105 README 2.4절). + +| 등급 | 이 repo의 예 | +| --- | --- | +| High·P1 | 결과 불명 쓰기를 키 없이 다시 보내 같은 항목이 둘 생긴다(0929/03-03 상향, 가이드 35.2절 High 예시와 같은 모양). 짝 백엔드의 업무 거절이 모든 쓰기에서 결과 불명이 되어 폼이 막힌다(1103/03-01). 두 템플릿을 짝으로 쓰면 업로드가 연결되지 않는다(1103/01-01) | +| Medium·P1 | 사용자 피해 없이 merge·release 게이트가 틀린 답을 내거나 이유를 숨긴다(1103/02-06, 1103/12-01, 1103/15-01, 1105/09-01, 1105/12-01, 1105/13-01). "생성 명령으로 빠른 출시"라는 핵심 약속을 깨는 것도 여기다 | +| Medium·P2 | 위험한 경로가 남았지만 템플릿이 그리는 경로는 막고, 제품이 직접 hook을 부를 때만 닿는다(0929/03-03 남은 부분) | +| Low·P3 | 낡은 문장, 이름, 작은 진단 누락 | + +- **P1의 기준:** 도입·출시·확대 전에 해결해야 하는 것(가이드 35.3절). 이 repo에서는 merge 게이트 14개를 막는 것과, + 지원 구성에서 짝 백엔드와 쓰는 기본 경로를 막는 것이다. +- **복제 범위를 함께 적는다.** 다운스트림 둘(tech-log, memento)이 그대로 복제하는 기본값이면 그 사실을 적는다(가이드 + 35.2절 「다음 정보를 함께 적는다」). + +## 3. 증거 규칙 + +- **현재 커밋에서 찾는다.** README와 설계 문서는 주장이다. 근거는 코드·설정·실행 결과다(`CLAUDE.md` 14줄, 가이드 + 34.1절). 지난 리뷰의 실행 결과를 현재 증거로 쓰지 않는다. 다른 세션이 같은 커밋에서 낸 결과도 가져다 쓰지 않고 + 다시 돌린다(1105 README 11.1절 끝 문단). +- **실행 증거에는 조건을 붙인다.** 커밋, 위치(desktop), env(workflow env인지), 부하, 반복 수. 부하가 높을 때의 실패는 + 따로 표시한다(1103 README 10.4절). +- **desktop에 workflow env를 준 실행은 실제 러너가 아니다.** 실제 Gitea 러너는 꺼져 있다. 그 사실을 미검증에 적는다 + (1105 README 8절 첫 행). 이 실행의 증거 수준은 E2~E3이고, 「실제 CI 미검증」을 함께 적는다. +- **"오케스트레이터 확인"의 뜻을 지킨다.** 재확인 칸에 이 말을 쓰면 총괄이 그 줄을 직접 읽었거나 직접 실행했다는 + 뜻이다(1103 README 2절 머리말). +- **확인하지 못한 것은 「미확인」이다.** M0(통제 부재 확인)와 다르다(`CLAUDE.md` 12줄). + +## 4. 28개 관점 — 이 repo에서 볼 곳 + +관점의 일반 설명은 가이드 1~28절이다. 아래는 이 repo에서 먼저 볼 곳과 그 관점을 지키는 검사, 지난 대표 발견이다. +「검사」 칸이 비어 있으면 그 관점을 기계로 지키는 게이트가 없다는 뜻이다. + +| # | 관점 | 이 repo에서 볼 곳 | 검사 | 지난 대표 발견 | +| --- | --- | --- | --- | --- | +| 1 | 코드 성숙도 | 판정 규칙이 모인 곳: `src/adapters/http/backend-envelope.ts`, 효과 분류, 폼 상태 | FE-GATE-002·003 | 1103/03-01 | +| 2 | 구조적 성숙도 | `docs/architecture/layers.md`, `.dependency-cruiser.json`(03장) | `check:architecture`(FE-GATE-010) | 0929/12-03 | +| 3 | 변경 용이성 | 기능 하나를 더하거나 지울 때 템플릿 파일을 고쳐야 하는가 | FE-GATE-020 | 1103/12-01, 1105/09-01 | +| 4 | 인지 부하 | 기능 작성자가 알아야 할 등록 규약 수, `docs/manual/` 막힘 | | 1103 README 14.6절(매뉴얼만으로 기능 추가 재실험) | +| 5 | 위험 가시성 | 결과 불명·재전송·삭제 같은 위험이 코드와 화면에 드러나는가(가이드 29절) | | 1105/13-01, 1105/12-01 | +| 6 | 실패 성숙도 | 짝 백엔드 오류 응답의 분류, 결과 불명 처리 | FE-GATE-007 | 1105/01-01 | +| 7 | 운영 성숙도 | `docs/runbooks/`, `docs/operations/`, release job 로그 | FE-GATE-021~025 | 1105/13-01 | +| 8 | 디버깅 가능성 | 실패 메시지가 원인과 고칠 파일을 말하는가, `traceId` | | 1105/12-01 | +| 9 | 유지보수 성숙도 | 낡은 문장, CHANGELOG 미출시 절 | `verify:documentation` | 1103/14-01, 1105/14-01 | +| 10 | 테스트 성숙도 | 변이 검출, 템플릿 원래 상태 밖 입력(05장) | FE-GATE-005~009 | 1103/10-02, 1103/05-01 | +| 11 | 데이터 성숙도 | 로그아웃·계정 삭제 뒤 남는 데이터(IndexedDB, OPFS, Cache Storage) | | 1103/05-01 | +| 12 | 동시성 성숙도 | 탭 사이 경쟁, Web Locks, 같은 입력 재제출, 한 checkout 두 실행 | | 1103/05-01, 1105/12-04 | +| 13 | 확장성 | 기능 수 증가 축: 초기 JS 여유, 기능 모양 상한 | `check:scale:pr`(FE-GATE-005), FE-GATE-012 | 1105/15-02 | +| 14 | 성능 성숙도 | 06장 | FE-GATE-012·026 | 1103/15-01 | +| 15 | 보안 성숙도 | `docs/security/browser-boundary.md`, 저장 키, 401 전달, CSP | FE-GATE-013 | 1103/13-03 | +| 16 | 의존성 성숙도 | advisory, lockfile, 의존성 변경 증거 | FE-GATE-001·013 | 1103/13-03 | +| 17 | API / Contract 성숙도 | 짝 백엔드 계약 pin, 답 표, 생성기가 옮긴 사실 | FE-GATE-007, 짝 계약 대조 테스트(1103 결정 D6) | 1105/07-01, 1105/16-02 | +| 18 | 배포 성숙도 | `docs/architecture/static-delivery.md`, 호스팅 헤더, 배포 슬롯 | FE-GATE-019 | 1105/13-02 | +| 19 | 설정 성숙도 | 런타임 설정과 빌드 식별값, CI env | `verify:documentation`(runtime variables) | 1103/11-07, 1103/11-08 | +| 20 | 개발자 경험 | `create:feature`, 로컬 실행, 한 파일 테스트 실행 | | 1105/16-04 | +| 21 | Guardrail 성숙도 | 게이트가 맞는 답을 내는가, 사전 점검이 실제로 확인하는가 | `check:ci` | 1105/12-01, 1105/09-01 | +| 22 | 추상화 성숙도 | descriptor·포트가 실제 요청을 통제하는가 | | 1103/04-01 | +| 23 | 일관성 | 같은 판정을 하는 두 표가 같은가 | | 1105/01-02 | +| 24 | 네이밍 / 의미 성숙도 | 오류 code·상태 이름의 뜻 | | 1105/04-02 | +| 25 | 조직 확장성 | 기능 브랜치끼리 같은 줄 충돌, 다운스트림 동기화 비용 | | 1105/16-01 | +| 26 | Ownership 성숙도 | 규칙 `comment`의 담당·재검토 조건, 두 repo 사이 몫 | | 1105/13-02 | +| 27 | 삭제 가능성 | 참조 기능·recipe·선택 runtime 제거(03장 6절) | FE-GATE-020 | 1105/14-01 | +| 28 | 회복 가능성 | 회복 필요 응답 뒤 행동, SW 비상 경로, release rollback | FE-GATE-025 | 1105/02-02 | + +## 5. 다시 판정할 때 + +다음 라운드 리뷰는 지난 발견 전부의 지금 상태를 표 하나로 적는다(1105 README 13절). + +- 상태: 고침 / 일부 / 남음 / 결정 대기. 지난 「고침」도 코드로 다시 본다. 4라운드는 1103 조치의 「고침」 13건을 + 「일부」로 정정했다. 코드는 들어왔지만 완료 기준 실행이 없으면 「일부」다(가이드 35.6절, 1105 README 3.1절, 부록 + P-27). +- 「일부」면 남은 부분에 새 등급을 매긴다. 남은 부분이 원래보다 좁으면 등급을 내린다(1105 README 2.3절 표). +- 지난 수정이 만든 새 결함은 새 발견으로 세고, 원인 수정 커밋을 적는다(1105 README 4절 끝 목록). + +## 6. 리뷰 문서 형식 + +### 6.1 폴더와 ID + +- 폴더: `docs/reviews/-maturity-review/`. README 하나와 영역 문서 `NN-<영역>.md`(`CLAUDE.md` 29줄). +- 발견 ID는 라운드 안에서 `NN-MM`(영역 번호-순번). 라운드 밖에서는 `MMDD/NN-MM`(가이드 36.3절). +- 총괄이 직접 찾은 발견은 관련 영역 번호를 쓰고 README 「오케스트레이터 발견」 절에 둔다(1105 README 14절). + +### 6.2 README 절 순서 + +4라운드 README(1105)의 순서다. 가이드 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 지난 발견 상태 | 5절 | +| 14 오케스트레이터 발견 | 36.3절 양식 | +| 15 새 발견 색인 | 영역 문서에서 기계적으로 모은다. 손으로 옮기지 않는다 | + +수정 라운드가 끝나면 같은 README에 「조치」 절을 더한다(01장 2절 산출물). + +### 6.3 영역 문서 절 순서 + +1103·1105 영역 문서의 순서다(예: 1103 `11-tests-browser-release-scale.md`). + +| 절 | 내용 | +| --- | --- | +| 0 결론 | 몇 줄 | +| 1 범위 | 36.1절. 읽은 경로, 돌린 것, 확인하지 못한 것 | +| 2 지난 발견 재판정 | 5절 | +| 3 이번 발견 | 36.3절 양식. 설계 선택이 없는 단순 결함은 선택 비교 칸을 「적용 제외」와 한 문장 이유로 | +| 4 28개 관점 판정 | 36.2절 | +| 5 설계 선택 설명 | 가이드 41절. 여러 타당한 선택지가 있는 발견만 | +| 6 실험·실행 기록 | 어디서 무엇을 돌렸나, 명령·결과 표, 미검증 목록 | + +## 지금 이해하면 되는 것 + +- 결함은 이 repo가 스스로 한 약속(지원 범위, 현재 계약, 게이트, 생성 명령, 제거 가능성, 짝 계약)을 어기는 것이다. +- 게이트가 틀린 답을 내거나 이유를 숨기면 사용자 피해가 없어도 Medium·P1이다. +- 증거는 현재 커밋의 실행에서, 조건을 붙여서. 지난 「고침」도 다시 본다. -- 2.54.0 From 05f0083538e1002bb20397010c0f322a3aad8298 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:15:22 +0900 Subject: [PATCH 04/10] =?UTF-8?q?docs(improvement):=20=ED=8F=B4=EB=8D=94?= =?UTF-8?q?=C2=B7=EB=AA=A8=EB=93=88=20=EA=B5=AC=EC=A1=B0=EC=99=80=20?= =?UTF-8?q?=EC=BD=94=EB=93=9C=20=EA=B5=AC=EC=A1=B0=EC=9D=98=20=EA=B0=9C?= =?UTF-8?q?=EC=84=A0=20=EA=B8=B0=EC=A4=80=EC=9D=84=20=EC=A0=81=EB=8A=94?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 구조를 바꿀 때 같이 고칠 정본(layers.md, .dependency-cruiser.json, INVENTORY)과, 게이트가 막지 못해 다섯 라운드 반복된 코드 결함(실패 분류, 결과 불명 재전송, 손 사본, 지운 코드가 지키던 검사)을 막는 기준이 문서로 묶여 있지 않다. 고른 방법: 03장에 정본 표, 이 repo의 고정 전제(확장 지점 유지, 갈라진 복사본 합치기, 배럴 경계, kernel 예외 셋), 바꿀 때 같이 고칠 것, 문서 위치, 제거 가능성을 적는다. 04장에 판정 규칙 한 곳, 실패 드러내기, 같은 사실 한 곳, 지우거나 바꿀 때, 설정·환경, 동시성, 확장 지점, 수정이 새로 가정하는 것을 적고 부록 패턴을 가리킨다. 새 파일 단위 kernel 예외는 제안하지 않는다. 위험·한계: "모든 대기에는 끝나는 조건이 있다"는 지난 완료 기준을 일반화한 [제안]이다. 검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤. --- .../improvement/03-folder-module-structure.md | 99 ++++++++++++++ docs/improvement/04-code-structure.md | 127 ++++++++++++++++++ 2 files changed, 226 insertions(+) create mode 100644 docs/improvement/03-folder-module-structure.md create mode 100644 docs/improvement/04-code-structure.md diff --git a/docs/improvement/03-folder-module-structure.md b/docs/improvement/03-folder-module-structure.md new file mode 100644 index 00000000..13caa63a --- /dev/null +++ b/docs/improvement/03-folder-module-structure.md @@ -0,0 +1,99 @@ +# 03. 폴더·모듈 구조 기준 + +## 핵심 + +폴더 구조의 규칙은 이미 코드와 게이트에 있다. 이 장은 **구조를 바꿀 때 어느 정본을 같이 고쳐야 하는지**와 +**리뷰에서 구조 결함으로 볼 것과 보지 않을 것**만 적는다. + +```text +src/ 최상위 9개 폴더 ── 역할: docs/architecture/layers.md 표 + │ 규칙: .dependency-cruiser.json (check:architecture, FE-GATE-010) + ├─ adapters/<그룹>/index.ts ── 공개 경계(배럴) + │ └─ platform/** 등 kernel 3곳만 그룹을 넘어 import 가능 + ├─ features// ── 지울 수 있는 기능 하나 (제거 드릴, FE-GATE-020) + └─ contexts/, apps/ ── 기능 묶음과 배포 단위 +``` + +## 1. 정본 + +| 무엇 | 정본 | 검사 | +| --- | --- | --- | +| 최상위 `src/` 폴더 9개와 각 역할 | `docs/architecture/layers.md` 7~21줄 표 | `verify:documentation`이 폴더 목록·설명 일치를 본다(`scripts/verify-documentation-readiness.ts` 101~152줄) | +| import 규칙 31개 | `.dependency-cruiser.json` `forbidden`, 설명은 `docs/architecture/layers.md` 33~75줄 | `check:architecture` | +| adapter kernel | `docs/architecture/layers.md` 77~97줄, `.dependency-cruiser.json` 253~261줄 | `check:architecture` | +| 규칙 예외의 이유·담당·재검토 조건 | 그 규칙의 `comment`(`docs/architecture/layers.md` 104~117줄) | 사람이 본다 | +| adapter 그룹의 공개 경계 | `docs/architecture/layers.md` 119줄부터, 규칙 `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/README.md` | `verify:documentation` | + +## 2. 이 repo의 고정 전제 + +`CLAUDE.md` 「이 repo의 리뷰 전제」(19~22줄)를 구조 기준으로 읽으면 다음과 같다. + +1. **확장 지점은 남긴다.** repo 안에 소비자가 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이다. 죽은 코드로 + 보고 지우지 않는다. 2026-09-16 사용자 결정 1(08장 표 O-1)이 출처다. +2. **갈라진 중복 복사본은 하나로.** 같은 일을 하는 코드가 두 벌이고 서로 달라지기 시작했으면 결함이다(부록 P-14). + 합칠 곳은 kernel(`src/adapters/platform/`)이나 `src/contracts/`다(`SPEC.md` 34줄). +3. **배럴이 공개 경계다.** 그룹 바깥(`src/bootstrap`, `src/features`, `src/presentation`)은 그룹의 `index.ts`만 import한다. + 배럴 폐지는 2026-09-16에 기각됐다(08장 표 O-2). +4. **kernel 예외는 셋뿐이다.** `src/adapters/platform/` 폴더 전체, `src/adapters/browser-file-storage/result.ts`, + `src/adapters/cross-context-invalidation/index.ts`. 새 파일 단위 예외를 제안하지 않는다(`CLAUDE.md` 21줄). 새 공유 + 프리미티브는 `src/adapters/platform/`에 넣는다. 폴더 전체가 예외라 규칙을 바꿀 필요가 없다. +5. **실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker다.** 서버 메모리 상태·다중 인스턴스 경쟁 기준은 적용하지 + 않는다. 탭 사이 경쟁은 적용한다(1105 README 0절). + +## 3. 바꿀 때 같이 고칠 것 + +| 바꾸는 것 | 같은 커밋에서 고칠 것 | +| --- | --- | +| 최상위 `src/` 폴더 추가·삭제 | `docs/architecture/layers.md` 표 한 행. 같은 설명 문장을 루트 `README.md`, `docs/architecture/overview.md`, `docs/architecture/frontend-application-foundation.md`에 그대로 | +| import 규칙 추가·이름 변경 | `.dependency-cruiser.json`, `docs/architecture/layers.md` 규칙 표의 행(규칙 이름이 빠지면 `verify:documentation`이 실패) | +| 규칙 예외 | 그 규칙의 `pathNot`과 `comment`(이유·담당·재검토 조건). 파일 단위 kernel 예외는 만들지 않는다 | +| adapter 파일 추가·이동·삭제 | `docs/reviews/adapters/INVENTORY.md`(`SPEC.md` 33줄) | +| adapter 그룹 공개 표면 | 그 그룹의 `index.ts`. 2단계 `index.ts`는 공개 배럴이 아니다(예외: `storage/indexeddb`, `storage/opfs` 서브배럴) | +| 기능·context 경계 | `src/features//`와 `tests/features//`. 기능끼리, context끼리 import하지 않는다(규칙 `features-do-not-import-other-features`, `contexts-do-not-import-other-contexts`) | +| 지울 수 있는 단위(참조 기능, recipe, 선택 runtime) | 그 단위의 제거 드릴이 함께 지울 목록. 예: `scripts/test-sample-removal.ts`의 머리말 주석과 `SAMPLE_EXTRAS`(루트 `README.md` 「Files you can delete after copying」 아래 문단) | + +## 4. 문서 위치 + +| 문서 | 둘 곳 | +| --- | --- | +| 지금 코드가 지키는 규칙 | `docs/README.md` §1 묶음. 링크하면 `verify:documentation` 범위에 든다 | +| 앞으로의 설계·결정 | §2 묶음. ADR은 `docs/architecture/decisions/` | +| 리뷰·계획·작업 추적 | §3 묶음(`docs/reviews/`, `docs/superpowers/`). 복사한 프로젝트가 지울 수 있다 | +| 새 기능 절차 | `docs/manual/` | +| 개선 작업 기준 | `docs/improvement/`(이 매뉴얼) | +| 여러 repo에 걸친 설계·공통 원칙 | repo 밖 `design-docs`. 템플릿 `docs/`에 두지 않는다(`docs/manual/README.md` 「이 폴더에 두지 않는 것」) | + +- 코드·테스트·스크립트·설정은 지워도 되는 문서(`docs/reviews/`, `docs/superpowers/`, `SPEC.md`, `CLAUDE.md`, `tasks/`)를 + 읽지 않는다. 예외는 `docs/reviews/adapters/INVENTORY.md` 하나다. `tests/unit/deletable-history-documents.test.ts`가 + 검사한다. 테스트가 리뷰 문서를 열어 제거 드릴 셋을 깨뜨린 적이 있다(같은 파일 머리말). +- 현재 계약 문서는 작업 이력 문서에 기대지 않는다(`docs/manual/README.md` 68줄). + +## 5. 리뷰에서 구조 결함으로 보는 것 + +| 결함으로 본다 | 결함으로 보지 않는다 | +| --- | --- | +| 갈라진 중복 복사본(부록 P-14) | 소비자 없는 확장 지점, 빈 레지스트리 | +| 같은 사실을 여러 곳에 손으로 다시 적는다(부록 P-03) | 인터페이스가 많다는 사실만으로(가이드 35.2절) | +| 문서가 없는 폴더·규칙을 말한다 | kernel 폴더가 크다는 사실만으로 | +| 템플릿 파일을 고쳐야 기능을 더하거나 지울 수 있다(1103 README 5절 원인 2) | 다운스트림이 쓰지 않는 선택 runtime | +| 지울 수 있다고 한 단위를 지우면 게이트가 실패한다(1105/14-01) | | + +## 6. 제거 가능성 + +지울 수 있는 단위는 merge 게이트 FE-GATE-020의 드릴이 지켜 준다. 드릴 목록은 `config/ci/gates.json`의 FE-GATE-020 +`commandIds` 다섯 개다(`test:sample-removal`, `test:feature-scaffold`, `test:optional-recipe-removal`, +`test:browser-file-storage-removal`, `test:realtime-removal`). + +- 구조를 바꾸면 드릴을 돌린다. 드릴 fixture가 복사하는 파일 목록이 바뀐 구조를 아는지 본다. fixture 복사 목록에 + `README.md`·`CHANGELOG.md`가 없어 드릴 넷 중 셋이 항상 실패한 적이 있다(1103/02-06). +- 드릴은 오래 걸린다. FE-GATE-020은 1,150초 안팎이다(1105 README 11.1절). desktop에서 잠금 아래 돌린다(07장 7절). + +## 지금 이해하면 되는 것 + +- 폴더 역할은 `layers.md`, import 규칙은 `.dependency-cruiser.json`, adapter 목록은 `INVENTORY.md`가 정본이다. +- 확장 지점은 남기고, 갈라진 복사본은 합친다. 새 공유 코드는 `src/adapters/platform/`이나 `src/contracts/`로. +- 구조를 바꾸면 규칙·문서·INVENTORY를 같은 커밋에서 고치고 제거 드릴을 돌린다. diff --git a/docs/improvement/04-code-structure.md b/docs/improvement/04-code-structure.md new file mode 100644 index 00000000..441701f6 --- /dev/null +++ b/docs/improvement/04-code-structure.md @@ -0,0 +1,127 @@ +# 04. 코드 구조 기준 + +## 핵심 + +결함을 고치거나 리팩터링할 때 지킬 코드 기준이다. 계층·import 규칙은 03장과 게이트가 지킨다. 이 장은 **게이트가 +지키지 못하고 다섯 라운드 동안 반복된 결함**을 막는 기준을 적는다. + +```text +판정 규칙은 한 곳에 → 실패 분류·결과 불명·멱등 키 (2절) +실패는 드러나게 → 원인을 싣고, 멈추지 않고, 사실대로 보고 (3절) +같은 사실은 한 곳에 → repo 안 손 사본, 두 템플릿 사이 손 사본 (4절) +지우거나 바꿀 때 → 그 코드가 지키던 것을 찾는다 (5절) +설정·환경은 한 출처에서 → 빌드 설정, base path, 테스트 env (6절) +고칠 때 → 수정이 새로 가정하는 것을 적는다 (8절) +``` + +각 기준 끝의 `P-NN`은 부록 결함 패턴 카탈로그의 행이다. 그 행에 지난 발견 ID가 있다. + +## 1. 정본 + +| 무엇 | 정본 | +| --- | --- | +| 계층과 import 방향 | `docs/architecture/layers.md`, `.dependency-cruiser.json`(03장) | +| 재시도 의미, 결과 불명, 인증, 업로드의 판단 기준 | `docs/manual/02-decision-tables.md` 3·4·5·7절 | +| 오류 모델, 재시도 모델, 실패 경계, trace | `scale-architecture.md §13`, `§17`, `§29`, `§30` (`docs/architecture/scale-architecture.md`) | +| 짝 백엔드 응답의 판정 표 | `src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE`, 근거 문서 `docs/architecture/backend-api-and-server-state-contract.md` 6.1절 | +| 위험을 코드에 드러내는 방법 | 가이드 29절 | +| 설계 의도와 단순화의 보존 조건 | 가이드 39절 | + +## 2. 판정 규칙은 한 곳에 + +- **실패 분류는 status 하나로 하지 않는다.** status와 code를 함께 본다. 표 밖의 값은 안전한 쪽(결과 불명)으로 둔다. + 업무 거절이 결과 불명으로, 일시 오류가 무결성 실패로, rate-limit 503이 결과 불명으로 분류되는 결함이 두 라운드 + 다섯 영역에서 났다. P-28 +- **짝 백엔드 쓰기 응답의 판정 표는 `REFUSED_BEFORE_WRITE` 하나다.** 실행 경로가 둘이어도 같은 표를 읽는다. 표를 + 경로마다 따로 두면 두 번째 표가 다시 갈라진다(1101 README 14.6절의 버린 대안). operation 단위 예외는 descriptor의 + `commandEffect.refusedBeforeWrite` code 목록으로만 선언한다(1103 결정 D2). +- **결과 불명 쓰기를 다시 보내는 모든 입구를 함께 본다.** 재전송 버튼, hook 재제출, 실행기 재시도, poll 재시도, 업로드 + 재시도. 하나를 막으면 다른 입구에서 다시 나왔다. 키 없는 쓰기(`NEVER`)는 결과 불명 뒤 재전송하지 않는다. 키 있는 + 쓰기는 같은 키로만 다시 보낸다. P-29 +- **판정 규칙의 경계를 테스트로 고정한다.** 경계 하나를 바꾸는 변이가 게이트에서 실패해야 한다(05장 3.2절). P-13 + +## 3. 실패는 드러나게 + +- **원인과 추적값을 싣는다.** 실패 객체·진단에 effect, reason, `traceId`, 어느 참여자인지를 싣는다. 서로 다른 실패를 + 같은 reason으로 남기지 않는다. 진단 reason은 이 repo가 소유한 닫힌 목록이고 서버 code를 그대로 넣지 않는다. + 서버 code는 실패의 `AppFailure.code`에 남는다(커밋 `93782b0` 결정, 1101 README 14.6절). 한 모듈에서 고친 누락이 새 모듈에서 다시 생겼다. 새 adapter는 같은 + 기준으로 리뷰한다. P-33 +- **오지 않을 신호를 기다리지 않는다.** 모든 대기에는 끝나는 조건(예산 소진, 마감, 취소)이 있다 **[제안]** — 지난 + 완료 기준(0925/04-01 "예산을 실제로 소진했을 때만 terminal")을 일반 규칙으로 올린 것이다. P-30 +- **손상 한 건이 전체를 멈추지 않게 한다.** 손상 행은 건너뛰고 수를 보고한다(1101 README 14.1절 0929/05-01 행). + P-31 +- **결과를 사실대로 보고한다.** 다 하지 못했으면 `COMPLETED`·`verified`·`active`를 보고하지 않는다. 상태를 읽은 + 시점과 보고하는 시점 사이에 다른 작업(다른 탭의 put, release)이 끼어들 수 있으면, 같은 잠금 아래에서 다시 대조하거나 + 끝난 뒤 한 번 더 센다(1105 README 9절 1103/05-01 행). 테스트는 객체 셋 이상으로 한다. P-32 +- **실패·복구 전이 뒤 화면이 다음 행동을 남긴다.** 실패 표시에서 고친 포커스·안내 장치를 복구 성공, 확인, 진행 중 + 전이에도 쓴다. 페이지마다 복사하지 않고 공용 폼 hook 안에서 한다. P-38 +- **확인하지 못한 판정은 `PASS`가 아니라 `UNVERIFIED`다.** 코드에 상수 `true` 판정을 두지 않는다(`SPEC.md` D-14). + +## 4. 같은 사실은 한 곳에 + +- **repo 안:** 스키마 메타, 레지스트리 행, 허용 키 목록, 빌드 입력 목록, 저장 키를 원본(zod 스키마, descriptor, + registry)에서 뽑는다. 손으로 다시 적어야 하면 원본과 대조하는 테스트를 같이 둔다. 두 검사기가 같은 산출물을 다른 + 키 목록으로 읽어 merge 게이트가 항상 실패한 적이 있다(1103/12-09). P-03 +- **이미 갈라진 복사본은 하나로 합친다.** 합칠 곳은 `src/adapters/platform/`(adapter 공용 메커니즘)이나 + `src/contracts/`(공유 어휘)다. 갈라진 recipe port는 지우고 `src` port를 다시 내보낸다(1101 README 14.1절 0929/05-03 + 행). P-14 +- **두 템플릿 사이:** 짝 백엔드의 프로토콜·오류 code·응답 모양·생성기 규칙을 프론트에 옮길 때는 백엔드 문서만 보지 + 않고 **코드까지 따라간다**(백엔드 생성기, 프론트 폼까지). 판정 표를 백엔드 계약 문서만으로 정해 High를 만든 적이 + 있다(1103 README 10.5절 03-01 행). 옮긴 사실은 기준 커밋(`config/contracts/backend-contract-pin.json`)과 대조 + 테스트로 묶는다(1103 결정 D6). pin과 drift 검사는 아직 계약 문서 글자만 비교한다. 답 표 JSON과 생성기 사실은 대조 + 밖이다(1105/07-01, 1105/16-02). P-04 +- 짝 백엔드 repo는 읽기만 한다. 백엔드가 바꿔야 할 것은 "백엔드에 넘길 것"으로 적는다(09장 1절). + +## 5. 지우거나 바꿀 때 + +- **그 코드가 지키던 것을 찾는다.** 실행 동작만 옮기면 지운 행·테스트·분기가 지키던 규칙이 조용히 사라진다. V2 + 삭제 때 실행 동작 셋만 찾고, 지운 검사·테스트가 지키던 것을 놓쳤다(1103/07-01, 1103/10-04). 지우기 전에 그 코드를 + 읽는 테스트와 검사를 `git grep`으로 찾고, 각각이 지키던 규칙이 새 경로에도 있는지 적는다. P-23 +- **이름을 바꿀 때는** 새 이름을 내고 옛 이름은 한 릴리스 동안 `@deprecated` 별칭으로 남긴다(1101 README 14.1절 + 16-03 행). 이름 하나가 여러 뜻을 가지거나 한 뜻이 여러 이름을 가지면 결함이다. P-37 +- **확장 지점은 지우지 않는다.** 소비자 없는 코드와 빈 레지스트리는 다운스트림용이다(03장 2절). +- **공개 포트는 추가만 한다.** 깨야 하면 결정 표에 적고 BREAKING으로 커밋한다(`SPEC.md` 35줄, 08장 6절). + +## 6. 설정·환경은 한 출처에서 + +- **같은 설정을 경로마다 다르게 읽지 않는다.** 번들, 빌드 스크립트, Service Worker 빌드가 같은 출처에서 읽는다. P-35 +- **URL은 router base path를 따른다.** `/`부터 직접 조립하지 않는다. 기본 게이트가 루트 경로만 돌아 드러나지 않는다. + 하위 경로 빌드 테스트로 확인한다. P-34 +- **테스트가 띄우는 빌드·서버의 env는 테스트가 정한다.** workflow가 job 전체에 주는 `CI=true`와 빌드 식별값이 + vitest·dev server·테스트 안 빌드로 새면 실제 CI에서만 실패한다. 테스트용 로컬 빌드 식별값은 + `scripts/lib/build-environment.ts`가 한 곳에서 준다. 테스트마다 env에서 기대값을 읽는 방식은 버렸다(다음 테스트가 + 같은 실수를 한다). P-05 +- **환경 가정은 적고, 확인하고, 없으면 이유를 말하며 실패한다.** 글꼴, user namespace, 옆 checkout(07장 5·6절). P-08 + +## 7. 동시성 + +- 여러 탭이 같은 저장소·구독·잠금을 건드리는 경로는 Web Locks로 직렬화하거나, 잠금 없이도 안전한 이유를 적는다 + (`SPEC.md` D-3·D-4). 잠금을 기다리는 작업에는 abort와 상한이 있다. P-36 +- 실행 형태가 브라우저 SPA라 서버 다중 인스턴스 경쟁은 보지 않는다. 탭 사이 경쟁은 본다(02장 1절). + +## 8. 확장 지점과 경계 + +- **제품마다 다른 것은 제품 소유 파일에 둔다.** 제품이 템플릿 소유 파일을 고쳐야 하면 결함이다. 동기화마다 같은 파일이 + 충돌한다. 제품 소유 자리의 예: `src/bootstrap/product-composition.ts`, `src/contracts/product-contracts.ts`, + `config/ci/product-gates.json`. 효과는 다음 동기화 충돌 수로 잰다(1101 README 5절). P-39 +- **경계 예외는 실제 쓰임만큼만 연다.** 예외의 이유·담당·재검토 조건을 규칙의 `comment`에 적는다. kernel 폴더에는 공유 + 메커니즘만 둔다(03장 2절). P-40 +- **두 모듈이 이어지는 곳을 지나는 테스트를 둔다.** 모듈마다 단위 테스트가 있어도, 한쪽이 보내는 결과를 다른 쪽이 다른 + 뜻으로 받는 결함은 연결 지점에서만 보인다. P-41 + +## 9. 고칠 때 — 수정이 새로 가정하는 것 + +4라운드 새 발견 48건 중 22건의 원인이 지난 수정이었다(1105 README 4절 끝). 수정 커밋마다 다음을 본문 「위험·한계」에 +적는다. + +1. 이 변경이 새로 가정하는 상태(빈 제품 파일, CI env 없음, 객체 하나, 기능 0개 등). +2. 그 가정이 깨지는 지원 구성에서 한 번 돌렸는가(01장 2절 5단계). +3. 이 변경이 다른 검사를 약하게 했는가. 예: 경로를 백틱 밖으로 옮겨 문서 검사를 피한 수정이 그 경로를 검사 밖으로 + 냈다(1105/14-03). 위험을 커밋 본문에 적고도 테스트하지 않아 다운스트림 게이트가 항상 실패한 수정도 있다 + (1105/09-01, 수정 커밋 `235143c`). P-26 + +## 지금 이해하면 되는 것 + +- 판정 규칙은 한 곳, 표 밖은 안전한 쪽. 결과 불명 쓰기의 모든 재전송 입구를 함께 본다. +- 같은 사실은 원본에서 뽑거나 대조 테스트로 묶는다. 짝 백엔드 사실은 코드까지 따라간다. +- 수정은 새로 가정하는 것을 적고, 그 가정이 깨지는 구성에서 돌려 본다. -- 2.54.0 From 40e3b2f81463f6c3fab8d0a20e414da7daab5343 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:15:44 +0900 Subject: [PATCH 05/10] =?UTF-8?q?docs(improvement):=20=ED=85=8C=EC=8A=A4?= =?UTF-8?q?=ED=8A=B8=20=EA=B5=AC=EC=A1=B0=EC=99=80=20=EC=84=B1=EB=8A=A5=20?= =?UTF-8?q?=EC=B8=A1=EC=A0=95=EC=9D=98=20=EA=B0=9C=EC=84=A0=20=EA=B8=B0?= =?UTF-8?q?=EC=A4=80=EC=9D=84=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 테스트 결함(변이 생존, 템플릿 원래 상태만 봄, 브라우저 추정· 그리는 중인 화면에 기댐, 고정 경로·포트)이 라운드마다 반복됐다. 가끔 떨어지는 테스트를 "부하 탓"으로 닫았다가 테스트 결함으로 정정한 일이 두 번 있다. 성능 숫자는 측정 조건 없이 남아 비교할 수 없고, lab 게이트는 release 단계에만 있다. 고른 방법: 05장에 테스트 위치 기준(taxonomy 가리킴), 검출력 확인 (RED·변이·원래 상태 밖 입력·단언 범위), 환경 의존 표, flaky 금지와 조사 절차(반복 실행→실패 기록→결정적 재현→수정→변이), 실행 비용을 적는다. 06장에 세 측정 맥락, 언제 재나, 측정 조건 표, 예산 사이 균형, 숫자를 고칠 때를 적는다. 참조 기능과 함께 지워지는 기록 파일과 측정 스크립트는 이름을 쓰지 않고 그것을 소유한 문서 절을 가리킨다. 위험·한계: 실행 격리(빈 포트·실행별 출력)와 기능 라우트 첫 진입 측정은 [제안]이다. 실행 격리는 결정 대기(1105/12-04)다. 검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤. --- docs/improvement/05-test-structure.md | 140 ++++++++++++++++++++++++++ docs/improvement/06-performance.md | 96 ++++++++++++++++++ 2 files changed, 236 insertions(+) create mode 100644 docs/improvement/05-test-structure.md create mode 100644 docs/improvement/06-performance.md diff --git a/docs/improvement/05-test-structure.md b/docs/improvement/05-test-structure.md new file mode 100644 index 00000000..877dcc50 --- /dev/null +++ b/docs/improvement/05-test-structure.md @@ -0,0 +1,140 @@ +# 05. 테스트 구조 기준 + +## 핵심 + +테스트는 **결함을 막는지**로 평가한다. 테스트가 있다는 사실, 커버리지 숫자는 근거가 아니다. 이 repo의 테스트 결함은 +다섯 라운드 동안 같은 모양으로 반복됐다. + +```text +결함을 고쳐도·규칙을 지워도 통과한다 → 변이로 확인한다 (3절) +템플릿 원래 상태·작은 입력에서만 맞다 → 기능 추가·예제 제거·입력 3개 이상으로도 돈다 (3절) +속도·부하·브라우저 추정에 기댄다 → 결정적 재현으로 원인을 찾는다 (5절) +고정 경로·포트·로컬 생성물에 기댄다 → 깨끗한 clone·한 checkout 두 실행으로 확인한다 (4절) +``` + +## 1. 정본 + +| 무엇 | 정본 | +| --- | --- | +| 테스트 층, 명령, 실행 환경, 층을 정하는 기준 | `docs/testing/taxonomy.md` | +| 넓은 테스트 설계, flaky 정책, 금지 패턴 | `docs/testing/frontend-platform-testing-strategy.md` 16.5절(1183~1196줄), 19절(1399~1418줄). 목표 설계 문서라 지금 코드와 다른 곳이 있다(예: 15절 디렉터리 구조). 다르면 코드가 맞다 | +| Vitest 수집 범위, `.only` 금지, 전역 timeout | `vitest.config.ts` | +| Vitest 실행 runner(Node 버전, `NODE_ENV`, 생성물) | `scripts/run-vitest.ts` | +| skip·todo를 남긴 실행의 실패 | `scripts/lib/no-skipped-tests-reporter.ts` | +| Playwright skip·fixme의 quarantine 조건, `forbidOnly` | `scripts/check-test-evidence.ts` | +| 테스트 공통 대기 기한 | `tests/setup.ts` 5~13줄 | +| 모든 테스트 파일이 어떤 게이트에서 도는가 | `check:ci`, 예외 목록 `config/ci/ungated-tests.json` | +| 지워도 되는 문서를 테스트가 읽지 않는다 | `tests/unit/deletable-history-documents.test.ts` | + +## 2. 테스트를 어디에 둘까 + +`docs/testing/taxonomy.md` 85~99줄이 기준이다. **프레임워크가 아니라 필요한 실행 환경**이 층을 정한다. + +| 필요한 것 | 둘 곳 | 명령 | +| --- | --- | --- | +| 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//` | 기능 폴더와 함께 지워진다 | + +- 스크립트 테스트가 자식 프로세스를 띄우면 그 suite가 자기 timeout을 선언한다. 전역 timeout(`vitest.config.ts`의 + `testTimeout`)을 올리지 않는다(taxonomy 95~99줄). +- 플랫폼을 지키는 테스트는 참조 기능·스타터 화면에 묶지 않는다. 샘플을 지우면 그 테스트도 사라지거나 게이트가 깨진다. + 테스트 전용 라우트와 플랫폼 소유 MSW 카탈로그(`tests/mocks/`)를 쓴다(1101 README 14.1절 0929/10-02 행, 부록 P-20). +- 기능 테스트가 지워도 되는 문서를 읽으면 제거 드릴이 깨진다(03장 4절). + +## 3. 테스트가 결함을 막는지 확인하는 법 + +### 3.1 RED 먼저 + +동작을 바꾸는 수정은 재현 테스트가 먼저 실패하고, 고친 뒤 통과한다(`SPEC.md` 29줄). 커밋 본문에 RED와 GREEN을 +적는다(1101 README 349줄). 이 규칙을 강제하는 게이트는 없다. 리뷰가 커밋 본문으로 확인한다. + +### 3.2 변이로 검출력을 잰다 + +- 보호 규칙 한 줄을 지우거나 바꾸는 변이를 넣어, 그 규칙을 지키는 테스트가 실패하는지 본다. 결함 수정안을 넣었을 때 + 기존 테스트가 모두 통과하면 그 테스트는 결함을 막지 못했던 것이다(부록 P-13). +- 커버리지 100%인 곳에서도 판정 경계의 변이가 살아남았다(1103 README 5절 원인 5). 커버리지는 줄을 지나갔다는 뜻일 + 뿐이다. +- 변이 실험은 일괄 실행 목록으로 낸다. 리뷰어가 손으로 만들어 checkout 전체를 잠그며 돌리지 않는다(1105/10-03, + 09장 4절). + +### 3.3 템플릿 원래 상태 밖에서도 돈다 + +수정을 템플릿 원래 상태나 작은 입력으로만 확인하면 다운스트림에서 다시 결함이 된다. 4라운드 반복 원인 1번이다 +(1105 README 6절, 부록 P-02). + +| 확인할 상태 | 지난 예 | +| --- | --- | +| 기능을 하나 이상 더한 상태(`create:feature`) | 기능을 더하면 시각 테스트가 실패했다(1103/12-01) | +| 제품 확장 지점을 채운 상태 | 타입 검사 탐침이 제품 파일을 통째로 덮어써 제품 capability가 있는 복사본에서 FE-GATE-005가 항상 실패(1105/09-01) | +| 예제 기능을 지운 상태 | CHANGELOG 안내대로 예제를 지우면 문서 검사가 실패(1105/14-01) | +| 입력·객체가 셋 이상 | purge 수정 테스트가 객체 0~1개만 써서 3개 이상의 결함을 놓쳤다(1103/05-01 남은 부분) | +| 매뉴얼 예시 이름으로 만든 기능 | 템플릿 테스트의 글자가 제품 기능 이름과 부딪쳐 제거 드릴 실패(1105/16-04) | + +### 3.4 단언이 대상에 닿는가 + +- fixture가 비어 첫 줄에서 return하지 않는가. 전제(예: 포커스가 먼저 옮겨졌는가)를 함께 단언하는가. +- 실제 화면이 아니라 로딩 화면·오류 화면·fixture 자신을 검사하지 않는가. 접근성 e2e가 기능의 빈 목록이 아니라 오류 + 화면을 검사하고 "passed"로 적은 적이 있다(1103/11-01). 부록 P-15. + +## 4. 환경에 기대지 않는다 + +| 기대는 것 | 증상 | 기준 | +| --- | --- | --- | +| gitignore된 로컬 생성물 | 깨끗한 clone에서 실패 | 테스트가 필요한 생성물을 스스로 만든다. 한 파일 실행도 `scripts/run-vitest.ts`를 거친다(07장 1절) | +| 작성자 PC의 글꼴·CPU | 다른 호스트에서 시각·규모 테스트 실패 | 글꼴은 `fonts.conf`로 고정한다(1101 README 343줄). 규모 테스트는 CPU와 무관한 비교만 단언한다 | +| 바깥 env(빌드 식별값, `CI=true`) | 실제 CI에서만 실패 | 테스트가 띄우는 빌드·dev server의 env는 테스트가 정한다(1103/11-06·11-07·11-08, 07장 4절) | +| 고정 출력 경로·고정 포트 | 한 checkout에서 두 실행이 부딪힌다 | 실행별 출력 폴더와 빈 포트 [제안]. 실행 격리 방법은 결정 대기다(08장 5.1절 D6, 1105/12-04) | +| 호스트 권한(user namespace 등) | 사전 점검 PASS 뒤 원문 오류 | 사전 점검이 본 단계와 같은 방법으로 한 번 실행해 본다(07장 5절) | +| 옆 checkout(짝 백엔드) | 기계마다 결과가 다르다 | 없으면 "확인 못 함"으로 보고한다(07장 6절, 1105/12-02) | + +## 5. 가끔 떨어지는 테스트 + +### 5.1 금지 + +- 재시도, timeout 늘리기, worker 줄이기, `force` 클릭·합성 이벤트로 덮지 않는다(전략 16.5절, 19절. 1103/11-10 조사에서 + 버린 대안). +- skip은 Playwright spec에만, owner·defect·route·만료일이 있는 quarantine으로만 둔다(`scripts/check-test-evidence.ts`). + 빠른 계층에는 quarantine이 없다. 고치거나 느린 층으로 옮긴다(1101 README 441줄, 2026-11-03 결정). +- "부하 탓"으로 닫지 않는다. 부하를 낮춘 재현과 결정적 재현으로 확인하기 전에는 원인이 아니다. 1103 조치에서 부하 + 탓으로 적었던 두 실패는 모두 테스트 결함이었다(1103 README 14.7절 정정 두 줄). + +### 5.2 조사 절차 + +1. **반복 실행으로 빈도를 잰다.** 같은 조건에서 30회 같은 식으로 돌려 실패 수를 적는다(1103/11-10: 30회 두 번, 각각 + 60건 중 3건 실패). +2. **실패 기록을 남긴다.** 이벤트 순서(pointerdown·pointerup·click 대상), 위치, 시각, 네트워크 로그를 실패한 실행에서 + 모은다. 진단용 코드는 별도 브랜치에 둔다. +3. **결정적 재현을 만든다.** 원인이라고 본 조건을 강제로 만들어 매번 실패하게 한다. 예: mousedown 때 앱 높이를 늘리면 + 세 엔진 6/6 실패(1103/11-10). 모듈 응답을 3.5초 늦추면 WebKit 경고 2/2(1103/11-09). +4. **고친다.** 고친 뒤 결정적 재현이 통과하고, 실제 조건 반복 실행에서 실패 0인지 본다(1103/11-10: 660/660). +5. **검사가 약해지지 않았는지 변이로 본다.** 경고를 무시하게 고쳤으면, 원래 잡아야 할 것(예: 정말 안 쓴 preload)을 + 여전히 잡는지 변이로 확인한다(1103/11-09 수정, 1105 README 3.3절). + +### 5.3 브라우저 테스트에서 반복된 원인 + +| 원인 | 예 | 기준 | +| --- | --- | --- | +| 브라우저의 추정에 기댄다 | WebKit이 load 3초 뒤 한 번 하는 "preload를 안 썼다" 추정. 곧 쓰일 preload로 가끔 실패하고, 정말 안 쓴 preload는 놓쳤다(1103/11-09) | 브라우저 경고 대신 확인하려는 사실(preload가 평가됐는가)을 직접 검사한다. 부록 P-17 | +| 그리는 중인 화면을 누른다 | 앱 뒤에 붙인 버튼이 렌더링 중 12 px 밀려 클릭이 버튼에 닿지 않았다(1103/11-10) | 테스트가 붙이는 조작 요소는 앱 레이아웃과 무관한 고정 층에 둔다. "다 그려질 때까지 기다리기"는 신호가 없어 쓰지 않는다. 부록 P-18 | +| 짧은 상태를 폴링으로 잡는다 | 500 ms만 이어지는 `BLOCKED` 상태를 폴링으로 잡으려다 두 엔진에서 실패(1103/11-05) | 상태 변화를 이벤트·기록으로 받는다 | +| 고정 상한과 첫 실행 비용 | provider 테스트 10개가 10초 상한에 묶이고, 하나만 고르면 첫 테스트가 fixture 빌드를 떠안아 실패(1103/11-03) | 무거운 준비는 suite 준비 단계로 옮기고 suite가 자기 timeout을 선언한다 | + +## 6. 테스트 실행 비용 + +- 빠른 계층(`tests/unit`)에 프로세스를 띄우는 도구 테스트, 실제 시계로 기다리는 테스트가 섞이면 전체가 느려진다 + (1101/10-05~10-07, 부록 P-21). +- merge 단계가 같은 파일을 두 번 돌리지 않는지 본다(1101/10-06). +- 긴 드릴은 시간을 함께 적는다. FE-GATE-020은 1,150초 안팎, `test:feature-scaffold`만 513~866초다(1103 README 14.7절, + 1105 README 11.1절). 45분 job 상한과의 여유를 본다. + +## 지금 이해하면 되는 것 + +- 테스트 위치는 필요한 실행 환경으로 정한다(`taxonomy.md`). +- 검출력은 변이로, 범위는 템플릿 원래 상태 밖(기능 추가·예제 제거·입력 셋 이상)으로 확인한다. +- 가끔 떨어지는 테스트는 재시도·timeout으로 덮지 않는다. 반복 실행 → 실패 기록 → 결정적 재현 → 수정 → 변이 순서로 + 원인을 찾는다. diff --git a/docs/improvement/06-performance.md b/docs/improvement/06-performance.md new file mode 100644 index 00000000..65ac3320 --- /dev/null +++ b/docs/improvement/06-performance.md @@ -0,0 +1,96 @@ +# 06. 성능·최적화 기준 + +## 핵심 + +이 템플릿의 성능 목표는 **예산**이다. 요청량·데이터량 목표는 없다(1105 README 0절). 예산은 세 측정 맥락으로 나뉘고, +맥락마다 재는 곳과 막는 게이트가 다르다. + +```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~13줄이다. 이 장은 숫자를 다시 적지 않는다. **언제 재는지, 어떤 조건으로 재는지, 숫자를 고칠 때 무엇을 같이 +하는지**만 정한다. + +## 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`(5회, 포트 4173) | +| 템플릿 그대로의 초기 JS 기준선, 기능·context 하나당 증가량, 그 기록을 재는 테스트와 갱신 명령 | `docs/operations/performance-evidence.md` 「번들 예산의 기준선과 여유」 절. 기록 파일과 측정 스크립트는 참조 기능과 함께 지워지므로 이 매뉴얼은 이름을 쓰지 않고 그 절을 가리킨다(07장 6절) | +| 규모 설계와 예산의 근거 | `docs/architecture/scale-architecture.md` | +| 측정 결과에 붙일 정보의 일반론 | 가이드 14절 「측정 결과에 반드시 붙일 정보」 | + +## 2. 언제 재나 + +| 바꾼 것 | 잴 것 | +| --- | --- | +| 라우트 로딩, dynamic import, 초기 화면, 청크 나누기(`vite.config.ts`) | `check:bundle`과 `test:performance` 둘 다 | +| 의존성 추가·갱신 | `check:bundle`. 갱신 하나가 초기 JS를 약 7 KB 늘려 예산을 넘긴 예가 있다(1103/13-03, zod 4.6.x) | +| 기능 추가(`create:feature`) | 생성 명령의 `Next:` 안내대로 초기 JS 기록을 다시 쓰고 FE-GATE-005·012를 돌린다(1103 README 14.6절 #2) | +| 성능 최적화 작업 | 바꾸기 전·후를 같은 조건으로(3절) | + +lab 게이트는 release 단계에만 있다. merge 게이트만 돌리면 lab 회귀를 모른다. 예제 화면 진입 회귀가 147커밋 동안 아무 +게이트에도 걸리지 않았다(1103/15-01). 라우트 로딩을 건드린 커밋은 merge 게이트에 더해 `test:performance`를 돌린다 +(07장 2절). + +## 3. 측정 조건 + +측정값에는 아래를 함께 적는다. 하나라도 빠지면 다른 측정과 비교하지 않는다(가이드 14절). + +| 항목 | 이 repo에서 | +| --- | --- | +| 위치 | desktop(07장 7절). 노트북 측정은 비교에 쓰지 않는다 | +| 하드웨어·런타임 | CPU 모델·논리 코어 수·Node 버전. lab 결과 JSON이 자동으로 담는다 | +| 부하 | 측정 앞뒤의 load average. lab 결과 JSON이 담는다. 다른 무거운 실행과 겹치지 않게 잠금 아래에서 잰다 | +| 브라우저와 조건 | lab: Chromium, 1280×720, `contract-fast-4g`, CPU 4배 감속, 빈 캐시·새 browser context(`scripts/test-performance.ts` 211~221줄) | +| 반복과 통계 | 기본 5회의 중앙값으로 판정한다. 표본 전부와 퍼짐을 함께 적는다(같은 파일 226~231줄). 예: "중앙값 227 ms(표본 223·224·227·438·526)"(1103/15-01) | +| 빌드 | 커밋과 build id. 비교하는 두 빌드는 같은 env로 만든다. 커밋 ID가 빌드에 박혀 초기 JS가 몇 바이트 달라진다(1103 README 14.5절 10회차) | +| 대조군 | 바꾸기 전 커밋을 같은 세션·같은 조건에서 함께 잰다. 지난 측정값을 대조군으로 쓰지 않는다 | +| 규모 | 기능 수에 따른 비용은 참조 기능을 복제한 실제 모양 기능 25개·100개로 재고 호스트 부하를 함께 적는다(`SPEC.md` D-18) | + +## 4. 예산 사이의 균형 + +- **초기 JS bytes와 초기 파일 수는 함께 본다.** bytes를 줄이려고 청크를 나누면 파일 수가 는다. HTTP/1.1에서는 요청이 + 줄을 서서 첫 화면이 늦어진다. 파일 수 상한은 HTTP/2 호스팅을 전제로 정했다(`docs/operations/performance-evidence.md` + 「초기 청크 수와 HTTP/1.1」, 1103 README 14.6절 #4). +- **청크 이름으로 크기를 판단하지 않는다.** 공용 청크는 안에 든 모듈 하나의 이름을 받는다. 출처별 크기는 + sourcemap으로 나눠 잰다(같은 문서 「번들 예산의 기준선과 여유」). +- **재방문 비용도 본다.** release마다 이름이 바뀌는 청크에 큰 라이브러리가 들어가면 코드가 같아도 다시 받는다(같은 문서 + 「build id와 재방문 캐시」). +- **여유를 적는다.** 예산에서 기준선을 뺀 여유와, 기능 하나가 쓰는 양을 함께 보고한다. 1103 조치 끝에 초기 JS 여유가 + 쓰기 기능 하나 남짓이었다(1103 README 14.5절 끝 문단, 14.7절). + +## 5. 숫자를 고칠 때 + +- **기준선 기록**은 손으로 고치지 않는다. 측정 스크립트를 `--initial-baseline --write`로 돌리고 같은 변경에 넣는다 + (`docs/operations/performance-evidence.md` 35~36줄). 손으로 적은 숫자는 두 번 낡았다(같은 문서 22줄). +- **대조 허용치는 남은 여유보다 작아야 한다.** 기록 대조 허용 1%(약 2 KB)가 남은 여유(1,873 B)보다 커서 여유를 다 쓰는 + 변경이 통과할 수 있다(1105/15-02). 허용치를 정할 때 여유·측정 오차와 비교한다. 부록 P-46. +- **예산 값**(`config/performance/budgets.json`)을 올리는 것은 결정이다. 이유·대안·재검토 조건을 08장 형식으로 남긴다. + 예: 초기 파일 수 상한을 26에서 32로 올린 것(1103 README 14.6절 #4). +- **문서에 측정값을 적을 때**는 커밋과 측정일을 붙인다. 그 숫자가 지금 빌드와 다를 수 있다고 적는다. + +## 6. 성능 쪽 반복 결함 + +| 패턴 | 막는 기준 | +| --- | --- | +| release 단계에만 있는 게이트의 회귀를 아무도 모른다(1101/15-01, 1103/15-01) | 2절: 라우트 로딩을 건드리면 `test:performance`도 돌린다 | +| 실패 메시지가 무엇을 얼마나 넘었는지 말하지 않는다(1103/15-03) | 예산 검사는 넘은 항목·잰 값·초과량을 모두 출력한다(`docs/operations/performance-evidence.md` 5~7줄) | +| 측정 조건 없이 숫자만 남아 비교할 수 없다 | 3절 표 | +| lab이 화면 하나·조건 하나만 잰다. 기능 라우트 첫 진입(약 400 ms), `/` 밖 화면의 layout shift, 스크롤바가 보이는 환경을 어느 게이트도 재지 않는다(1105/15-04, 15-01, 15-05, 모두 미조치) | 기능 라우트 로딩을 바꾸면 그 라우트 첫 진입을 lab과 같은 조건으로 따로 재고 결과에 적는다 **[제안]** | +| 부하가 높은 시간대의 실패를 "부하 탓"으로 닫는다. 두 번 다 원인은 테스트에 있었다(1103/11-09, 11-10) | 05장 5절: 부하를 낮춘 재현과 결정적 재현으로 확인한 뒤에만 부하를 원인으로 쓴다 | + +전체 목록은 부록의 「성능」 행이다. + +## 지금 이해하면 되는 것 + +- 예산 숫자는 `config/performance/budgets.json`, 맥락별 계약은 `performance-evidence.md`가 정본이다. +- 라우트 로딩을 건드리면 merge 게이트에 더해 lab 게이트도 돌린다. +- 측정값에는 위치·부하·반복 수·빌드·대조군을 붙인다. 붙이지 않은 숫자는 비교하지 않는다. -- 2.54.0 From 402fe122318d8f84f848b0836e74b0ebf70352c2 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:15:44 +0900 Subject: [PATCH 06/10] =?UTF-8?q?docs(improvement):=20=EA=B2=80=EC=A6=9D?= =?UTF-8?q?=20=EC=9C=84=EC=B9=98=C2=B7merge=20=ED=8C=90=EC=A0=95=20?= =?UTF-8?q?=EB=B0=A9=EB=B2=95=EA=B3=BC=20=EA=B2=B0=EC=A0=95=20=EC=83=89?= =?UTF-8?q?=EC=9D=B8=EC=9D=84=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: "merge 가능" 판정을 고른 스크립트 목록이나 CI=true 없는 env로 해서 실제 러너에서 항상 실패하는 게이트를 놓친 적이 있다. 테스트를 어디서 돌리는지(desktop, 잠금, 되돌림)는 사용자 지시로만 있다. 소유자 결정이 리뷰 README·SPEC.md·ADR·세션 기록에 흩어져 다시 묻게 된다. 고른 방법: 07장에 때별로 돌릴 것, ci:gate로 merge 단계 14개를 workflow env로 돌리는 방법, 가끔 떨어지는 게이트의 기록법, desktop의 FE-GATE-013 처리, CI env에서만 나는 실패, PASS 뒤 실패, 문서 검사의 범위와 도는 곳, 소유자 환경을 적는다. 08장에 결정을 적는 곳, 다시 묻지 않는 규칙, 작업 방식 결정 O-1~O-14와 기술 결정 묶음의 색인, 결정 대기 형식과 지금 열린 D1~D6, 커밋·PR에서 이 repo가 덧붙이는 것을 적는다. 결정 원문은 옮기지 않는다. 위험·한계: 열린 결정 표는 4라운드 시점이다. 다음 라운드가 닫으면 고쳐야 한다. CLAUDE.md 27줄의 리뷰 게이트 목록이 merge 단계와 다르다는 발견(1105/12-03)은 고치지 않고 07장이 merge 단계를 함께 돌리라고만 적는다. 검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤. --- docs/improvement/07-verification-gates.md | 177 ++++++++++++++++++++++ docs/improvement/08-decisions-records.md | 123 +++++++++++++++ 2 files changed, 300 insertions(+) create mode 100644 docs/improvement/07-verification-gates.md create mode 100644 docs/improvement/08-decisions-records.md diff --git a/docs/improvement/07-verification-gates.md b/docs/improvement/07-verification-gates.md new file mode 100644 index 00000000..0e2ed20a --- /dev/null +++ b/docs/improvement/07-verification-gates.md @@ -0,0 +1,177 @@ +# 07. 검증과 게이트 + +## 핵심 + +무엇을 돌릴지는 **언제인지**로 정한다. 작업 중에는 바뀐 테스트 파일만, 커밋 전에는 빠른 게이트 8개, 통합 때는 +5개를 더, merge 가능을 말할 때는 merge 단계 14개를 CI와 같은 env로 돌린다. + +```text +작업 중 바뀐 테스트 파일 하나 (1절) +커밋 전 빠른 게이트 8개 (2절, SPEC.md 31줄) +레인 끝·통합 + 5개 (2절, SPEC.md 32줄) +merge 판정 ci:gate로 merge 단계 14개, workflow env (3절) +리뷰 시작 CLAUDE.md 목록 11개 + merge 단계 14개 (3절) +``` + +게이트 ID·단계·명령의 정본은 `config/ci/gates.json`이다. 이 장은 그 목록을 다시 적지 않는다. + +## 1. 명령 규칙 + +- 패키지 스크립트는 `corepack pnpm