Files
clean-architecture-backend-…/docs/manual/01-generator.md
T
DongHyeonka 12d3f39893 docs(manual): 생성 명령 왕복 검사의 leaf 개수 대신 이름을 쓴다
문제: `docs/manual/01-generator.md`가 「./gradlew 5 leaf check」로 leaf 개수를 복사해
숫자 검사 예외에 있다.

고른 방법: `scripts/verify-feature-scaffold.sh`가 실제로 돌리는 leaf 이름(domain-core,
application-core, identifier, web, app-bootstrap)을 쓴다.

검증: `python3 scripts/check-docs.py` rc=0.
2026-11-07 17:18:18 +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/CLAUDE.md 「Package ownership」 스크립트, NamingConventionTest.FEATURE_PACKAGES_DO_NOT_REUSE_TEMPLATE_PACKAGE_NAMES
HTTP 경로 lowerCamel 복수형. AIP-122 모양 스크립트, ForbiddenApiArchitectureTest.CONTROLLER_REQUEST_MAPPINGS_FOLLOW_AIP122
이미 있는 파일·패키지 덮어쓰지 않고 멈춘다 스크립트

생성 뒤 확인:

cd src
./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(src/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로 옮긴 것, src/build-logic/README.md). 템플릿이 실제 Java 파일 모양이라 리뷰가 쉽다. Gradle 설정 단계를 거치지 않아 빠르다
build-logic의 Gradle 태스크(./gradlew newFeature -Pname=…) 버림 build-logic은 빌드 규약·아키텍처 검사만 둔다(CLAUDE.md Gradle policy). 소스를 쓰는 태스크는 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에 있어야 한다(AGENTS.md 테스트 규칙 6)
src/application-core/build.gradle, src/adapter/inbound/web/build.gradle, src/app-bootstrap/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 포트를 구현한다