Files
clean-architecture-backend-…/docs/work/new-feature.md
T
DongHyeonka c8db79a78f docs(work): 쌓인 매뉴얼 빈틈과 조사 문서의 매뉴얼 규칙을 한 묶음으로 넣는다
cold-read 3회차(수정 세션 넷의 빈틈 9건), 통합·배치·문서 체계·번역 세션이
「매뉴얼에서 답을 못 찾았다」고 적은 곳, 프론트 총괄 교훈 둘, design-docs
repo-structure 01·02·03의 「매뉴얼에 넣을 규칙」 중 백엔드 몫이 아직 매뉴얼에
없다. 세션마다 같은 판단을 스스로 다시 했다.

넣은 자리(항목별 표는 PR 본문):
- delegate.md: upgrade 안내 「커밋:」 줄은 총괄이 합칠 때 적는다, 두 라운드
  연속 결함이면 조사로, 병합 커밋에는 충돌 해결만, 자주 하는 실수 둘(충돌
  없음은 merge-tree로, PR 만들기 전 head 브랜치의 PR을 API로).
- improve.md: 절차 문서 결함과 대기 결함의 RED 모양, 테스트 Javadoc도 고친다,
  그 코드를 지키는 lane 찾기, 두 라운드 연속 결함이면 조사로.
- docs-writing.md: 문체·용어·언어 범위(코드 주석 제외), check-docs도 돌린다,
  이동 커밋에 참조 수정을 같이, 번역 기준(영어 절 제목, 레지스트리 yaml,
  머리말 없는 runbook, MANIFEST는 납품 당시 해시).
- operate.md 4.1: zsh 파이프 rc와 자기 실행 멈추기, runner 사실(capacity 1,
  12코어·31GB, 잠금 밖), 취약점 DB는 설치가 아니다, 형식은 나누기 전에.
- reference/gates.md: 커밋하는 수정의 lockfile, 처음 켜진 lane의 이전 실패,
  lychee·buf·trivy 공식 이미지, smoke 이미지가 이 트리에서 만들어졌음,
  원래 있던 실패 가리기(세 번), 순서 의존 재현, 공유 잠금 기다리기, 증거
  실행의 --no-build-cache, 거짓 통과 두 줄(OOM 재시작, 조건 안 set -e),
  새 7절 「workflow·검사 스크립트를 더할 때」.
- reference/review-criteria.md: 관점 2·4·9·18·20·21·23·26·27의 볼 곳과 결함,
  Important 예시, leaf 변경 체크리스트(README 다섯 칸, 문서 검사).
- reference/decisions.md: brief와 결정 원문이 다르면 원문, 취약점 DB 기본값.
- reference/terms.md(새): 영어 그대로 쓰는 말과 「개발 환경」의 뜻.
- README.md 2절(최상위 폴더는 큼), new-feature.md(테스트 환경·release/는
  leaf 안), docs/ci-cd/template-vs-consumer.md(docs-check·link-check·
  check-repo-layout은 파생 서비스도 유지), settings-and-runtime 규칙.

버린 대안: 항목마다 따로 커밋(소유자 결정: 매뉴얼 보강은 한 묶음).

위험: 정한 기본값 둘은 소유자 확인 대상이다: 취약점 DB 받기 허용,
병합 커밋에 충돌 해결만. operate.md는 143/150줄, improve.md 144/150줄로
상한에 가깝다.

검증: check-work-docs(진입 경로 최대 269/350), check-docs, unittest 모두 rc=0.
2026-11-07 22:21:04 +09:00

6.9 KiB

새 기능 — 업무 기능과 capability 모듈 만들기

이 playbook은 입구다. 만드는 순서와 판단 지점은 개발 매뉴얼 docs/manual/이 정본이다. 여기에는 크기, 완료 기준, 하지 말 것만 더한다.

1. 언제 쓰나

  • 새 업무 기능(도메인 개념, 유스케이스, endpoint)을 더할 때.
  • 새 capability 모듈(의존성 한 줄로 켜지는 부가 기능)을 만들 때.
  • 아니면 다른 playbook이다.
    • 있는 기능의 결함·구조를 고친다 → improve.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).
  • 선행 사례는 생성 명령의 출력 하나다. 개별 기법의 예시는 docs/manual/이 실제 코드(fileserver, durable operation)로 가리킨다.
  • 스킬: 이 repo의 new-feature(이 playbook의 실행 순서표), 설계가 바뀌면 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 안 <feature> 패키지다. 이름이 템플릿 패키지(src/application-core/AGENTS.md 「Package ownership」)와 겹치지 않는지 본다.
  3. capability 모듈이면 docs/manual/10-capabilities.md의 완료 기준 7개를 먼저 읽는다. 새 leaf가 생기면 reference/review-criteria.md 「leaf 변경 체크리스트」를 따른다.
  4. 뼈대를 만든다: scripts/new-feature.sh <FeatureName>(docs/manual/01-generator.md). 이 명령은 끝에 Gradle spotlessApply를 돈다. 노트북에서는 --no-format으로 파일만 만들고, 포맷은 desktop에서 ./gradlew spotlessApply로 한다(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 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·설정에 들어가는 것.
  • 한 leaf에 모든 계층을 두지 않는다. onboarding 테스트 fixture도 따라 하지 않는다.
  • 업무 코드를 템플릿 패키지에 넣지 않는다.
  • 저장 adapter를 persistence-jpa leaf 안에 만들지 않는다. 서비스 전용 persistence leaf에 둔다.
  • 한 단계가 다른 leaf나 계층을 고쳐야 하면 범위를 조용히 넓히지 않는다. 거기서 멈추고 설계를 다시 본다(7절).
  • bootstrap에 capability 이름·스위치 목록·scan 정규식을 넣지 않는다. 모듈이 자기 AutoConfiguration.imports로 켜진다.
  • 새 capability가 테스트 환경(compose, 스크립트)을 더하면 그 leaf 안에 둔다. 저장소 루트에 두지 않는다. leaf가 가진 기능 데이터(readiness card, release registry)는 그 leaf의 release/에 둔다.
  • 노트북에서 Gradle을 돌리지 않는다.

7. 막혔을 때

  • 저장소 선택, 공개 계약, 권한 매핑처럼 매뉴얼이 "사람이 정한다"고 한 것은 근거와 권하는 안을 붙여 한 번 묻고 그 부분만 멈춘다(README 5절).
  • 매뉴얼의 판단 지점이 이 기능에 맞지 않으면(기본값도 예외도 해당 없음) 멈추고 묻는다. 새 판단 지점은 매뉴얼에 더할 후보로 보고한다.

8. 보고 형식

README 6절에 더해 적는다.

  • 만든 기능과 배치: leaf별 패키지와 주요 타입.
  • 읽은 매뉴얼 장과 그 장에서 고른 기본값·예외.
  • 정한 것(소유자 확인 대상): 경로, 권한 이름, 오류 코드, 마이그레이션 번호.
  • 11장 체크리스트 결과: 참이 아닌 항목과 이유.

9. 자주 하는 실수

  • 한 leaf에 모든 계층을 둔다. 생성 명령의 출력을 따른다.
  • 생성 명령을 노트북에서 기본 옵션으로 돌려 Gradle이 노트북에서 돈다. --no-format을 쓴다.
  • 역할 → 권한 매핑을 빠뜨려 쓰기 API가 모든 요청에 403이다. docs/manual/07-authorization.md를 본다.