문제: 앞 커밋이 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
7.2 KiB
01. 생성 명령 — 새 기능 뼈대
핵심
scripts/new-feature.sh <FeatureName> 한 번으로 새 업무 기능의 뼈대가 계층 leaf 다섯 곳에 생긴다.
만든 직후 그대로 PR 게이트(ci의 해당 leaf check)와 architectureCheck를 통과한다. 이 성질은
scripts/verify-feature-scaffold.sh가 main 단계(mainCheck)에서 매번 확인한다.
scripts/new-feature.sh Invoice
-> domain-core Invoice, InvoiceId, InvoiceIdFactory, InvoiceRepository, InvoiceInvariantException
+ testFixtures: InMemoryInvoiceRepository, SequentialInvoiceIdFactory, InvoiceRepositoryContract
-> application-core CreateInvoiceUseCase, GetInvoiceUseCase, command·query·view, InvoiceErrorCode, 예외 2개
-> outbound:identifier UuidInvoiceIdFactory
-> inbound:web InvoiceController (POST /invoices, GET /invoices/{id}), 요청·응답 DTO
-> app-bootstrap InvoiceConfig + AutoConfiguration.imports 한 줄
-> 각 leaf 테스트 불변식, id 문법, 유스케이스, 공유 계약, HTTP 계약, 조립 조건
-> spotlessApply (이름 길이에 따라 Javadoc 줄바꿈이 달라져서)
사용법
scripts/new-feature.sh Invoice # /invoices, 권한 invoice:create
scripts/new-feature.sh PurchaseOrder # /purchaseOrders, 권한 purchase-order:create
scripts/new-feature.sh Person --path people # 복수형이 규칙대로 안 될 때
scripts/new-feature.sh Invoice --no-format # Gradle 없이 파일만 (뒤에 spotlessApply 직접)
| 입력 | 규칙 | 어디서 막나 |
|---|---|---|
| 이름 | PascalCase, 영숫자 | 스크립트 |
| 패키지 이름 | 이름을 소문자로(purchaseorder). Java 예약어이거나, 다섯 루트 중 어디든(어느 leaf든) 이미 있는 패키지 이름이면 거절 — 템플릿 패키지(operation, lock, cache…)가 모두 여기 걸린다. 목록은 src/application/core/AGENTS.md 「Package ownership」 |
스크립트, NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES |
| HTTP 경로 | lowerCamel 복수형. AIP-122 모양 | 스크립트, ForbiddenApiArchitectureTest.CONTROLLER_REQUEST_MAPPINGS_FOLLOW_AIP122 |
| 이미 있는 파일·패키지 | 덮어쓰지 않고 멈춘다 | 스크립트 |
생성 뒤 확인:
./gradlew :domain-core:check :application-core:check :adapter:outbound:identifier:check \
:adapter:inbound:web:check :app-bootstrap:check architectureCheck --console=plain
만드는 것과 만들지 않는 것
| 만든다 | 만들지 않는다 | 이유 |
|---|---|---|
| 도메인 모델·포트·불변식, 유스케이스 두 개(쓰기·읽기), id adapter, 컨트롤러, 조립, 테스트 | 저장 adapter(JPA 엔티티·Spring Data·마이그레이션) | 저장소 종류(JPA/Mongo), 마이그레이션 위치·번호대, 실 DB 계약 lane은 서비스가 정한다(04장). 템플릿이 정하면 upstream과 병합 충돌이 나는 자리다 |
권한 선언 @RequiresPermission("<f>:create") |
역할 → 권한 매핑 | 어떤 역할이 쓸 수 있는지는 서비스의 결정이다(07장). 매핑 전에는 쓰기가 모두 403 — 안전한 쪽 |
<F>ErrorCode enum |
docs/registries/error-codes.yaml 행 |
그 registry는 템플릿 운영 코드 전용이다. 서비스 코드는 서비스 registry에(06장) |
| 읽기 유스케이스 | 목록·수정·삭제 | 목록은 페이지·정렬·N+1 판단이, 수정은 동시성(버전) 판단이 필요하다(04장) |
저장 adapter가 없으면 <F>Config의 @ConditionalOnBean(<F>Repository)가 꺼져 있어 엔드포인트가
없다. 반쯤 켜진 상태(엔드포인트는 있는데 저장이 안 됨)가 생기지 않는다.
생성 결과는 placeholder 필드 name 하나를 가진다. 기능의 실제 상태로 바꾸는 것이 첫 작업이다.
왕복 검사
verify-feature-scaffold.sh
-> 작업 트리를 임시 디렉터리로 복사(추적 + 무시되지 않은 새 파일), git init
-> new-feature.sh Operation / Notification / Common (템플릿 패키지 이름: 거절되고 아무것도 안 씀)
-> new-feature.sh Invoice, new-feature.sh PurchaseOrder (한 단어 / 여러 단어)
-> 생성 파일이 있는지 확인
-> 생성물이 닿는 leaf(domain-core, application-core, identifier, web, app-bootstrap) check + architectureCheck
-> 각 leaf 테스트 결과에 생성된 테스트 클래스가 실행·통과로 남았는지 확인
-> 임시 디렉터리 삭제
- 루트 태스크
verifyFeatureScaffold(build.gradle)가 이 스크립트를 부르고mainCheck에 들어 있다. 중첩 Gradle 빌드라 PR 단계가 아니라 main 단계다. - 템플릿이나 템플릿이 기대는 규칙(ArchUnit, Error Prone, 포맷)이 바뀌어 생성물이 깨지면 여기서 빨강이 된다.
- 생성된 테스트가 실행되지 않고 지나가는 일(빈 녹색)을 막으려고 결과 XML을 확인한다.
고른 형태와 버린 대안
| 형태 | 결정 | 이유 |
|---|---|---|
scripts/의 bash + 텍스트 템플릿(scripts/feature-scaffold/templates/**/*.tmpl) |
채택 | 개발자 도구는 scripts/에 둔다는 repo 관례(ca.developer-bootstrap 플러그인을 지우고 scripts/bootstrap-local.sh로 옮긴 것, build-logic/README.md). 템플릿이 실제 Java 파일 모양이라 리뷰가 쉽다. Gradle 설정 단계를 거치지 않아 빠르다 |
build-logic의 Gradle 태스크(./gradlew newFeature -Pname=…) |
버림 | build-logic은 빌드 규약·아키텍처 검사만 둔다(build-logic/AGENTS.md). 소스를 쓰는 태스크는 configuration cache·up-to-date와 맞지 않는다 |
| 생성 대신 예시 기능을 커밋해 두고 복사 | 버림 | 복사본이 하나 더 생겨 규칙과 갈라진다. 이름 바꾸기를 사람이 손으로 한다 |
| 왕복 검사를 JUnit 안에서 javac로 컴파일 | 버림 | Spotless·Error Prone·ArchUnit 전체를 다시 구현해야 하고, 실제 게이트와 다른 것을 검사하게 된다. 실제 Gradle 게이트를 그대로 돌리는 쪽을 골랐다 |
생성 뒤 자동 spotlessApply |
채택(끄려면 --no-format) |
google-java-format이 Javadoc을 이름 길이에 따라 다시 접는다. 템플릿만으로는 모든 이름에서 포맷 검사를 통과시킬 수 없다 |
생성 결과가 기대는 빌드 설정
생성물이 컴파일되려고 다음 의존이 미리 들어 있다(모두 registry가 허용한 edge).
| 파일 | 설정 | 왜 |
|---|---|---|
src/domain/core/build.gradle |
java-test-fixtures |
domain 소유 포트의 fake·계약이 포트 소유자 testFixtures에 있어야 한다(.claude/rules/java-tests.md 규칙 6) |
src/application/core/build.gradle, src/adapter/inbound/web/build.gradle, src/bootstrap/app/build.gradle |
testImplementation testFixtures(project(':domain-core')) |
유스케이스·HTTP·조립 테스트가 그 fake를 쓴다 |
src/adapter/inbound/web/build.gradle |
implementation project(':domain-core') |
컨트롤러가 경로 문자열을 도메인 id로 바꾼다 |
src/adapter/outbound/identifier/build.gradle |
implementation project(':domain-core') |
id adapter가 도메인 IdFactory 포트를 구현한다 |