문제: 확인 리뷰들이 찾은 Minor와 "남음" 항목을 고치지 않고 기록만 했다. 그중 동작에 닿는 것이 여럿이었다. verifyStrictLaneStages가 `./gradlew ci || true`, `| tee`, `if ./gradlew …` 같은 실패를 막지 못하는 명령을 실행으로 세는 거짓 통과, Redis 멱등 저장소가 lease가 지난 CLAIMED의 시작을 받아 주던 것(PostgreSQL은 거절), gRPC가 INTERNAL_ERROR 실패를 아무 데도 남기지 않고 STOMP가 SQL 원인까지 로그에 쓰던 것, 잠금 대기 검사기가 Flyway가 트랜잭션 밖에서 돌리는 VACUUM FULL을 몰라 통과시키던 것, 템플릿 패키지 목록과 버전 판정 정규식이 두 곳에 갈라져 있던 것. 방법: 영역별 4묶음이 실패 테스트를 먼저 확인하고 고쳤다(재리뷰 README 16절). - workflow run 스크립트를 bash 문법으로 읽고, 실패를 막지 못하는 명령과 셸이 실행하지 않는 줄의 cd는 이유를 대며 세지 않는다. - 두 멱등 저장소가 lease가 지난 시작을 LEASE_EXPIRED로 거절하고, executor는 아무것도 실행하지 않았으므로 503으로 답한다. - web·GraphQL·gRPC·STOMP가 shared-contract ServerFailureLog로 같은 실패 로그 줄을 쓴다(persistence 실패는 분류만). - @SystemCaller 규칙이 인터페이스로 주입한 경로도 보고, 조립 설정은 사용자 전송으로 세지 않는다. - 갈라진 복사본은 하나로: 템플릿 패키지 표가 정본이고 클래스를 대조하며, 버전 판정 코드는 grpc 빌드가 Sync로 가져와 컴파일한다. - httpclient 장애 주입 lane이 main 단계에서 두 번 돌던 것을 한 번으로. - 게이트에서 드러난 httpclient drain 스레드 경쟁: close()가 스레드를 join하고, 런타임이 닫기를 거부해도 drain 스레드를 먼저 멈춘다. 위험·한계: 목록에 넣지 않은 새 템플릿 패키지는 기능 패키지와 구별할 수 없다(문서화). 서브셸·eval·source 안의 cd 뒤 명령과 `|| exit 1`은 세지 않는다 (거짓 실패 쪽). Gradle 옵션 판독은 Gradle 9.0 동작을 TestKit으로 고정했다. 검증: 첫 ci가 httpclient ClientRuntimeRegistryTest 1건으로 실패(기존 코드의 drain 스레드 경쟁, README 16.1절) — 고친 뒤 ci 재실행 통과. 두 빌드 verifyStrictLaneStages, mainCheck, :integrationCheck, -p optional-platforms ci integrationCheck performanceCheck, :performanceCheck, :releaseCheck, compose 18 lane 통과. httpclient check·testQualityCheck·failure injection·performance lane을 수정 뒤 다시 돌려 통과. Refs: docs/reviews/2026-11-03-rereview/README.md 16절 BREAKING CHANGE: 멱등 저장소 시작·renew 결과에 LEASE_EXPIRED가 생겼고, lease가 지난 시작은 503 IDEMPOTENCY_UNAVAILABLE이다. verifyStrictLaneStages가 실패를 막지 못하는 workflow 명령을 세지 않는다.
개발 매뉴얼 — 이 템플릿으로 기능을 만드는 순서와 판단 지점
이 매뉴얼은 새 업무 기능을 추가하는 사람이 읽는다. 무엇을 어떤 순서로 만들고, 갈림길마다 무엇을 기준으로 고르는지를 적는다. 규칙의 정본은 따로 있다. 이 매뉴얼은 그 정본을 가리키고 작업 순서로 엮을 뿐, 규칙을 다시 쓰지 않는다(아래 「정본 위치」).
판단 지점은 모두 같은 틀로 적는다.
- 고르는 기준 — 무엇을 보고 고르는가
- 기본값 — 기준이 애매하면 이것
- 예외 — 기본값을 벗어나도 되는 경우와 그때 같이 해야 하는 것
근거는 코드 경로로 단다. 경로는 저장소 루트 기준이다.
읽는 순서
처음이면 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(요약은 CLAUDE.md) |
| leaf 목록·허용 의존 | src/config/architecture/modules.json |
| 이름 규칙(유스케이스·포트·command·query) | src/application-core/CLAUDE.md 「Naming convention」. 기계 검사는 src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/NamingConventionTest.java와 ApplicationBoundaryArchitectureTest.java |
| 유스케이스 모양·트랜잭션 모양 | src/application-core/CLAUDE.md 「Canonical use case shape」「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개 | AGENTS.md 「부가 기능(capability) 모듈 규칙」 |
이름 규칙은 위 한 곳에만 둔다. 이 매뉴얼과 생성 명령은 그 규칙을 따른 결과를 보여 줄 뿐이고,
규칙 문장을 복사하지 않는다. 생성 명령의 템플릿(scripts/feature-scaffold/templates/)이 규칙과
어긋나면 scripts/verify-feature-scaffold.sh가 ArchUnit으로 잡는다.
따라 할 예시는 하나
예시가 셋(sample-portfolio 수직, onboarding fixture, durable operation)이라 어느 것을 베끼느냐에 따라 배치가 달라졌다(리뷰 2026-11-01 01-01·07-09). 이제 새 업무 기능의 예시는 생성 명령의 출력 하나다.
| 코드 | 역할 | 따라 하나 |
|---|---|---|
scripts/new-feature.sh 출력 |
계층 leaf에 나눈 업무 기능 | 이것을 따른다 |
src/sample-portfolio |
한 leaf에 모든 계층을 둔 지울 수 있는 샘플. 개별 기법(조건부 PATCH, 페이지, outbox, DB 유일성 제약)의 참고 | 기법만 본다. 배치는 따르지 않는다 |
src/app-bootstrap/src/test/java/dev/caskeleton/onboarding/** |
ArchUnit 규칙이 새 기능 모양에 적용되는지 확인하는 테스트 fixture | 따르지 않는다 |
application-core/.../operation + DurableOperationAutoConfiguration(composition:durable-operation) |
템플릿 플랫폼 기능 | 조립 모양(@ConditionalOnBean + 유스케이스 @Bean)만 본다 |
1라운드 수정으로 생긴 패턴 (리뷰 README 13절)
리뷰 뒤 1라운드에서 굳은 모양이다. 각 장에 반영했다.
| 패턴 | 근거 코드 | 장 |
|---|---|---|
| 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로 변환 | src/sample-portfolio/src/main/resources/db/sample-migration/V8_1__poster_title_unique.sql, PosterRepositoryAdapter |
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, 번호는 운영과 겹치지 않게 | SamplePostgreSqlPersistenceConfig, V8_1__… |
04 |
| 재시도 가능한 broker 거부는 DEAD가 아니라 재시도 | docs/runbooks/outbox-dead-letter.md |
09 |