Files
clean-architecture-backend-…/CLAUDE.md
T
DongHyeonka 63c63413d1 docs(work): 지도와 작업 종류별 playbook으로 작업 매뉴얼을 만든다
문제: 이 repo의 진입 문서는 아키텍처 규칙을 길게 다시 쓴 CLAUDE.md(183줄)와
리뷰·수정만 다루는 옛 개선 매뉴얼(진입 717줄, 미병합)이었다. 이력 없는 세션이
"이 일이면 무엇을 읽나"를 알 수 없었고, 새 기능·조사·문서·운영·총괄의 절차는
없었다. 규칙도 서로 달랐다: 하위 에이전트(AGENTS.md는 권함, 소유자는 금지),
커밋(human-only와 브랜치 커밋 허용), 리뷰 멈춤 기준(거둔 기준이 남음).

고른 방법(2026-11-06 소유자 결정 D1, D2, D4, D12; 설계 design-docs
delegation-loop/02-design.md 4~6·10절):
- CLAUDE.md를 72줄 지도로 바꿨다: 이 repo, HARD-STOP 7개 한 줄씩(정본
  AGENTS.md), 일 → playbook 표, 검증 명령과 실행 위치, 코드만 보고는 헷갈리는
  곳, 소유자 환경 포인터. AGENTS.md를 요약하던 절은 지웠다. AGENTS.md에 없던
  내용은 옮겼다: messaging 예외는 지도 5절, 판단 보고 규칙은
  reference/review-criteria.md 11절, 위험 비례 원칙은 docs/work/README.md 2절.
- docs/work/: README(라우터·크기·공통 단계·커밋·막혔을 때·보고), playbook 6개
  (new-feature, improve, research-design, docs-writing, operate, delegate, 모두
  같은 9칸 뼈대), reference/ 4개(gates, review-criteria, defect-patterns,
  decisions), evidence.md. 옛 매뉴얼 03~06장은 reference/를 늘리지 않고
  review-criteria(점검 기준), defect-patterns(막는 기준), gates(성능 lane)에
  나눠 넣었다. 다섯 번째 reference 파일은 설계의 파일 구성과 달라 버렸고,
  improve.md 본문에 넣는 안은 150줄 상한을 넘어 버렸다.
- improve.md에 수정 보고의 「새로 가정하는 것」 칸(확인 리뷰가 여기서 시작)과
  수정 묶음 상한(영역 하나·발견 8건, 확인 리뷰당 추가 1,500줄)을 넣었다. 지난
  수정 커밋의 추가 줄과 다음 확인 리뷰 발견 수(+906→9, +1,877→7, +5,420→25,
  +13,479→29)가 근거다(evidence.md 3절). 멈춤 기준은 "발견 0"으로 하나만 둔다.
- 커밋: AGENTS.md human-only는 두고 "brief가 허용할 때만 자기 브랜치에" 예외를
  README 4절과 AGENTS.md에 같은 말로 적었다.
- 본문 이력 ID 0. 지난 리뷰 ID와 사건은 evidence.md와 두 색인
  (reference/decisions.md, reference/defect-patterns.md)에만 둔다.
- 연결: README.md(HARD-STOP을 "8개"로 잘못 적은 것도 7개로), docs/README.md,
  docs/manual/README.md(입구 연결), docs/manual/02-new-feature.md(지운
  CLAUDE.md 「Layer workflow」를 가리키던 줄).

위험·한계: 이 매뉴얼은 이력 없는 새 세션으로 시험(cold-read)하기 전이라
초안이다. 정식 시험은 총괄이 따로 한다. 작성 중 자가 점검(지도부터 읽어
docs-writing.md로 brief 하나를 써 봄)에서 막힌 네 곳은 고쳤다. docs/manual/
본문에는 아직 이력 ID 9줄이 남아 있다(범위 밖, 후속 작업). gates.md 5절의
성능 단언 속성 문장은 성능 게이트를 고치는 다른 작업과 겹친다.

검증
- python3 scripts/check-work-docs.py: rc=0. 지도 72/120, README 75/80,
  playbook 79~132/150, 진입 경로 최대 279/350, 본문 이력 ID 0줄
- python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md
  AGENTS.md: 504파일, 상대 링크 447개, 깨진 것 0
- CLAUDE.md를 읽는 테스트 DeveloperExperienceContractTest
  .guidanceNamesTheArchitectureSourceSetTask가 기대하는
  "./gradlew :app-bootstrap:architectureTest"를 지도에 남겼다. Gradle 게이트는
  이 커밋을 push한 뒤 desktop에서 돌린다
2026-11-06 19:58:44 +09:00

6.6 KiB

CLAUDE.md — 이 repo의 지도

이 파일은 세션이 처음 읽는 지도다. 규칙을 담지 않고, 어떤 일이면 무엇을 읽을지 가리킨다.

1. 이 repo

  • Java 21 + Spring Boot 4.0.8 Gradle 멀티모듈 Clean Architecture 백엔드 템플릿이다. 서비스는 이 repo를 받아 도메인을 채운다.
  • Gradle 루트는 src/다. Gradle 명령은 src/에서 실행한다.
  • 규칙의 정본은 AGENTS.md다. leaf 목록·경로·허용 의존의 정본은 src/config/architecture/modules.json(registry)이다. 각 leaf의 지역 규칙은 가장 가까운 src/**/CLAUDE.md가 정한다.

2. HARD-STOP — 하나라도 어기면 완료가 아니다

정본은 AGENTS.md 「Prime Directive」다. 두 문서가 다르면 AGENTS.md가 맞다.

  1. domain-core가 framework·transport·database·cloud 의존성을 가진다.
  2. controller가 repository·Spring Data interface·persistence entity를 직접 쓴다.
  3. inbound DTO가 application-core나 domain-core로 들어간다.
  4. 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 간다.
  5. 프로젝트 의존성이 registry나 Gradle 의존성 검증을 어긴다.
  6. 관련 검증 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.
  7. 결론의 범위와 위험에 맞는 증거 없이 저장소 전체에 대한 결론을 낸다.

3. 맡은 일 → 읽을 문서

먼저 docs/work/README.md를 읽는다. 크기 정하기, 모든 작업의 공통 단계, 커밋 규칙이 거기 있다. 그다음 맡은 일의 playbook 하나를 끝까지 읽는다.

맡은 일 playbook
새 업무 기능, 새 capability 모듈 docs/work/new-feature.md → docs/manual/
리뷰, 결함 수정, 리팩터링, 성능, 구조·테스트 구조 개선 docs/work/improve.md
바꾸기 전에 대안 비교와 소유자 결정 docs/work/research-design.md
매뉴얼·안내 문서 쓰기 docs/work/docs-writing.md
게이트 실행, desktop 검증, 릴리스, 파생 서비스 docs/work/operate.md
큰 일을 나눠 다른 세션에 맡기기 docs/work/delegate.md

brief(작업 지시문)가 있으면 brief의 범위·크기·완료 기준이 먼저다. playbook은 brief에 없는 공통 절차를 채운다.

4. 검증 명령과 실행 위치

  • 실행 위치: Gradle·Docker·테스트·게이트는 이 repo 소유자 환경에서 desktop에서만 돌린다. 절차는 docs/work/operate.md 4.1절이다.
  • leaf 하나: registry에서 그 leaf의 gradle_path를 읽고 ./gradlew <gradle-path>:test --console=plain 또는 :check를 돌린다. 기억이나 디렉터리 이름으로 Gradle path를 짐작하지 않는다.
  • 저장소 전체 질문:
./gradlew architectureCheck --console=plain
./gradlew :app-bootstrap:architectureTest --console=plain
./gradlew verifyPublicPathSnapshot --console=plain
./gradlew :app-bootstrap:verifyEnvKeys --console=plain
  • 공개 경로 검사와 env 키 검사는 그 표면이 바뀌었을 때 돌린다. 전체 test·check·ci는 brief가 시킬 때 돌린다.
  • 게이트 목록(ci, mainCheck, integrationCheck, performanceCheck, releaseCheck 등)과 바꾼 것에 맞는 게이트는 docs/work/reference/gates.md다.
  • docs/work/나 이 파일을 고쳤으면 python3 scripts/check-work-docs.py를 돌린다.

5. 코드만 보고는 헷갈리는 곳

  • leaf 목록은 registry 하나다. 문서는 leaf 개수를 적지 않는다(적힌 수는 leaf가 늘면 틀린다). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 registry의 allowed_dependencies가 정하고, 방향 게이트가 그 밖의 edge를 막는다.
  • src/messaging/*는 Clean Architecture 계층이 아니다. 자기 API·SPI·adapter·조립 경계를 가진, 들여온(vendored) 메시징 제품이다. domain-core·application-core·shared-contract에 의존하지 않는다. 이 애플리케이션은 adapter:outbound:messaging의 bridge로만 닿는다. 이유와 지역 규칙은 src/messaging/CLAUDE.md다.
  • composition:* leaf는 조립만 한다. outbox relay, 멱등성 executor, durable operation처럼 bootstrap에서 떼어 낸 조립이다. 각각 runtimeOnly 한 줄로 고른다.
  • capability는 한 줄로 켜고 끈다. 기본 조립은 web inbound, 운영 관측, core들, support·identifier뿐이다. JPA도 src/app-bootstrap/build.gradle의 runtimeOnly 한 줄로 켠다. 규칙은 AGENTS.md 「부가 기능(capability) 모듈 규칙」이다.
  • gRPC 플랫폼 라이브러리는 다른 빌드다. src/grpc/*·src/grpc-advanced/*(registry의 "build": "optional-grpc")는 -p optional-platforms로 돈다. adapter:inbound:grpc는 애플리케이션 adapter라 주 빌드에 있다.
  • src/sample-portfolio는 지울 수 있는 샘플이다. 한 leaf에 모든 계층을 둔 모양이라 배치를 따라 하지 않는다. 새 기능의 예시는 scripts/new-feature.sh의 출력이다.
  • 저장소 파일을 읽는 테스트는 태그가 있다. 문서와 대조하는 테스트는 document-contract(main 단계 mainCheck), 빌드 스크립트·workflow를 읽는 테스트는 repository-contract(PR)다. 문서를 고치면 그 문서를 읽는 테스트를 찾는다.
  • 커밋 정책은 human-only다. brief가 허용할 때만 자기 브랜치에 커밋·push한다. 자세한 것은 docs/work/README.md 4절이다.
  • 문서 위치 규칙은 docs/README.md다. 설계서는 docs/superpowers/specs/, 결정 기록은 docs/adr/, 리뷰는 docs/reviews/, 파생 서비스용 변경 안내는 docs/upgrade/다.

6. 소유자 환경

  • 이 repo 소유자의 기계·세션 도구에 묶인 규칙은 두 곳에만 있다: docs/work/operate.md 4.1절(실행 위치)과 docs/work/delegate.md 4.3절(세션). 공용 정본은 design-docs conventions/delegation-loop.md 11절이다.
  • Agent 도구(세션 안의 하위 에이전트)는 이 repo의 .claude/settings.json이 막는다. 일을 나눌 때는 delegate.md대로 별도 세션에 맡긴다.
  • 작업 사고 순서의 정본은 design-docs conventions/work-thinking-order.md, 커밋·PR 형식은 conventions/commit-and-pr.md다.
  • 보고 말투와 형식은 소유자의 전역 ~/.claude/CLAUDE.md를 따른다.