Files
clean-architecture-backend-…/docs/manual/01-generator.md
T
DongHyeonka 08f932123a docs(agents)!: leaf 지역 규칙 문서를 같은 폴더 AGENTS.md로 옮긴다
leaf·family 지역 규칙은 지금 src/**/CLAUDE.md에만 있어서 Claude Code
밖의 에이전트는 이 규칙을 정본 이름으로 찾지 못한다. 소유자가
2026-11-07에 루트와 하위 폴더 모두 AGENTS.md를 정본으로 정했다
(design-docs harness/01-harness-design.md 13절 Q1·Q2).

- 28개 파일을 git mv로 같은 폴더 AGENTS.md로 옮기고, 그 자리
  CLAUDE.md에는 `@AGENTS.md` 한 줄만 둔다. 이 세션에서
  src/domain-core 파일을 열자 CLAUDE.md의 가져오기가 펼쳐져
  AGENTS.md 본문이 함께 읽히는 것을 확인했다. 그래서 Claude Code는
  지금처럼 그 폴더를 만질 때 규칙을 읽는다.
- 버린 대안: 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않는다),
  CLAUDE.md 그대로 두기(다른 에이전트가 못 찾는다).
- 살아 있는 문서와 테스트 코드의 leaf 규칙 경로를 새 이름으로 바꿨다.
  기록 문서(evidence, upgrade, design, history, reviews, adr)는 쓴
  때의 경로를 그대로 둔다.
- link-check workflow(lychee)는 src/**/CLAUDE.md만 본다. 내용이
  AGENTS.md로 가면 상대 링크가 검사 밖으로 나가므로, PR마다 도는
  check-docs.py에 살아 있는 문서 전체의 상대 링크 검사를 더했다.
  workflow는 CI 재편 몫이라 고치지 않았다.
- check-work-docs.py의 이력 ID 검사도 src/**/AGENTS.md를 본다.

위험: git은 이 커밋을 "CLAUDE.md 수정 + AGENTS.md 추가"로 본다(같은
이름의 새 파일이 생겨 이름 바꾸기로 잡히지 않는다). 옛 이력은
`git log -- <폴더>/CLAUDE.md`로 본다. 코드 주석의 "CLAUDE.md"는
가져오기를 거쳐 같은 문서에 닿으므로 운영 코드는 고치지 않았다.

검증: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py,
python3 -m unittest discover -s scripts/tests 모두 rc=0. 링크 검사
시험은 검사 조건을 끈 사본에서 7건 중 3건이 실패했다.

BREAKING CHANGE: 파생 서비스의 leaf 규칙 문서 이름이 AGENTS.md로
바뀐다. 동기화 뒤 각 leaf의 CLAUDE.md는 `@AGENTS.md` 한 줄이다.
2026-11-07 21:58:12 +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
이미 있는 파일·패키지 덮어쓰지 않고 멈춘다 스크립트

생성 뒤 확인:

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