# 개선 작업 매뉴얼 — 이 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까지 확인 리뷰"를 쓴다. 차이는 마지막 라운드의 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를 고치고 멈춘다.