# 개발 매뉴얼 — 이 템플릿으로 기능을 만드는 순서와 판단 지점 이 매뉴얼은 **새 업무 기능을 추가하는 사람**이 읽는다. 무엇을 어떤 순서로 만들고, 갈림길마다 무엇을 기준으로 고르는지를 적는다. 규칙의 정본은 따로 있다. 이 매뉴얼은 그 정본을 **가리키고** 작업 순서로 엮을 뿐, 규칙을 다시 쓰지 않는다(아래 「정본 위치」). 입구는 작업 매뉴얼의 [새 기능 playbook](../work/new-feature.md)이다. 일의 크기, 완료 기준, 하지 말 것은 거기에 있다. 새 기능이 아닌 일(개선, 조사·설계, 문서, 운영)은 [docs/work/](../work/README.md)가 맡는다. 판단 지점은 모두 같은 틀로 적는다. - **고르는 기준** — 무엇을 보고 고르는가 - **기본값** — 기준이 애매하면 이것 - **예외** — 기본값을 벗어나도 되는 경우와 그때 같이 해야 하는 것 근거는 코드 경로로 단다. 경로는 저장소 루트 기준이다. ## 읽는 순서 처음이면 1 → 2 → 3을 읽고 생성 명령을 한 번 돌려 본다. 그다음은 기능에 필요한 장만 읽는다. | 장 | 언제 읽나 | | --- | --- | | [01. 생성 명령](01-generator.md) | 새 기능 뼈대를 만들 때. 무엇을 만들고 무엇을 안 만드는지 | | [02. 새 도메인·유스케이스 추가](02-new-feature.md) | 기능 하나를 domain → application → outbound → inbound → bootstrap 순서로 만들 때 | | [03. 새 기능을 둘 곳 고르기](03-placement.md) | 계층 leaf 안 패키지 / `application-*` capability / 별도 수직 중 고를 때 | | [04. 영속성](04-persistence.md) | 저장 adapter, 엔티티 매핑, DB 제약과 충돌 변환, 마이그레이션 번호 | | [05. 멱등성·결과 불명](05-idempotency.md) | 재시도될 수 있는 쓰기, 409/422, `DB_COMPLETION_UNKNOWN` | | [06. 오류 모델](06-errors.md) | 실패를 클라이언트 탓/서버 탓으로 나누고 코드로 내보낼 때 | | [07. 권한](07-authorization.md) | `@RequiresPermission`, 역할 매핑, 객체 단위 인가 | | [08. 테스트 작성 규칙](08-testing.md) | 포트당 fake, 공유 계약, 이름·주석, lane 단계 지정 | | [09. outbox·이벤트](09-outbox-events.md) | 저장과 함께 이벤트를 내보낼 때 | | [10. capability 추가·제거](10-capabilities.md) | JPA·Redis·Kafka 같은 부가 기능을 켜고 끌 때 | | [11. 체크리스트](11-checklist.md) | PR 올리기 전 | | [부록. 공통 원칙 후보](appendix-common-principles.md) | 프론트·백엔드 공통 실무 원칙으로 옮길 후보 | ## 정본 위치 매뉴얼과 정본이 다르면 정본이 맞다. 매뉴얼을 고친다. | 무엇 | 정본 | | --- | --- | | 계층 경계·금지 규칙 | `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](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 |