문제: 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
개선 작업 매뉴얼 — 이 repo를 리뷰·수정·리팩터링·최적화할 때의 기준
핵심
이 매뉴얼은 이미 있는 코드를 평가하거나 고치는 사람이 읽는다. 사람과 AI 에이전트가 같은 기준을 쓴다.
새 기능을 만드는 순서는 docs/manual/이 맡는다. 두 매뉴얼은 독자가 다르다.
개선 작업 하나는 다음 흐름을 탄다. 괄호 안 숫자는 이 매뉴얼의 장이다.
리뷰(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/ |
| 운영 장애 대응 | 아님 | 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 | 어떤 작업이든 시작할 때. 시작 조건·단계·산출물·완료 기준 |
| 02 리뷰 기준 | 02-review-criteria.md | 리뷰하거나 리뷰 결과를 읽을 때 |
| 03 폴더·모듈 구조 기준 | 03-folder-module-structure.md | src/ 폴더·adapter 그룹·기능 폴더·문서 위치를 바꿀 때 |
| 04 코드 구조 기준 | 04-code-structure.md | 결함을 고치거나 리팩터링할 때 |
| 05 테스트 구조 기준 | 05-test-structure.md | 테스트를 쓰거나 옮기거나, 가끔 떨어지는 테스트를 조사할 때 |
| 06 성능·최적화 기준 | 06-performance.md | 성능을 재거나 고칠 때 |
| 07 검증과 게이트 | 07-verification-gates.md | 무엇을 언제 어디서 돌릴지, merge 가능을 어떻게 판정할지 정할 때 |
| 08 결정과 기록 | 08-decisions-records.md | 결정이 필요해 보일 때, 커밋·PR을 쓸 때 |
| 09 작업 진행 방식 | 09-working-method.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-01docs/reviews/2026-09-25-maturity-review/의 발견 03-010929/03-03docs/reviews/2026-09-29-maturity-review/의 발견1101/12-04docs/reviews/2026-11-01-maturity-review/의 발견. 「1101 README」는 그 폴더의README.md1103/11-07docs/reviews/2026-11-03-maturity-review/의 발견1105/12-044라운드 리뷰(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 |
이 repo의 다섯 라운드가 모두 이 체계로 적혔다. 백엔드는 확인 리뷰에 Critical/Important/Minor를 더 쓰지만, 이 repo에는 그 이력이 없다. 소유자 지시의 "Minor"는 Low로 읽는다(09장 5절) | 백엔드처럼 두 체계 |
| M-6 | 08장의 결정 표는 색인이다. 한 줄 요약과 출처만 둔다 | 결정 원문을 옮겨 쓰면 갈라진 복사본이 된다(부록 P-14) | 결정 원문 이동 |
| M-7 | 반복 종료 조건은 소유자 문장 그대로 쓴다(09장 5.2절) | 2026-11-04 사용자 결정의 문장이다. 백엔드는 "발견 0까지 확인 리뷰"를 쓴다. 차이는 마지막 라운드의 Medium·Low 수정이 확인 리뷰를 받는가다(프론트는 받지 않는다). 2026-11-05 소유자 결정 「각자 유지」가 두 기준을 각자 유지하게 정했다(08장 표 O-12) | 백엔드 문장으로 통일 |
| 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를 고치고 멈춘다.