문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지 크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의 500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본 (TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR 테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로 만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져 객체 저장소 lane이 돌지 않았다. 방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은 결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD, S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한). MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자· mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고, scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과 왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와 결정은 리뷰 README 14절에 있다. 위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서 H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC· WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체, 샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개 (composition:durable-operation, adapter:inbound:messaging)와 새 마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1, grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면 실패한다(runbook에 확인 쿼리). 검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함 전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절 BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션 기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가, 샘플 Idempotency-Key 오류 코드 변경.
7.0 KiB
7.0 KiB
개발 매뉴얼 — 이 템플릿으로 기능을 만드는 순서와 판단 지점
이 매뉴얼은 새 업무 기능을 추가하는 사람이 읽는다. 무엇을 어떤 순서로 만들고, 갈림길마다 무엇을 기준으로 고르는지를 적는다. 규칙의 정본은 따로 있다. 이 매뉴얼은 그 정본을 가리키고 작업 순서로 엮을 뿐, 규칙을 다시 쓰지 않는다(아래 「정본 위치」).
판단 지점은 모두 같은 틀로 적는다.
- 고르는 기준 — 무엇을 보고 고르는가
- 기본값 — 기준이 애매하면 이것
- 예외 — 기본값을 벗어나도 되는 경우와 그때 같이 해야 하는 것
근거는 코드 경로로 단다. 경로는 저장소 루트 기준이다.
읽는 순서
처음이면 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 |