문제: README가 두 매뉴얼에서 다른 것은 종료 조건 하나라고만 적었다. 프론트 매뉴얼 세션이 알려 온 것을 보면 장 번호와 파일 이름은 같지만, 「소유자 환경」 절 번호, 심각도 체계, 부록 패턴 ID가 다르다. 두 repo를 같은 번호로 비교하는 사람이 절 번호를 그대로 옮기면 엉뚱한 절을 찾는다. 방법: "소유자가 의도적으로 다르게 둔 것"은 종료 조건 하나로 남기고, repo 이력 때문에 다른 세 가지를 표로 적는다. 비교할 때는 장 번호로 찾고 절 번호와 패턴 ID는 각 매뉴얼에서 다시 찾으라고 적는다. 검증: 인용·링크 대조 스크립트를 다시 돌렸다(새 불일치 없음).
개선 작업 매뉴얼 — 이 repo를 리뷰·수정·리팩터링·최적화할 때의 기준
핵심
이 매뉴얼은 이미 있는 코드를 평가하거나 고치는 사람이 읽는다. 사람과 AI 에이전트가 같은 기준을 쓴다.
새 업무 기능을 만드는 순서는 docs/manual/이 맡는다. 두 매뉴얼은 독자가 다르다.
개선 작업 하나는 다음 흐름을 탄다. 각 칸의 숫자는 이 매뉴얼의 장이다.
리뷰(02) ──> 결함 목록 ──> 수정 묶음(01·03·04·05·06) ──> 검증(07)
^ |
| v
└──── 확인 리뷰: 수정 diff만 본다(02) <──── 발견이 남았나?(09)
| 0이면
v
결정·결과 기록(08) ──> 보고
- 리뷰는 결함을 찾고 적는다. 코드를 고치지 않는다.
- 수정 묶음은 결함을 테스트로 먼저 재현하고(RED) 고친다(GREEN).
- 확인 리뷰는 수정이 만든 새 결함을 찾는다. 지난 라운드의 반복 결함 대부분이 여기서 나왔다(부록 A12).
- 발견이 심각도와 상관없이 0이 될 때까지 반복한다(09장).
적용 범위
| 작업 | 이 매뉴얼 | 다른 문서 |
|---|---|---|
| 리뷰(전체·영역·커밋 diff) | 01장 1절, 02장 | 공용 가이드(아래) |
| 결함 수정 | 01장 2절, 04·05장 | 해당 leaf src/**/CLAUDE.md |
| 리팩터링(동작을 바꾸지 않는 구조 변경) | 01장 3절, 04장 | |
| 성능 최적화 | 01장 4절, 06장 | |
| 폴더·모듈 구조 변경 | 01장 5절, 03장 | src/config/architecture/modules.json |
| 테스트 구조 개선 | 01장 6절, 05장 | docs/testing/TESTING_STRATEGY.md |
| 새 업무 기능 추가 | 아님 | docs/manual/ |
| 운영 장애 대응 | 아님 | docs/runbooks/ |
정본 표
이 매뉴얼은 규칙을 다시 쓰지 않고 정본을 가리킨다. 매뉴얼과 정본이 다르면 정본이 맞고, 매뉴얼을 고친다. 아래 「이 매뉴얼이 정본」 행만 이 매뉴얼이 처음이자 유일한 기록이다.
| 무엇 | 정본 | 이 매뉴얼에서 |
|---|---|---|
| HARD-STOP 7개, 계층 책임, 금지된 지름길 | AGENTS.md(요약 CLAUDE.md) |
04장이 가리킴 |
테스트 작성 규칙 6개(이름·@DisplayName·GWT·단언·fake) |
AGENTS.md 「테스트 전략」 |
05장이 가리킴 |
| capability 완료 기준 7개 | AGENTS.md 「부가 기능(capability) 모듈 규칙」 |
03·04장이 가리킴 |
| leaf 목록·허용 의존 | src/config/architecture/modules.json |
03장이 가리킴 |
| 이름 규칙, 템플릿 패키지 목록 | src/application-core/CLAUDE.md 「Naming convention」「Package ownership」 |
03·04장이 가리킴 |
| 테스트 분류 5개, 배치, source set | docs/testing/TESTING_STRATEGY.md, 기계 기준 TestLaneCategory |
05장이 가리킴 |
게이트 구성(ci·mainCheck·integrationCheck…) |
src/build.gradle 라이프사이클, .github/workflows/ |
07장이 언제 무엇을 돌리는지 정함 |
| strict lane 단계 검사 | src/build-logic/(StrictLaneStagesPlugin), AGENTS.md 「Gradle 정책 권위」 |
07장이 가리킴 |
| HTTP wire 계약 | docs/web/http-contract.md |
04장이 가리킴 |
| 새 기능 만드는 순서 | docs/manual/ |
가리킴 |
| 커밋·PR 형식 | design-docs/conventions/commit-and-pr.md(저장소 밖) |
08장이 이 repo 예외를 덧붙임 |
| 28개 관점의 일반 설명, 판정 체계(심각도·통제·증거) | 공용 가이드(저장소 밖, 아래) | 02장이 이 repo에 맞춤 |
| 소유자 결정 원문 | 각 리뷰 문서의 결정 절, docs/reviews/2026-09-25-review-followup-status.md 「소유자 결정」 |
08장은 색인 |
| 이 매뉴얼이 정본 | 작업 종류별 절차(01), 이 repo의 리뷰 점검 항목·결함 정의·리뷰 문서 형식(02), 반복 결함 패턴과 막는 기준(04·부록), 성능 측정 조건(06), 무거운 실행 위치(07 「소유자 환경」), 결정을 다시 묻지 않는 규칙·결정 기록법(08), 세션 분업·brief·리뷰 반복 종료 조건(09) |
읽는 순서
처음이면 이 README → 01 → 09 → 08을 읽는다. 그다음은 맡은 작업의 장만 읽는다.
| 장 | 파일 | 언제 읽나 |
|---|---|---|
| 01 작업 종류별 절차 | 01-procedures.md | 어떤 작업이든 시작할 때. 시작 조건·단계·산출물·완료 기준 |
| 02 리뷰 기준 | 02-review-criteria.md | 리뷰하거나 리뷰 결과를 읽을 때 |
| 03 폴더·모듈 구조 기준 | 03-folder-module-structure.md | leaf·패키지·source set·문서 위치를 바꿀 때 |
| 04 코드 구조 기준 | 04-code-structure.md | 결함을 고치거나 리팩터링할 때 |
| 05 테스트 구조 기준 | 05-test-structure.md | 테스트를 쓰거나 옮기거나 RED를 확인할 때 |
| 06 성능·최적화 기준 | 06-performance.md | 성능을 재거나 고칠 때 |
| 07 검증과 게이트 | 07-verification-gates.md | 무엇을 언제 어디서 돌릴지 정할 때 |
| 08 결정과 기록 | 08-decisions-records.md | 결정이 필요해 보일 때, 커밋·PR을 쓸 때 |
| 09 작업 진행 방식 | 09-working-method.md | 여러 세션으로 나눠 일할 때, 반복을 멈출지 정할 때 |
| 부록 결함 패턴 카탈로그 | appendix-defect-patterns.md | 리뷰 전 훑어볼 목록이 필요할 때 |
프론트 매뉴얼과 같은 뼈대
짝 프론트 템플릿(clean-architecture-frontend-template)도 같은 장 번호로 개선 매뉴얼을 만든다. 장 번호가 같으면
"두 repo의 05장"처럼 같은 주제를 바로 비교할 수 있다. 이 repo는 장을 합치거나 더하지 않았다. 부록 파일 이름은
appendix-defect-patterns.md다.
두 매뉴얼에서 소유자가 의도적으로 다르게 둔 것은 리뷰 반복의 종료 조건 하나다. 소유자가 "각자 유지"로 정했다(08장 1절 「두 repo의 종료 조건」). 백엔드는 발견이 0이 될 때까지 반복하고(09장 5절), 프론트는 자기 매뉴얼의 조건을 따른다.
장 번호와 파일 이름은 같지만, 각 repo의 이력 때문에 장 안에서 다른 것이 있다(2026-11-05 프론트 매뉴얼 세션 확인):
| 무엇 | 백엔드 | 프론트 |
|---|---|---|
| 「소유자 환경」 절 | 07장 6절, 09장 6절 | 07장 7절, 09장 7절 |
| 심각도 체계 | 전체 리뷰와 확인 리뷰에 따라 둘(결정 M-3) | 가이드 35.2+35.3 하나. 확인 리뷰용 Critical/Important/Minor 이력이 없다 |
| 부록 패턴 ID | A1~ |
P-NN |
두 repo의 장을 비교할 때는 장 번호로 찾고, 절 번호와 패턴 ID는 각 매뉴얼에서 다시 찾는다.
공용 리뷰 가이드와의 관계
지금까지 리뷰 기준으로 쓴 가이드는 프론트 repo의 docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md다.
Backend·Frontend·Platform 공용 일반론이고, 예시는 이 템플릿의 코드가 아니다. 2026-11-01 백엔드 성숙도 리뷰도
이 가이드의 31절 Backend 시나리오를 기준으로 했다(docs/reviews/2026-11-01-maturity-review/README.md 머리말).
- 이 매뉴얼은 가이드를 복사하지 않는다. 가이드의 절 번호(예: 「가이드 35.5」)로 가리킨다.
- 02장은 가이드의 28개 관점과 판정 체계를 이 repo의 경로·명령·지난 결함으로 바꿔 적는다. 일반 설명이 더 필요하면 가이드를 읽는다.
- 가이드는 저장소 밖에 있어 링크 검사(
.github/workflows/link-check.yml, lychee)가 따라갈 수 없다. 그래서 경로를 링크가 아니라 코드 표기로 쓴다. - 이 repo에서 파생한 서비스에는 프론트 repo가 없을 수 있다. 02장은 가이드 없이도 판정할 수 있게 썼다.
근거 표기
-
경로는 저장소 루트 기준이다. 코드 근거는
file:line, 문서 근거는 「문서 N절」로 적는다. -
file:line은 링크로 쓰지 않는다. lychee가path:42를 없는 파일로 본다. -
리뷰 ID는 가이드 36.3의 라운드 밖 표기
MMDD/ID를 쓴다. 같은 접두어를 그 폴더의 파일에도 쓴다. 이 매뉴얼에서 쓰는 줄임말:줄임말 뜻 1101/05-01docs/reviews/2026-11-01-maturity-review/의 발견 05-01.1101README는 그 폴더의README.md,1101/09-performance-measurement.md는 그 폴더의 파일1103/RR6-01-05docs/reviews/2026-11-03-rereview/의 발견.RR-*(1차 재리뷰),RR2-*round6).RR6-*(round21103README,1103/round6/01-core-inbound.md도 같은 방식「결정 N」 docs/reviews/2026-09-25-review-followup-status.md「소유자 결정」의 N번「가이드 N절」 공용 리뷰 가이드(프론트 repo docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md)의 N절「커밋 규칙 N」 design-docs/conventions/commit-and-pr.md(이 repo 옆design-docsrepo)의 N절 -
이 repo에서 근거를 찾지 못한 기준은 **[제안]**으로 표시했다. 제안은 소유자가 받기 전까지 규칙이 아니다.
결정 기록
이 매뉴얼을 만들며 정한 것이다. 소유자가 뒤집을 수 있다.
| # | 결정 | 이유 | 버린 대안 |
|---|---|---|---|
| M-1 | 위치는 docs/improvement/ |
독자가 docs/manual/(새 기능 작성자)과 다르다. docs/reviews/는 리뷰 결과 보관소라, 기준서를 섞으면 어느 문서가 현재 기준인지 흐려진다 |
docs/reviews/ 안에 두기, docs/manual/ 뒤에 장 추가 |
| M-2 | 장 구성은 총괄 세션이 준 뼈대 그대로 | 프론트 매뉴얼과 장 번호를 맞추기 위해서다 | 07·09 합치기 |
| M-3 | 심각도 체계를 용도로 나눈다. 전체 리뷰는 가이드 35.2(Critical |
두 체계 모두 이력에 있다(1101 전체 리뷰, 1103 확인 리뷰). 전체 리뷰는 지난 결과·프론트와 비교해야 하고, 확인 리뷰는 superpowers:requesting-code-review 템플릿이 쓰는 체계다. 어느 쪽이든 모든 발견을 고치므로 심각도는 순서와 재확인 범위만 정한다 |
하나로 통일(지난 문서와 비교가 끊긴다) |
| M-4 | 08장의 결정 표는 색인이다. 한 줄 요약과 출처만 둔다 | 결정 원문을 옮겨 쓰면 갈라진 복사본이 된다(부록 A1) | 결정 원문 이동 |
| M-5 | 저장소 밖 문서(공용 가이드, 커밋 규칙)는 링크 대신 코드 표기 | lychee 링크 검사가 저장소 밖을 못 따라간다 | 상대 링크 |
| M-6 | 소유자 환경에 묶인 규칙(desktop 실행, 세션 도구)은 07·09장의 「소유자 환경」 절에만 둔다 | 파생 프로젝트가 그 절만 바꾸면 되게 하려는 것이다 | AGENTS.md에 직접 쓰기 |
| M-7 | AGENTS.md의 commit 정책 human-only는 바꾸지 않는다. 소유자가 브랜치를 지정해 허용한 예외를 08장에 적는다 |
commit 정책은 소유자만 바꿀 수 있다 | 정책 문장 수정 |
| M-8 | 결함이 아닌 "개선 제안"도 열린 채 두지 않는다. 받아서 고치거나, 받지 않는 이유를 결정으로 남긴다 | 소유자 규칙 "보고할 때 남은 문제가 없어야 한다"(1103 README 16절)를 결함이 아닌 항목에도 적용한 것이다 |
제안은 기록만 |
| M-9 | 총괄+하위 세션 분업과 "Minor도 고친다"는 2026-11-05 총괄 세션 brief로 받은 소유자 규칙이다. 이 매뉴얼(09장)이 그 규칙의 저장소 안 정본이 된다 | 규칙이 세션 기록에만 있었다 |
이 매뉴얼을 고칠 때
- 정본이 바뀌면 이 매뉴얼의 해당 문장을 고친다. 이 매뉴얼을 정본과 대조하는 자동 검사는 없다. 이 repo는 문서를
파싱해 대조하는 검사를 일부러 두지 않는다(
docs/testing/TESTING_STRATEGY.md2·8절,AGENTS.md「Gradle 정책 권위」). - 상대 링크는 lychee가 검사한다(
.github/workflows/link-check.yml의docs/**/*.md). - 리뷰 라운드에서 새 반복 패턴이 나오면 부록에 행을 더하고, 막는 기준이 생기면 04·05·07장에 넣는다.
- 새 소유자 결정이 생기면 08장 색인에 한 줄을 더한다.
지금 이해하면 되는 것
- 새 기능은
docs/manual/, 이미 있는 코드를 평가·수정하는 일은 이 매뉴얼. - 규칙의 정본은
AGENTS.md·registry·leafCLAUDE.md다. 이 매뉴얼은 가리키고, 절차·점검 항목·패턴·기록법만 소유한다. - 리뷰 → 수정 → 확인 리뷰를 발견이 0이 될 때까지 돈다.