문제: 앞 커밋이 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
87 lines
7.2 KiB
Markdown
87 lines
7.2 KiB
Markdown
# 개발 매뉴얼 — 이 템플릿으로 기능을 만드는 순서와 판단 지점
|
|
|
|
이 매뉴얼은 **새 업무 기능을 추가하는 사람**이 읽는다. 무엇을 어떤 순서로 만들고, 갈림길마다
|
|
무엇을 기준으로 고르는지를 적는다. 규칙의 정본은 따로 있다. 이 매뉴얼은 그 정본을 **가리키고**
|
|
작업 순서로 엮을 뿐, 규칙을 다시 쓰지 않는다(아래 「정본 위치」).
|
|
|
|
입구는 작업 매뉴얼의 [새 기능 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 |
|