# 01. 생성 명령 — 새 기능 뼈대 ## 핵심 `scripts/new-feature.sh ` 한 번으로 새 업무 기능의 뼈대가 계층 leaf 다섯 곳에 생긴다. 만든 직후 그대로 PR 게이트(`ci`의 해당 leaf check)와 `architectureCheck`를 통과한다. 이 성질은 `scripts/verify-feature-scaffold.sh`가 main 단계(`mainCheck`)에서 매번 확인한다. ```text 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 줄바꿈이 달라져서) ``` ## 사용법 ```bash 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` | | 이미 있는 파일·패키지 | 덮어쓰지 않고 멈춘다 | 스크립트 | 생성 뒤 확인: ```bash ./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(":create")` | 역할 → 권한 매핑 | 어떤 역할이 쓸 수 있는지는 서비스의 결정이다(07장). 매핑 전에는 쓰기가 모두 403 — 안전한 쪽 | | `ErrorCode` enum | `docs/registries/error-codes.yaml` 행 | 그 registry는 템플릿 운영 코드 전용이다. 서비스 코드는 서비스 registry에(06장) | | 읽기 유스케이스 | 목록·수정·삭제 | 목록은 페이지·정렬·N+1 판단이, 수정은 동시성(버전) 판단이 필요하다(04장) | 저장 adapter가 없으면 `Config`의 `@ConditionalOnBean(Repository)`가 꺼져 있어 엔드포인트가 **없다**. 반쯤 켜진 상태(엔드포인트는 있는데 저장이 안 됨)가 생기지 않는다. 생성 결과는 placeholder 필드 `name` 하나를 가진다. 기능의 실제 상태로 바꾸는 것이 첫 작업이다. ## 왕복 검사 ```text 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` 포트를 구현한다 |