문제: 저장소 전체 ArchUnit suite가 약속한 것을 막지 못하는 길이 다섯이다.
1. controller가 domain repository 포트(생성 명령이 aggregate 옆
dev.caskeleton.domain.<feature>에 두는 <Aggregate>Repository)를 주입해도
걸리지 않는다. 규칙은 ..repository.. 패키지와 Spring Data·JPA 타입만 본다.
gRPC 서비스는 controller 판정에 들지 않는다(HARD-STOP 2).
2. ..adapter.inbound.. 밖의 사용자 전송(조립 모듈의 controller 등)이
@SystemInvoked 유스케이스를 new로 만들어 부르거나, 표시 없는 중간 클래스를
거쳐 부르면 통과한다. 매뉴얼 07은 이것을 "빌드 실패"라고 약속한다. app
AGENTS의 "bootstrap에 controller 금지"도 검사가 없다.
3. web 패키지 밖에 둔 Spring Security 요청 경로 확장점(JWT converter,
AuthorizationManager, AuthenticationProvider, 필터 chain DSL)은 servlet 타입을
쓰지 않아 사용자 전송으로 보이지 않는다.
4. 설정이 interceptor를 자기 클래스 타입 필드로 쥐고
registration.interceptors(x)로 넘기면, ArchUnit 1.3은 ChannelRegistration
(설정용 타입)만 기록해 설정이 사용자 전송이 되지 않는다.
5. capabilityProjects에 :adapter:inbound:messaging이 없어 저장소 전체 suite가
MessagingInboxAutoConfiguration을 읽지 않는다("suite가 모든 모듈을 본다"는
주석과 다름).
고른 방법:
1. ENDPOINTS_DO_NOT_HOLD_PERSISTENCE_PORTS: controller와 gRPC 서비스는
..domain..·..application..의 *Repository·*StorePort·*QueryPort에 의존하지
않는다.
2. CONTROLLERS_LIVE_IN_INBOUND_ADAPTERS, 그리고
USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS의 전이 대상에 @SystemInvoked
유스케이스 자신을 더한다.
3. org.springframework.security.web·config.annotation.web·
oauth2.server.resource·oauth2.jwt 패키지와 AuthenticationProvider·
AuthorizationManager를 사용자 전송·요청 처리기 목록에 더한다.
4. 설정이 의존하는 프로젝트 클래스가 요청 처리기 타입을 상속·구현하면 그
설정도 사용자 전송으로 본다.
5. capabilityProjects와 주석 처리된 runtimeOnly 줄에 inbound messaging을 더한다.
매뉴얼 07 표와 app AGENTS를 같이 고쳤다. 지금 운영 코드에 걸리는 곳은
없다(inbound가 그런 포트를 import한 곳 0, 조립 모듈 controller 0).
버린 대안: inbound가 application *Port 전부를 못 쓰게 하기 — web이
AuthorizationPort·CorrelationIdPort를 구현하고 쓰므로 맞는 코드가 걸린다.
IdFactory는 지금 DurableOperationController가 쓰고 있어 이번 규칙에서 뺐다
(그 controller의 id 생성은 리뷰 RR9-05-13로 따로 고친다).
위험·한계: 규칙 3·4는 목록·클래스 의존 방식이라, 목록에 없는 보안 타입이나
타입 이름이 남지 않는 길(bean 이름 조회, 함수로 감싸 넘기기)은 여전히
못 본다(매뉴얼 07 「규칙이 못 보는 길」). gRPC 서비스 fixture는 io.grpc가
architectureTest 컴파일 classpath에 없어 두지 않았다 — 판정은
BindableService 이름으로 한다.
검증(desktop, --no-build-cache):
- RED: 기준 a7e38c10 + 새 fixture와 시험(새 규칙 대신 기존 규칙을 부르는
변형)만으로 ArchitectureViolationFixtureTest 204건 중 5건 실패 — 다섯 위반
모두 기존 규칙에 안 걸림. 허용 시험은 통과.
- GREEN: :app-bootstrap:resolveAndLockAll --write-locks(잠금 변화 없음),
spotlessApply 뒤 :app-bootstrap:architectureTest 259건 실패 0,
:app-bootstrap:testQualityCheck, :app-bootstrap:spotlessCheck,
:verifyDependencyLocks, :architectureCheck rc=0. 로그 desktop
~/r9-be-logs/b14-{red,green2}.log.
Refs: docs/reviews/2026-11-12-round9-review RR9-05-01~05
개발 매뉴얼 — 이 템플릿으로 기능을 만드는 순서와 판단 지점
이 매뉴얼은 새 업무 기능을 추가하는 사람이 읽는다. 무엇을 어떤 순서로 만들고, 갈림길마다 무엇을 기준으로 고르는지를 적는다. 규칙의 정본은 따로 있다. 이 매뉴얼은 그 정본을 가리키고 작업 순서로 엮을 뿐, 규칙을 다시 쓰지 않는다(아래 「정본 위치」).
입구는 작업 매뉴얼의 새 기능 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와 가장 가까운 src/**/AGENTS.md |
| 테스트 작성 규칙 | .claude/rules/java-tests.md |
| leaf 목록·허용 의존 | gradle/modules.json |
| 이름 규칙(유스케이스·포트·command·query) | src/application/core/AGENTS.md 「Naming convention」. 기계 검사는 src/bootstrap/app/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java와 ApplicationBoundaryArchitectureTest.java |
| 유스케이스 모양·트랜잭션 모양 | src/application/core/README.md 「정해진 유스케이스 모양 (Canonical use case shape)」, src/application/core/AGENTS.md 「허용하는 트랜잭션 모양 (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개 | 10-capabilities.md |
이름 규칙은 위 한 곳에만 둔다. 이 매뉴얼과 생성 명령은 그 규칙을 따른 결과를 보여 줄 뿐이고,
규칙 문장을 복사하지 않는다. 생성 명령의 템플릿(scripts/feature-scaffold/templates/)이 규칙과
어긋나면 scripts/verify-feature-scaffold.sh가 ArchUnit으로 잡는다.
따라 할 예시는 하나
예시가 셋(한 leaf에 모든 계층을 둔 샘플 모듈, onboarding fixture, durable operation)이라 어느 것을 베끼느냐에 따라 배치가 달라졌다(2026-11-01 성숙도 리뷰). 이제 새 업무 기능의 예시는 생성 명령의 출력 하나다. 샘플 모듈은 2026-11-07에 지웠다.
| 코드 | 역할 | 따라 하나 |
|---|---|---|
scripts/new-feature.sh 출력 |
계층 leaf에 나눈 업무 기능 | 이것을 따른다 |
src/bootstrap/app/src/test/java/dev/caskeleton/onboarding/** |
ArchUnit 규칙이 새 기능 모양에 적용되는지 확인하는 테스트 fixture | 따르지 않는다 |
src/application/core/.../operation + DurableOperationAutoConfiguration(composition:durable-operation) |
템플릿 플랫폼 기능 | 조립 모양(@ConditionalOnBean + 유스케이스 @Bean)만 본다 |
리뷰 뒤 첫 수정으로 생긴 패턴
2026-11-01 성숙도 리뷰 뒤 같은 날 한 첫 수정에서 굳은 모양이다. 각 장에 반영했다.
| 패턴 | 근거 코드 | 장 |
|---|---|---|
| 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로 변환 | 04장 「중복·경쟁은 DB가 막는다」(템플릿 코드에 예 없음) | 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(build.gradle strictLaneStages) |
08 |
| 서비스 마이그레이션은 별도 history table, 번호는 운영과 겹치지 않게 | NotificationSchemaStream(persistence-notification) |
04 |
| 재시도 가능한 broker 거부는 DEAD가 아니라 재시도 | docs/runbooks/outbox-dead-letter.md |
09 |