문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
7.0 KiB
7.0 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. 절차
docs/manual/README.md를 읽는다. 처음이면 01 → 02 → 03장을 읽는다.- 배치를 정한다(
docs/manual/03-placement.md). 기본은 계층 leaf 안<feature>패키지다. 이름이 템플릿 패키지(src/application/core/README.md「패키지 소유 (Package ownership)」)와 겹치지 않는지 본다. - capability 모듈이면
docs/manual/10-capabilities.md의 완료 기준 7개를 먼저 읽는다. 새 leaf가 생기면 reference/review-criteria.md 「leaf 변경 체크리스트」를 따른다. - 뼈대를 만든다:
scripts/new-feature.sh <FeatureName>(docs/manual/01-generator.md). 이 명령은 끝에 GradlespotlessApply를 돈다. 노트북에서는--no-format으로 파일만 만들고, 포맷은 desktop에서./gradlew spotlessApply로 한다(operate.md 「실행 위치」). docs/manual/02-new-feature.md의 순서대로 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립. 안쪽부터 만들면 각 단계가 앞 단계만 보고 컴파일된다.- 기능에 필요한 장만 더 읽는다: 저장(04), 재시도될 쓰기(05), 오류(06), 권한(07), 테스트 배치(08), 이벤트(09).
- 동작은 테스트를 먼저 쓴다. 포트마다 fake 하나와 공유 계약(
XxxRepositoryContract)을 포트 소유 leaf의testFixtures에 두고, 실제 adapter도 같은 계약을 실 DB lane에서 상속한다. - 건드린 leaf마다
check, 경계를 넘었으면architectureCheck, 바뀐 표면의 검사를 desktop에서 돌린다(reference/gates.md 2절). docs/manual/11-checklist.md를 한 줄씩 확인한다.- 매뉴얼과 코드가 다른 곳을 찾았으면 매뉴얼을 고치는 변경을 따로 낸다(정본이 맞다).
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.mdHARD-STOP을 어기지 않는다. 특히 controller가 repository를 부르거나, inbound DTO가 application으로 들어가거나, 업무 규칙이 mapper·filter·설정에 들어가는 것.- 한 leaf에 모든 계층을 두지 않는다. onboarding 테스트 fixture도 따라 하지 않는다.
- 업무 코드를 템플릿 패키지에 넣지 않는다.
- 저장 adapter를
persistence-jpaleaf 안에 만들지 않는다. 서비스 전용 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를 본다.