문제: 매뉴얼은 백엔드와 종료 조건이 다르다는 것만 적고 무엇이 다른지 적지 않았다. 프론트는 멈출 조건을 채운 라운드의 Medium·Low를 고치고 멈추므로 그 마지막 수정은 확인 리뷰를 받지 않는데, 이 위험이 문서에 없다. 2026-11-05 사용자 지시 두 가지(수정 결과의 "고침"을 다음 리뷰에서 ID별로 재판정, 큰 라운드는 작은 PR로 나누고 소유자가 직접 merge)도 빠져 있다. 고른 방법: 09장 5.2절에 차이(마지막 수정의 확인 리뷰 여부)와, 그래서 마지막 수정도 01장 절차와 merge 판정을 그대로 거친다는 점을 적는다. 5.3절에 "고침은 확정이 아니다", 6절에 PR 크기 규칙(커밋 규칙 5.1절)을 더한다. 08장 결정 색인 O-12를 2026-11-05 소유자 결정 「각자 유지」 문장으로 바꾸고 O-15·O-16을 더한다. README M-7도 맞춘다. 위험·한계: 종료 조건을 통일할지는 정하지 않았다. 소유자 결정대로 각자 유지한다. 검증: 로컬 정적 대조. desktop 검사는 이 커밋을 보내 돌린다.
14 KiB
개선 작업 매뉴얼 — 이 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를 고치고 멈춘다.