leaf·family 지역 규칙은 지금 src/**/CLAUDE.md에만 있어서 Claude Code 밖의 에이전트는 이 규칙을 정본 이름으로 찾지 못한다. 소유자가 2026-11-07에 루트와 하위 폴더 모두 AGENTS.md를 정본으로 정했다 (design-docs harness/01-harness-design.md 13절 Q1·Q2). - 28개 파일을 git mv로 같은 폴더 AGENTS.md로 옮기고, 그 자리 CLAUDE.md에는 `@AGENTS.md` 한 줄만 둔다. 이 세션에서 src/domain-core 파일을 열자 CLAUDE.md의 가져오기가 펼쳐져 AGENTS.md 본문이 함께 읽히는 것을 확인했다. 그래서 Claude Code는 지금처럼 그 폴더를 만질 때 규칙을 읽는다. - 버린 대안: 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않는다), CLAUDE.md 그대로 두기(다른 에이전트가 못 찾는다). - 살아 있는 문서와 테스트 코드의 leaf 규칙 경로를 새 이름으로 바꿨다. 기록 문서(evidence, upgrade, design, history, reviews, adr)는 쓴 때의 경로를 그대로 둔다. - link-check workflow(lychee)는 src/**/CLAUDE.md만 본다. 내용이 AGENTS.md로 가면 상대 링크가 검사 밖으로 나가므로, PR마다 도는 check-docs.py에 살아 있는 문서 전체의 상대 링크 검사를 더했다. workflow는 CI 재편 몫이라 고치지 않았다. - check-work-docs.py의 이력 ID 검사도 src/**/AGENTS.md를 본다. 위험: git은 이 커밋을 "CLAUDE.md 수정 + AGENTS.md 추가"로 본다(같은 이름의 새 파일이 생겨 이름 바꾸기로 잡히지 않는다). 옛 이력은 `git log -- <폴더>/CLAUDE.md`로 본다. 코드 주석의 "CLAUDE.md"는 가져오기를 거쳐 같은 문서에 닿으므로 운영 코드는 고치지 않았다. 검증: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py, python3 -m unittest discover -s scripts/tests 모두 rc=0. 링크 검사 시험은 검사 조건을 끈 사본에서 7건 중 3건이 실패했다. BREAKING CHANGE: 파생 서비스의 leaf 규칙 문서 이름이 AGENTS.md로 바뀐다. 동기화 뒤 각 leaf의 CLAUDE.md는 `@AGENTS.md` 한 줄이다.
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/adapter/outbound/identifier/src/main/java/dev/caskeleton/adapter/outbound/identifier/UuidV7DurableOperationIdFactory.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/AGENTS.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/AGENTS.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). 이것은 400VALIDATION_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.