Files
clean-architecture-backend-…/docs/manual/README.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

7.3 KiB

개발 매뉴얼 — 이 템플릿으로 기능을 만드는 순서와 판단 지점

이 매뉴얼은 새 업무 기능을 추가하는 사람이 읽는다. 무엇을 어떤 순서로 만들고, 갈림길마다 무엇을 기준으로 고르는지를 적는다. 규칙의 정본은 따로 있다. 이 매뉴얼은 그 정본을 가리키고 작업 순서로 엮을 뿐, 규칙을 다시 쓰지 않는다(아래 「정본 위치」).

입구는 작업 매뉴얼의 새 기능 playbook이다. 일의 크기, 완료 기준, 하지 말 것은 거기에 있다. 새 기능이 아닌 일(개선, 조사·설계, 문서, 운영)은 docs/work/가 맡는다.

판단 지점은 모두 같은 틀로 적는다.

  • 고르는 기준 — 무엇을 보고 고르는가
  • 기본값 — 기준이 애매하면 이것
  • 예외 — 기본값을 벗어나도 되는 경우와 그때 같이 해야 하는 것

근거는 코드 경로로 단다. 경로는 저장소 루트 기준이다.

읽는 순서

처음이면 1 → 2 → 3을 읽고 생성 명령을 한 번 돌려 본다. 그다음은 기능에 필요한 장만 읽는다.

장 언제 읽나
01. 생성 명령 새 기능 뼈대를 만들 때. 무엇을 만들고 무엇을 안 만드는지
02. 새 도메인·유스케이스 추가 기능 하나를 domain → application → outbound → inbound → bootstrap 순서로 만들 때
03. 새 기능을 둘 곳 고르기 계층 leaf 안 패키지 / application-* capability / 별도 수직 중 고를 때
04. 영속성 저장 adapter, 엔티티 매핑, DB 제약과 충돌 변환, 마이그레이션 번호
05. 멱등성·결과 불명 재시도될 수 있는 쓰기, 409/422, DB_COMPLETION_UNKNOWN
06. 오류 모델 실패를 클라이언트 탓/서버 탓으로 나누고 코드로 내보낼 때
07. 권한 @RequiresPermission, 역할 매핑, 객체 단위 인가
08. 테스트 작성 규칙 포트당 fake, 공유 계약, 이름·주석, lane 단계 지정
09. outbox·이벤트 저장과 함께 이벤트를 내보낼 때
10. capability 추가·제거 JPA·Redis·Kafka 같은 부가 기능을 켜고 끌 때
11. 체크리스트 PR 올리기 전
부록. 공통 원칙 후보 프론트·백엔드 공통 실무 원칙으로 옮길 후보

정본 위치

매뉴얼과 정본이 다르면 정본이 맞다. 매뉴얼을 고친다.

무엇 정본
계층 경계·금지 규칙·테스트 작성 규칙 AGENTS.md(작업 지도는 CLAUDE.md)
leaf 목록·허용 의존 src/config/architecture/modules.json
이름 규칙(유스케이스·포트·command·query) src/application-core/CLAUDE.md 「Naming convention」. 기계 검사는 src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java와 ApplicationBoundaryArchitectureTest.java
유스케이스 모양·트랜잭션 모양 src/application-core/CLAUDE.md 「Canonical use case shape」「Allowed transactional shapes」
HTTP wire 계약(Envelope·멱등성 응답) docs/web/http-contract.md
운영 오류 코드 docs/registries/error-codes.yaml, src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java
엔티티 매핑·마이그레이션 docs/jpa/entity-mapping-guide.md, docs/jpa/migration-guide.md, docs/jpa/transaction-guide.md
capability 완료 기준 7개 AGENTS.md 「부가 기능(capability) 모듈 규칙」

이름 규칙은 위 한 곳에만 둔다. 이 매뉴얼과 생성 명령은 그 규칙을 따른 결과를 보여 줄 뿐이고, 규칙 문장을 복사하지 않는다. 생성 명령의 템플릿(scripts/feature-scaffold/templates/)이 규칙과 어긋나면 scripts/verify-feature-scaffold.sh가 ArchUnit으로 잡는다.

따라 할 예시는 하나

예시가 셋(sample-portfolio 수직, onboarding fixture, durable operation)이라 어느 것을 베끼느냐에 따라 배치가 달라졌다(리뷰 2026-11-01 01-01·07-09). 이제 새 업무 기능의 예시는 생성 명령의 출력 하나다.

코드 역할 따라 하나
scripts/new-feature.sh 출력 계층 leaf에 나눈 업무 기능 이것을 따른다
src/sample-portfolio 한 leaf에 모든 계층을 둔 지울 수 있는 샘플. 개별 기법(조건부 PATCH, 페이지, outbox, DB 유일성 제약)의 참고 기법만 본다. 배치는 따르지 않는다
src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/** ArchUnit 규칙이 새 기능 모양에 적용되는지 확인하는 테스트 fixture 따르지 않는다
application-core/.../operation + DurableOperationAutoConfiguration(composition:durable-operation) 템플릿 플랫폼 기능 조립 모양(@ConditionalOnBean + 유스케이스 @Bean)만 본다

1라운드 수정으로 생긴 패턴 (리뷰 README 13절)

리뷰 뒤 1라운드에서 굳은 모양이다. 각 장에 반영했다.

패턴 근거 코드 장
Envelope는 null 필드를 내보내지 않는다 docs/web/http-contract.md 1절 06
처리 중 409 IDEMPOTENT_IN_FLIGHT는 retryable=true + Retry-After: 2, 같은 키로 재전송 docs/web/http-contract.md 2절 05
커밋 중 연결이 끊기면 재시도 가능이 아니라 결과 불명(DB_COMPLETION_UNKNOWN, 500) src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/failure/PersistenceExceptionTranslator.java, docs/adr/ADR-JPA-003-completion-unknown.md 05
중복 규칙은 조회 후 insert가 아니라 DB 유일성 제약, 위반은 같은 409로 변환 src/sample-portfolio/src/main/resources/db/sample-migration/V8_1__poster_title_unique.sql, PosterRepositoryAdapter 04
여러 인스턴스가 집는 작업은 lease 있는 claim ReconciliationJobStorePort.claimDue(application-notification) 04
양방향 연관관계 금지를 ArchUnit으로 JpaArchitectureRules.associationsAreMappedFromOneSideOnly() 04
store는 호출자 트랜잭션을 요구한다 src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/CallerTransaction.java 04
@RequiresPermission 검사는 인증 체인과 분리된 자동 설정 src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/autoconfigure/WebMethodSecurityAutoConfiguration.java 07
JWT audience 필수, 자기 client role만 src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/JwtDecoderConfig.java, docs/runbooks/auth-audience-mismatch.md 07
strict lane은 반드시 어떤 단계에 속한다 verifyStrictLaneStages(src/build.gradle strictLaneStages) 08
샘플 마이그레이션은 별도 history table, 번호는 운영과 겹치지 않게 SamplePostgreSqlPersistenceConfig, V8_1__… 04
재시도 가능한 broker 거부는 DEAD가 아니라 재시도 docs/runbooks/outbox-dead-letter.md 09