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` 한 줄이다.
7.7 KiB
Mongo 소비 leaf 등록 절차
파생 서비스가 adapter:outbound:persistence-mongo를 실제로 쓰려면 자기 Mongo 어댑터 leaf를 하나
만든다. 이 leaf(이하 "플랫폼 leaf")는 client·template·정책·실패 분류를 주고, document·repository·
mapper·port 구현은 서비스 leaf가 가진다. 플랫폼 leaf에는 예시 도메인을 production으로 넣지 않는다
(src/adapter/outbound/persistence-mongo/AGENTS.md "Forbidden").
전체 흐름:
domain-core (Note) application-core (NoteStore port)
\ /
adapter:outbound:persistence-note ← 서비스가 새로 만드는 leaf
NoteDocument / NoteDocumentMapper / NoteDocumentRepository / MongoNoteStore
|
| implementation
v
adapter:outbound:persistence-mongo ← 플랫폼 leaf (executor, 실패 분류, 정책)
^
| runtimeOnly (둘 다)
app-bootstrap
1. 동작하는 예시
예시 한 벌이 플랫폼 leaf의 테스트 소스에 있다. mongoStableContractTest(그래서 check)에서
컴파일되고 실행되므로 API가 바뀌면 예시도 같이 깨진다.
| 역할 | 예시 타입 | 실제 서비스에서 둘 곳 |
|---|---|---|
| 도메인 타입 | Note |
domain-core |
| outbound port, 도메인 예외 | NoteStore, NoteStore.NoteAlreadyExistsException |
application-core |
| 저장 형태 | NoteDocument (@Document, @Id, @Field) |
서비스 Mongo leaf |
| 변환 | NoteDocumentMapper |
서비스 Mongo leaf |
| collection 접근 | NoteDocumentRepository (DefaultMongoImperativeExecutor 사용) |
서비스 Mongo leaf |
| port 구현, 예외 변환 | MongoNoteStore |
서비스 Mongo leaf |
| 실행 확인 | MongoNoteStoreExampleTest |
서비스 Mongo leaf 테스트 |
위치: src/adapter/outbound/persistence-mongo/src/test/java/dev/caskeleton/adapter/outbound/mongo/example/.
testFixtures가 아니라 테스트 소스에 둔 이유: testFixtures는 소비 leaf의 테스트 classpath에 그대로 올라가는 variant다. 예시 타입이 거기 있으면 API처럼 import된다. 테스트 소스는 아무 데도 export되지 않는다.
2. 레지스트리와 Gradle에 leaf 등록
leaf 목록과 허용 의존 방향의 원본은 src/config/architecture/modules.json이다. 레지스트리에 없는 edge는
verifyCleanArchitectureDependencies가 거부한다.
-
modules.json의modules에 서비스 leaf를 추가한다. 플랫폼 leaf로 가는 edge를 여기서 연다.{ "id": "adapter-outbound-persistence-note", "gradle_path": ":adapter:outbound:persistence-note", "source_path": "src/adapter/outbound/persistence-note", "allowed_dependencies": [ "domain-core", "application-core", "adapter-outbound-persistence-mongo" ] }같은 모양의 선례:
adapter-outbound-persistence-notification이adapter-outbound-persistence-jpa를 같은 방식으로 받는다. -
app-bootstrap의allowed_dependencies에"adapter-outbound-persistence-note"를 더한다.adapter-outbound-persistence-mongo는 이미 들어 있다. -
서비스 leaf의
build.gradle:dependencies { implementation project(':domain-core') implementation project(':application-core') implementation project(':adapter:outbound:persistence-mongo') } -
app-bootstrap/build.gradle에서 두 leaf를 켠다. 플랫폼 leaf 줄은 주석으로 이미 있다.runtimeOnly project(':adapter:outbound:persistence-mongo') runtimeOnly project(':adapter:outbound:persistence-note') -
확인: 새 leaf의
check와architectureCheck를 돈다. 아래 Gradle 경로는 서비스가 만든 leaf의 것이라 이 템플릿에는 없다../gradlew :adapter:outbound:persistence-note:check architectureCheck --console=plain
3. 서비스 leaf가 등록해야 하는 bean
자동 구성되는 MongoCollectionProfileRegistry는 비어 있다. 등록하지 않은 collection profile로
executor를 부르면 거부된다. 서비스 leaf가 자기 collection을 등록한 registry bean을 준다.
@Bean
MongoCollectionProfileRegistry mongoCollectionProfileRegistry() {
return MongoCollectionProfileRegistry.builder()
.register(NoteDocument.COLLECTION, NoteDocument.COLLECTION)
.build();
}
여러 서비스 leaf가 각자 collection을 가지면 registry bean은 하나여야 하므로 composition(보통
app-bootstrap)에서 합친다.
DefaultMongoImperativeExecutor는 자동 구성 bean이다. 서비스 leaf는 그것을 주입받아
NoteDocumentRepository처럼 감싼다.
4. 예외 변환
- executor는 driver·Spring 실패를 한 번만 플랫폼 예외로 바꾼다:
MongoDuplicateKeyException,MongoTimeoutException,MongoWriteConcernException,MongoServerSelectionException등(dev.caskeleton.adapter.outbound.mongo.api.error). - port 구현은 port가 약속한 실패만 도메인 예외로 바꾼다. 예시에서는
MongoDuplicateKeyException→NoteAlreadyExistsException하나다. - 나머지는 그대로 내보낸다. 플랫폼 예외는
outcome()·ambiguous()로 "쓰기가 됐는지 모름"을 알려 준다. 이것을 일반 도메인 예외로 감싸면 호출자가 재시도해도 되는지 판단할 근거가 사라진다. - 트랜잭션은
MongoTransactionRetryCoordinator로 실행한다. 본문의TransientTransactionError는 새 세션에서 본문을 다시 실행하고, commit 결과를 모르면 commit만 재시도한 뒤MongoTransactionCommitUnknownException으로 알린다. 본문은 재실행될 수 있으므로 본문 안에서 외부 호출(메시지 발행, HTTP)을 하지 않는다.
5. 정책을 우회하는 경로 — 쓰기 전에 알 것
| 경로 | 받는 것 | 잃는 것 |
|---|---|---|
DefaultMongoImperativeExecutor (+ MongoAtomicOperationsTemplate, MongoBulkExecutor) |
operation 이름, collection profile 확인, consistency, deadline, 관측, 실패 변환 | 없음. 기본 경로 |
Spring Data MongoRepository (adapter-local) |
짧은 CRUD 코드 | 위 전부. 실패가 Spring DuplicateKeyException 등으로 온다. derived query는 MongoQueryPolicy를 거치지 않는다. deadline·consistency profile이 붙지 않는다 |
MongoTemplate / MongoClient 직접 주입 |
모든 명령 | 위 전부 + collection 범위 확인 |
MongoRepository는 adapter leaf 안에서만 허용된다 (MongoRepositoryArchitectureRules.allowedRepositorySuperTypes). 고르면 예외 변환과 timeout을 서비스 leaf가 직접 책임진다. 플랫폼 공통 CRUD base(CommonMongoRepository등)는 만들지 않는다.- 사용자 입력으로 조건이 바뀌는 동적 조회는
PolicyAwareMongoQueryBuilder(MongoQueryPolicyallowlist)로 만든다. 예시의_id조회처럼 adapter 코드가 고정한 조건은Query를 직접 써도 된다. - inbound adapter(controller 등)는
MongoTemplate·MongoClient를 갖지 않는다. 서비스 leaf 테스트에서 플랫폼 testFixtures의MongoAccessRules.noMongoAccessFrom(...)으로 확인할 수 있다 (testImplementation testFixtures(project(':adapter:outbound:persistence-mongo'))).
6. 연결 설정
URI만 주는 배포(SPRING_MONGODB_URI)는 유한 timeout·pool 기본값을 받는다. 값과 바꾸는 법은
src/adapter/outbound/persistence-mongo/README.md의 SPRING_MONGODB_URI 예시 바로 아래 문단과 MongoUriOnlyClientDefaults에 있다.
production은 typed profile(app.persistence-mongo.platform.profiles.*)을 쓴다.