leaf 지역 규칙(src/**/AGENTS.md)은 그 폴더 파일을 열 때마다 통째로
읽힌다. Claude Code 공식 권장은 지침 파일마다 200줄 이하인데,
persistence-jpa 357줄, application-core 337줄, graphql 218줄이었다. 총괄이
2026-11-07에 상한 200을 검사에 넣고 셋을 줄이기로 정했다(소유자 결정
「자료대로 해 본다」의 방향).
- 참조 표, 계약 세부, 설계 근거를 절 단위로 그 leaf README 끝 「지역
규칙에서 옮긴 표와 계약」으로 옮겼다(내용 그대로, 제목 한 단계 내림).
지역 규칙의 같은 자리에는 README 절을 가리키는 줄과 그 폴더를 고칠 때
지킬 규칙 몇 줄을 남겼다.
- application-core: 계약 타입, 패키지 소유 표, 정해진 유스케이스 모양,
멱등성(KEYED) → 337줄에서 190줄.
- persistence-jpa: Spring 조립 소유, 플랫폼 lane, vendor 고르기,
TransactionPort 모드표, 영속 실패 번역(SQLState 표), 영속 감사 → 357줄에서
194줄.
- graphql: 구현된 플랫폼 범위 등급 표 → 218줄에서 185줄.
- 템플릿 패키지 목록의 정본이 src/application-core/README.md로 옮겨 가서
TemplatePackageOwnershipDocumentTest가 그 파일을 읽는다. 표를 머리 줄로
찾고 단언은 그대로다. 옛 경로를 읽으면 표가 없어 실패한다(옮긴 뒤
AGENTS.md에 표 머리 줄 없음, README에 둘 다 있음을 확인했다). 그 표를
가리키는 테스트 주석·실패 메시지와 매뉴얼·리뷰 기준·스킬의 참조도 바꿨다.
- persistence-jpa README가 계약 표의 정본을 AGENTS.md라고 적던 줄 넷을 새
자리로 고쳤다. 그중 「세 템플릿 모두 isolation을 READ_COMMITTED로 고정」은
코드(`SpringTransaction`: pool에 고정, template은 기본값)와 달라 코드에
맞췄고, AGENTS.md에 없던 분산 락 provider 선택표 포인터는 실제 설정 코드
`lock/DistributedLockPersistenceConfig`로 바꿨다.
- check-work-docs.py: src/**/AGENTS.md 200줄 상한(시험 둘). RolePermission
PolicyTest 주석의 옛 절 이름을 새 규칙 파일로 바꿨다.
위험: 운영 코드 주석 넷(persistence-jpa failure·transaction)은 "CLAUDE.md의
표"를 가리킨다. 업무 코드라 고치지 않았다. CLAUDE.md → AGENTS.md → README
포인터로 닿는다. persistence-jpa README는 V1이 70~72줄을 고친다. 이 커밋은
그 범위를 건드리지 않는다.
검증: check-work-docs(가장 긴 지역 규칙 194/200), check-docs, unittest rc=0.
상한 검사를 끈 사본과 상한을 400으로 올린 사본에서 시험이 실패했다. Java
변경은 최종 트리에서 desktop documentContractTest·ci로 돌린다.
BREAKING CHANGE: 세 leaf의 표가 README로 옮겨 갔다. docs/upgrade/
2026-11-harness.md 2절 8행.
개발 매뉴얼 — 이 템플릿으로 기능을 만드는 순서와 판단 지점
이 매뉴얼은 새 업무 기능을 추가하는 사람이 읽는다. 무엇을 어떤 순서로 만들고, 갈림길마다 무엇을 기준으로 고르는지를 적는다. 규칙의 정본은 따로 있다. 이 매뉴얼은 그 정본을 가리키고 작업 순서로 엮을 뿐, 규칙을 다시 쓰지 않는다(아래 「정본 위치」).
입구는 작업 매뉴얼의 새 기능 playbook이다. 일의 크기, 완료 기준, 하지 말 것은 거기에 있다. 새 기능이 아닌 일(개선, 조사·설계, 문서, 운영)은 docs/work/가 맡는다.
판단 지점은 모두 같은 틀로 적는다.
- 고르는 기준 — 무엇을 보고 고르는가
- 기본값 — 기준이 애매하면 이것
- 예외 — 기본값을 벗어나도 되는 경우와 그때 같이 해야 하는 것
근거는 코드 경로로 단다. 경로는 저장소 루트 기준이다.
읽는 순서
처음이면 1 → 2 → 3을 읽고 생성 명령을 한 번 돌려 본다. 그다음은 기능에 필요한 장만 읽는다.
| 장 | 언제 읽나 |
|---|---|
| 01. 생성 명령 | 새 기능 뼈대를 만들 때. 무엇을 만들고 무엇을 안 만드는지 |
| 02. 새 도메인·유스케이스 추가 | 기능 하나를 domain → application → outbound → inbound → bootstrap 순서로 만들 때 |
| 03. 새 기능을 둘 곳 고르기 | 계층 leaf 안 패키지 / application-* capability / 별도 수직 중 고를 때 |
| 04. 영속성 | 저장 adapter, 엔티티 매핑, DB 제약과 충돌 변환, 마이그레이션 번호 |
| 05. 멱등성·결과 불명 | 재시도될 수 있는 쓰기, 409/422, DB_COMPLETION_UNKNOWN |
| 06. 오류 모델 | 실패를 클라이언트 탓/서버 탓으로 나누고 코드로 내보낼 때 |
| 07. 권한 | @RequiresPermission, 역할 매핑, 객체 단위 인가 |
| 08. 테스트 작성 규칙 | 포트당 fake, 공유 계약, 이름·주석, lane 단계 지정 |
| 09. outbox·이벤트 | 저장과 함께 이벤트를 내보낼 때 |
| 10. capability 추가·제거 | JPA·Redis·Kafka 같은 부가 기능을 켜고 끌 때 |
| 11. 체크리스트 | PR 올리기 전 |
| 부록. 공통 원칙 후보 | 프론트·백엔드 공통 실무 원칙으로 옮길 후보 |
정본 위치
매뉴얼과 정본이 다르면 정본이 맞다. 매뉴얼을 고친다.
| 무엇 | 정본 |
|---|---|
| 계층 경계·금지 규칙 | AGENTS.md와 가장 가까운 src/**/AGENTS.md |
| 테스트 작성 규칙 | .claude/rules/java-tests.md |
| leaf 목록·허용 의존 | src/config/architecture/modules.json |
| 이름 규칙(유스케이스·포트·command·query) | src/application-core/AGENTS.md 「Naming convention」. 기계 검사는 src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java와 ApplicationBoundaryArchitectureTest.java |
| 유스케이스 모양·트랜잭션 모양 | src/application-core/README.md 「정해진 유스케이스 모양 (Canonical use case shape)」, src/application-core/AGENTS.md 「허용하는 트랜잭션 모양 (Allowed transactional shapes)」 |
| HTTP wire 계약(Envelope·멱등성 응답) | docs/web/http-contract.md |
| 운영 오류 코드 | docs/registries/error-codes.yaml, src/shared-contract/src/main/java/dev/caskeleton/shared/error/OperationalError.java |
| 엔티티 매핑·마이그레이션 | docs/jpa/entity-mapping-guide.md, docs/jpa/migration-guide.md, docs/jpa/transaction-guide.md |
| capability 완료 기준 7개 | 10-capabilities.md |
이름 규칙은 위 한 곳에만 둔다. 이 매뉴얼과 생성 명령은 그 규칙을 따른 결과를 보여 줄 뿐이고,
규칙 문장을 복사하지 않는다. 생성 명령의 템플릿(scripts/feature-scaffold/templates/)이 규칙과
어긋나면 scripts/verify-feature-scaffold.sh가 ArchUnit으로 잡는다.
따라 할 예시는 하나
예시가 셋(한 leaf에 모든 계층을 둔 샘플 모듈, onboarding fixture, durable operation)이라 어느 것을 베끼느냐에 따라 배치가 달라졌다(2026-11-01 성숙도 리뷰). 이제 새 업무 기능의 예시는 생성 명령의 출력 하나다. 샘플 모듈은 2026-11-07에 지웠다.
| 코드 | 역할 | 따라 하나 |
|---|---|---|
scripts/new-feature.sh 출력 |
계층 leaf에 나눈 업무 기능 | 이것을 따른다 |
src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/** |
ArchUnit 규칙이 새 기능 모양에 적용되는지 확인하는 테스트 fixture | 따르지 않는다 |
application-core/.../operation + DurableOperationAutoConfiguration(composition:durable-operation) |
템플릿 플랫폼 기능 | 조립 모양(@ConditionalOnBean + 유스케이스 @Bean)만 본다 |
리뷰 뒤 첫 수정으로 생긴 패턴
2026-11-01 성숙도 리뷰 뒤 같은 날 한 첫 수정에서 굳은 모양이다. 각 장에 반영했다.
| 패턴 | 근거 코드 | 장 |
|---|---|---|
| Envelope는 null 필드를 내보내지 않는다 | docs/web/http-contract.md 1절 |
06 |
처리 중 409 IDEMPOTENT_IN_FLIGHT는 retryable=true + Retry-After: 2, 같은 키로 재전송 |
docs/web/http-contract.md 2절 |
05 |
커밋 중 연결이 끊기면 재시도 가능이 아니라 결과 불명(DB_COMPLETION_UNKNOWN, 500) |
src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/failure/PersistenceExceptionTranslator.java, docs/adr/ADR-JPA-003-completion-unknown.md |
05 |
| 중복 규칙은 조회 후 insert가 아니라 DB 유일성 제약, 위반은 같은 409로 변환 | 04장 「중복·경쟁은 DB가 막는다」(템플릿 코드에 예 없음) | 04 |
| 여러 인스턴스가 집는 작업은 lease 있는 claim | ReconciliationJobStorePort.claimDue(application-notification) |
04 |
| 양방향 연관관계 금지를 ArchUnit으로 | JpaArchitectureRules.associationsAreMappedFromOneSideOnly() |
04 |
| store는 호출자 트랜잭션을 요구한다 | src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/CallerTransaction.java |
04 |
@RequiresPermission 검사는 인증 체인과 분리된 자동 설정 |
src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/mvc/autoconfigure/WebMethodSecurityAutoConfiguration.java |
07 |
| JWT audience 필수, 자기 client role만 | src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/JwtDecoderConfig.java, docs/runbooks/auth-audience-mismatch.md |
07 |
| strict lane은 반드시 어떤 단계에 속한다 | verifyStrictLaneStages(src/build.gradle strictLaneStages) |
08 |
| 서비스 마이그레이션은 별도 history table, 번호는 운영과 겹치지 않게 | NotificationSchemaStream(persistence-notification) |
04 |
| 재시도 가능한 broker 거부는 DEAD가 아니라 재시도 | docs/runbooks/outbox-dead-letter.md |
09 |