# 새 기능 — 업무 기능과 capability 모듈 만들기 이 playbook은 입구다. 만드는 순서와 판단 지점은 개발 매뉴얼 [`docs/manual/`](../manual/README.md)이 정본이다. 여기에는 크기, 완료 기준, 하지 말 것만 더한다. ## 1. 언제 쓰나 - 새 업무 기능(도메인 개념, 유스케이스, endpoint)을 더할 때. - 새 capability 모듈(의존성 한 줄로 켜지는 부가 기능)을 만들 때. - 아니면 다른 playbook이다. - 있는 기능의 결함·구조를 고친다 → [improve.md](improve.md) - 어디에 둘지, 어떤 저장소를 쓸지 같은 결정이 먼저 필요하다 → [research-design.md](research-design.md) - 있는 capability를 켜거나 끈다(`runtimeOnly` 한 줄) → 이 playbook의 4절 3단계에서 `docs/manual/10-capabilities.md`만 따른다 ## 2. 받아야 할 것 - 기능 이름(PascalCase, 예: `Invoice`)과 경로 이름이 규칙대로 안 될 때의 경로(`--path`). - 요구사항: 무엇을 저장하나, 누가 호출하나, 어떤 권한인가, 재전송될 수 있는 쓰기인가. - 저장소 선택(어떤 persistence leaf, 마이그레이션 번호대). 서비스마다 달라 사람이 정한다(`docs/manual/04-persistence.md`). brief에 없으면 묻는다. - 공개 계약(HTTP 경로, 오류 코드, env 키)을 새로 만드는지. 만들면 크기는 큼이다. - 기준 커밋, 브랜치, 커밋 허용 여부. ## 3. 크기와 사고 순서 - 업무 기능 하나는 보통 중간이다: 계층 leaf 여러 곳에 파일이 생기지만 판단은 매뉴얼이 정해 둔 범위 안이다. - 큼: 새 capability 모듈, 새 leaf, 새 공개 계약, 파생 서비스가 따라 고쳐야 하는 변경. 큰 일은 설계와 소유자 검토가 먼저다([research-design.md](research-design.md)). - 선행 사례는 생성 명령의 출력 하나다. `src/sample-portfolio`는 개별 기법(조건부 PATCH, 페이지, outbox, DB 유일 제약)의 참고일 뿐 배치를 따라 하지 않는다. - 스킬: 설계가 바뀌면 `superpowers:brainstorming`, 여러 단계면 `superpowers:writing-plans`, 구현은 `superpowers:test-driven-development`. ## 4. 절차 1. `docs/manual/README.md`를 읽는다. 처음이면 01 → 02 → 03장을 읽는다. 2. 배치를 정한다(`docs/manual/03-placement.md`). 기본은 계층 leaf 안 `` 패키지다. 이름이 템플릿 패키지(`src/application-core/CLAUDE.md` 「Package ownership」)와 겹치지 않는지 본다. 3. capability 모듈이면 `docs/manual/10-capabilities.md`와 `AGENTS.md` 「부가 기능(capability) 모듈 규칙」의 완료 기준 7개를 먼저 읽는다. 새 leaf가 생기면 [reference/review-criteria.md](reference/review-criteria.md) 「leaf 변경 체크리스트」를 따른다. 4. 뼈대를 만든다: `scripts/new-feature.sh `(`docs/manual/01-generator.md`). 이 명령은 끝에 Gradle `spotlessApply`를 돈다. 노트북에서는 `--no-format`으로 파일만 만들고, 포맷은 desktop에서 `./gradlew spotlessApply`로 한다([operate.md](operate.md) 「실행 위치」). 5. `docs/manual/02-new-feature.md`의 순서대로 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립. 안쪽부터 만들면 각 단계가 앞 단계만 보고 컴파일된다. 6. 기능에 필요한 장만 더 읽는다: 저장(04), 재시도될 쓰기(05), 오류(06), 권한(07), 테스트 배치(08), 이벤트(09). 7. 동작은 테스트를 먼저 쓴다. 포트마다 fake 하나와 공유 계약(`XxxRepositoryContract`)을 포트 소유 leaf의 `testFixtures`에 두고, 실제 adapter도 같은 계약을 실 DB lane에서 상속한다. 8. 건드린 leaf마다 `check`, 경계를 넘었으면 `architectureCheck`, 바뀐 표면의 검사를 desktop에서 돌린다([reference/gates.md](reference/gates.md) 2절). 9. `docs/manual/11-checklist.md`를 한 줄씩 확인한다. 10. 매뉴얼과 코드가 다른 곳을 찾았으면 매뉴얼을 고치는 변경을 따로 낸다(정본이 맞다). ## 5. 완료 기준 - `docs/manual/11-checklist.md`의 항목이 모두 참이다. 아닌 항목은 이유를 보고에 적었다. - 건드린 leaf의 `check`와 `architectureCheck`가 desktop에서 rc=0이다. 로그 경로가 보고에 있다. - 공개 경로·env 키·의존성을 바꿨으면 `verifyPublicPathSnapshot`·`:app-bootstrap:verifyEnvKeys`·`verifyDependencyLocks`가 rc=0이다. - 저장 adapter가 있으면 공유 계약을 실 DB lane에서 상속하고, 그 lane이 어떤 단계에 속한다(`verifyStrictLaneStages --dry-run`). - capability 모듈이면 완료 기준 7개가 모두 참이고, 모듈 README에 세 가지(제공하는 것, 추가할 한 줄, 필요한 env 키)가 있다. - 생성 명령의 템플릿이나 패키지 규칙을 바꿨으면 `verifyFeatureScaffold`가 통과한다. ## 6. 하지 말 것 - `AGENTS.md` HARD-STOP을 어기지 않는다. 특히 controller가 repository를 부르거나, inbound DTO가 application으로 들어가거나, 업무 규칙이 mapper·filter·설정에 들어가는 것. - `src/sample-portfolio`의 배치(한 leaf에 모든 계층)를 따라 하지 않는다. onboarding 테스트 fixture도 따라 하지 않는다. - 업무 코드를 템플릿 패키지에 넣지 않는다. - 저장 adapter를 `persistence-jpa` leaf 안에 만들지 않는다. 서비스 전용 persistence leaf에 둔다. - 한 단계가 다른 leaf나 계층을 고쳐야 하면 범위를 조용히 넓히지 않는다. 거기서 멈추고 설계를 다시 본다(7절). - bootstrap에 capability 이름·스위치 목록·scan 정규식을 넣지 않는다. 모듈이 자기 `AutoConfiguration.imports`로 켜진다. - 노트북에서 Gradle을 돌리지 않는다. ## 7. 막혔을 때 - 저장소 선택, 공개 계약, 권한 매핑처럼 매뉴얼이 "사람이 정한다"고 한 것은 근거와 권하는 안을 붙여 한 번 묻고 그 부분만 멈춘다([README](README.md) 5절). - 매뉴얼의 판단 지점이 이 기능에 맞지 않으면(기본값도 예외도 해당 없음) 멈추고 묻는다. 새 판단 지점은 매뉴얼에 더할 후보로 보고한다. ## 8. 보고 형식 [README](README.md) 6절에 더해 적는다. - 만든 기능과 배치: leaf별 패키지와 주요 타입. - 읽은 매뉴얼 장과 그 장에서 고른 기본값·예외. - 정한 것(소유자 확인 대상): 경로, 권한 이름, 오류 코드, 마이그레이션 번호. - 11장 체크리스트 결과: 참이 아닌 항목과 이유. ## 9. 자주 하는 실수 - 샘플을 베껴 한 leaf에 모든 계층을 둔다. 생성 명령의 출력을 따른다. - 생성 명령을 노트북에서 기본 옵션으로 돌려 Gradle이 노트북에서 돈다. `--no-format`을 쓴다. - 역할 → 권한 매핑을 빠뜨려 쓰기 API가 모든 요청에 403이다. `docs/manual/07-authorization.md`를 본다.