Files
clean-architecture-backend-…/docs/manual/01-generator.md
T
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 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
2026-11-11 22:15:42 +09:00

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 포트를 구현한다