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

8.8 KiB

02. 새 도메인·유스케이스 추가

핵심

안쪽 계층부터 바깥으로 만든다. 각 단계는 그 단계의 테스트까지 끝내고 다음으로 간다. 생성 명령(01장)이 1~5단계의 뼈대를 만들고, 이 장은 각 단계에서 사람이 정할 것을 적는다.

1 domain-core ─▶ 2 application-core ─▶ 3 outbound adapter ─▶ 4 inbound adapter ─▶ 5 app-bootstrap
 모델·불변식       유스케이스·포트          저장·외부 연동         전송·DTO·오류         bean·조건·권한
 (Java만)          (Java + 계약 타입)       (Spring·JPA 등)         (HTTP 등)             (조립)

바깥 계층은 안쪽을 알지만 안쪽은 바깥을 모른다. 그래서 안쪽부터 만들면 각 단계가 앞 단계만 보고 컴파일된다. 한 단계가 다른 leaf나 계층을 고쳐야 하면 거기서 멈추고 설계를 다시 본다 (새 기능 playbook 「하지 말 것」).

0단계 — 배치를 정한다

먼저 03장으로 이 기능을 어디 둘지 정한다. 기본은 계층 leaf 안 <feature> 패키지다. 생성 명령은 이 기본값만 만든다.

1단계 — domain-core: 모델과 불변식

만드는 것: aggregate(@AggregateRoot), id(@ValueObject record, ResourceId), id 생성 포트 (IdFactory 상속), 저장 포트(*Repository), 불변식 예외(Reason enum). 예: 생성 결과 src/domain-core/src/main/java/dev/caskeleton/domain/<f>/.

검사: DomainPurityArchitectureTest(Spring·JPA·전송 타입 금지, setter 비공개, 감사 필드 금지), ForbiddenApiArchitectureTest.NO_LONG_ID_PK.

판단: id를 누가 만드나

  • 고르는 기준: 클라이언트가 같은 요청을 다시 보낼 때 같은 리소스를 가리켜야 하는가.
  • 기본값: 서버가 만든다. domain XIdFactory extends IdFactory<XId> + adapter:outbound:identifier 구현. 문법은 id 값 객체 생성자에서 검사한다.
  • 예외: 클라이언트가 자연 키(주문번호 등)를 주는 기능은 그 키를 id로 쓴다. 이때 중복은 DB 유일성 제약이 막는다(04장). UUIDv7이 필요하면 src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/outbound/identifier/UuidWorkLogIdFactory.java처럼 바꾼다.

판단: 불변식을 어디 두나

  • 고르는 기준: 규칙이 aggregate 하나의 상태만 보고 판정되는가.
  • 기본값: aggregate 메서드·팩토리 안. 위반은 XInvariantException(Reason).
  • 예외: 둘 이상의 aggregate나 저장된 다른 행을 봐야 하는 규칙(중복 금지 등)은 유스케이스 + DB 제약. 조회 후 insert만으로는 동시 요청에서 깨진다(04장).

판단: 저장 포트를 누가 소유하나

  • 고르는 기준: 포트가 aggregate 단위로 말하는가, 기술적 저장·조회인가.
  • 기본값: aggregate를 통째로 저장·로드하면 domain 소유 XRepository.
  • 예외: 읽기 모양이 aggregate와 다르면 application 소유 XQueryPort + projection(record). QUERY_PORTS_DO_NOT_LEAK_DOMAIN_JPA_OR_WEB_TYPES가 반환 타입을 검사한다. lease·claim 같은 기술 저장은 application 소유 *StorePort. 이름 규칙의 정본은 src/application-core/CLAUDE.md.

2단계 — application-core: 유스케이스와 포트

만드는 것: command/query record, 유스케이스(쓰기 CommandUseCase, 읽기 QueryUseCase), 반환용 view record, 오류 코드 enum과 carrier 예외. 예: src/application-core/src/main/java/dev/caskeleton/application/<f>/.

필수 선언(ArchUnit이 강제, ApplicationBoundaryArchitectureTest):

  • 모든 유스케이스에 @UseCaseCapability(transactionMode, idempotency, repositoryAccess). 선언과 실제 TransactionPort 호출이 맞아야 한다(USE_CASE_CAPABILITY_MATCHES_TRANSACTION_PORT_BOUNDARY).
  • 쓰기 유스케이스에 @RequiresPermission("<resource>:<action>")(MUTATING_USE_CASES_DECLARE_REQUIRED_PERMISSION).
  • 유스케이스 클래스는 final이 아니다. 권한 프록시가 하위 클래스를 만든다 (src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/authz/RequiresPermissionProxyabilityTest.java).

판단: 트랜잭션 모양

  • 고르는 기준: 결과를 커밋 뒤에 내보내야 하는가, 호출자와 독립적으로 커밋해야 하는가.
  • 기본값: 쓰기 tx.inWrite, 읽기 tx.inRead.
  • 예외: 커밋 확인 뒤 결과를 노출해야 하면 inRootWrite(바깥 트랜잭션이 있으면 거부). 감사·보상만 inNew(루프 안 금지). 외부 HTTP·메시지 발행은 트랜잭션 밖. 표: src/application-core/CLAUDE.md 「Allowed transactional shapes」.

판단: 무엇을 반환하나

  • 기본값: application view record(XView). 전송 계층이 aggregate를 받지 않는다 (TypeBoundaryArchitectureTest.CONTROLLERS_DO_NOT_RETURN_DOMAIN_OR_ENTITY_TYPES).
  • 예외: 같은 leaf 안 다른 유스케이스가 aggregate를 이어 받아야 하면 aggregate를 반환해도 된다. 컨트롤러는 그때도 응답 DTO로 바꾼다.

판단: 멱등성 선언

05장. 기본값 NOT_IDEMPOTENT(쓰기), IDEMPOTENT(읽기). 클라이언트가 재전송할 수 있는 결제·주문류 쓰기는 KEYED.

3단계 — outbound adapter

만드는 것: 포트 구현. 생성 명령은 id adapter(adapter:outbound:identifier/<f>/Uuid<F>IdFactory)만 만든다. 저장 adapter는 04장 순서로 직접 만든다.

필수: adapter는 포트 소유자 testFixtures의 XRepositoryContract를 실제 저장소로 상속하는 테스트를 가진다(08장). 실 DB가 필요하면 strict lane(integrationTest 등)에 둔다.

4단계 — inbound adapter (HTTP)

만드는 것: 컨트롤러, 요청·응답 DTO. 예: src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/<f>/.

  • 컨트롤러는 변환만 한다: 요청 → command/query → 유스케이스 → Envelope.ok(응답 DTO, ResponseMetaFactory.fromMdc()). repository·엔티티 직접 사용 금지(CONTROLLERS_DO_NOT_ACCESS_REPOSITORIES_OR_JPA_ENTITIES).
  • 생성 201은 Location 헤더를 준다. 비동기 수락은 202(DurableOperationController).
  • 경로는 lowerCamel 복수형(AIP-122).
  • 실패는 던지기만 한다. ApiErrorCarrier를 전역 핸들러가 매핑한다(06장). 기능 전용 핸들러를 만들지 않는다.

판단: 입력 검증을 어디서 하나

  • 고르는 기준: 규칙이 도메인 규칙인가, wire 모양(형식·필수 키)인가.
  • 기본값: 도메인 규칙은 aggregate가 한 번만 검사한다. DTO에 같은 규칙을 bean validation으로 또 쓰지 않는다(두 벌이 갈라진다).
  • 예외: 도메인이 볼 수 없는 wire 모양 — 크기 상한, 형식 패턴, 필수 키 — 은 DTO에 @NotNull·@Size·@Pattern으로 둔다(SubmitOperationHttpRequest). 이것은 400 VALIDATION_FAILED로 나간다.

5단계 — app-bootstrap 조립

만드는 것: @AutoConfiguration 클래스 하나 + AutoConfiguration.imports 한 줄. 예: src/composition/durable-operation/src/main/java/dev/caskeleton/composition/operation/DurableOperationAutoConfiguration.java.

  • @ConditionalOnBean(필요한 포트들): 포트 구현이 없으면 기능 전체가 없다.
  • 유스케이스는 @Bean으로 만든다. 직접 new 하면 권한 프록시가 없어 @RequiresPermission이 조용히 빠진다.
  • 컨트롤러는 component scan이 아니라 @Import로 등록한다. scan은 dev.caskeleton.bootstrap만 본다 (CaSkeletonApplication).
  • 포트 구현이 다른 자동 설정에서 오면 afterName으로 순서를 적는다. 안 적으면 조건이 그 bean을 못 본다.
  • 이벤트를 내면 계약 contribution도 @Bean으로 등록한다(09장).
  • 역할 → 권한 매핑을 app.authz.role-permissions에 더한다(07장).

6단계 — 공개 계약이 바뀌었으면 함께 고친다

바뀐 것 같이 할 것
새 공개 경로(인증 없이 열림) docs/security/public-paths-snapshot.txt, ./gradlew verifyPublicPathSnapshot
새 env 키 docs/registries/env-keys.yaml, ./gradlew :app-bootstrap:verifyEnvKeys
새 의존성 lockfile 갱신(./gradlew :<leaf>:resolveAndLockAll --write-locks), verifyDependencyLocks
새 마이그레이션 04장 번호 규칙
새 이벤트 계약 09장

지금 이해하면 되는 것

  • 안쪽부터: domain → application → outbound → inbound → bootstrap.
  • 쓰기 유스케이스는 non-final + @RequiresPermission + bean. 셋 중 하나라도 빠지면 권한 검사가 없다.
  • 조립은 포트가 있을 때만 켜진다. 저장 adapter가 생기기 전 기능은 없는 상태다.
  • 같은 규칙을 두 곳에 쓰지 않는다. 도메인 규칙은 aggregate, wire 모양은 DTO.