Files
clean-architecture-backend-…/docs/improvement
DongHyeonka 3b66358e52 docs(improvement): 리뷰·개선 작업 매뉴얼을 만든다
문제: 이 repo를 리뷰하거나 결함 수정·리팩터링·성능 최적화·구조 변경을 할 때
기준으로 삼을 문서가 없다. docs/manual/은 새 기능을 만드는 순서이고, 리뷰
기준으로 써 온 공용 가이드는 프론트 repo에만 있으며 AGENTS.md·CLAUDE.md가
가리키지 않는다. 2026-11-01부터 쌓인 소유자 결정과 반복 결함 패턴은 리뷰
문서 여러 곳에 흩어져 있다.

방법: docs/improvement/에 README, 01~09장, 결함 패턴 부록을 둔다. 규칙은
다시 쓰지 않고 정본(AGENTS.md, modules.json, application-core/CLAUDE.md,
TESTING_STRATEGY.md, src/build.gradle, 리뷰 문서의 결정 절)을 가리킨다.
정본이 없는 것 — 작업 종류별 절차, 이 repo의 28개 관점 점검 항목과 결함
정의, 반복 결함 패턴, 성능 측정 조건, 무거운 실행 위치, 결정 색인, 세션
분업과 리뷰 반복 종료 조건 — 만 매뉴얼이 정본이 된다. AGENTS.md에
「리뷰·개선 작업 기준」 절, CLAUDE.md에 그 요약을 두고 docs/README.md와
docs/manual/README.md에서 가리킨다. 프론트 매뉴얼과 같은 장 번호를 쓴다.
버린 대안: docs/reviews/ 안에 두기(결과 보관소와 기준서가 섞인다), 공용
가이드 복사(갈라진 복사본이 된다), 소유자 환경 규칙을 AGENTS.md에 직접
쓰기(파생 프로젝트가 정책 문서를 고쳐야 한다).

위험·한계: 매뉴얼을 정본과 대조하는 자동 검사는 없다(문서 파서를 두지
않는 repo 방침). 08장 결정 표는 색인이고 원문과 다르면 원문이 맞다. 저장소
밖 문서(공용 가이드, 커밋 규칙)는 lychee가 따라갈 수 없어 링크 대신 코드
표기로 썼다. 근거를 찾지 못한 것 하나(측정 스크립트를 scripts/perf/로
넣기)는 [제안]으로 표시했다.

검증: 인용한 저장소 경로·리뷰 ID·클래스 이름·태스크 이름·상대 링크·절
번호를 스크립트로 전수 대조했다(로컬, 읽기만). 남은 불일치는 저장소 밖
가이드 경로, 자리표시자, 제안 경로, 원래 있던 문장뿐이다. CLAUDE.md는
DeveloperExperienceContractTest가 요구하는 architectureTest 명령을 그대로
둔다. 문서 대조 lane은 이 커밋을 push한 뒤 desktop에서 돌린다.
2026-11-05 21:59:44 +09:00
..

개선 작업 매뉴얼 — 이 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다.

공용 리뷰 가이드와의 관계

지금까지 리뷰 기준으로 쓴 가이드는 프론트 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-01 docs/reviews/2026-11-01-maturity-review/의 발견 05-01. 1101 README는 그 폴더의 README.md, 1101/09-performance-measurement.md는 그 폴더의 파일
    1103/RR6-01-05 docs/reviews/2026-11-03-rereview/의 발견. RR-*(1차 재리뷰), RR2-*RR6-*(round2round6). 1103 README, 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-docs repo)의 N절
  • 이 repo에서 근거를 찾지 못한 기준은 **[제안]**으로 표시했다. 제안은 소유자가 받기 전까지 규칙이 아니다.

결정 기록

이 매뉴얼을 만들며 정한 것이다. 소유자가 뒤집을 수 있다.

# 결정 이유 버린 대안
M-1 위치는 docs/improvement/ 독자가 docs/manual/(새 기능 작성자)과 다르다. docs/reviews/는 리뷰 결과 보관소라, 기준서를 섞으면 어느 문서가 현재 기준인지 흐려진다 docs/reviews/ 안에 두기, docs/manual/ 뒤에 장 추가
M-2 장 구성은 총괄 세션이 준 뼈대 그대로 프론트 매뉴얼과 장 번호를 맞추기 위해서다 07·09 합치기
M-3 심각도 체계를 용도로 나눈다. 전체 리뷰는 가이드 35.2(CriticalLow)+35.3(P0P3), 확인 리뷰는 Critical/Important/Minor(02장 3절) 두 체계 모두 이력에 있다(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.md 2·8절, AGENTS.md 「Gradle 정책 권위」).
  • 상대 링크는 lychee가 검사한다(.github/workflows/link-check.yml의 docs/**/*.md).
  • 리뷰 라운드에서 새 반복 패턴이 나오면 부록에 행을 더하고, 막는 기준이 생기면 04·05·07장에 넣는다.
  • 새 소유자 결정이 생기면 08장 색인에 한 줄을 더한다.

지금 이해하면 되는 것

  • 새 기능은 docs/manual/, 이미 있는 코드를 평가·수정하는 일은 이 매뉴얼.
  • 규칙의 정본은 AGENTS.md·registry·leaf CLAUDE.md다. 이 매뉴얼은 가리키고, 절차·점검 항목·패턴·기록법만 소유한다.
  • 리뷰 → 수정 → 확인 리뷰를 발견이 0이 될 때까지 돈다.