문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
7.2 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와 가장 가까운 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 |