Files
clean-architecture-backend-…/docs/manual
DongHyeonka bbe944bd3c fix!: 재리뷰가 찾은 결함과 색인에서 빠졌던 발견 5건을 고친다
문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가
Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다.
@SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히
prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고,
GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로
나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역
발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다.

방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이
기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록,
@SystemInvoked bean은 기동 실패, complete 단계 실패는
IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도
SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도
행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도
내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제
지표(redis.lane.*) 기준으로 고쳤다.

위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이
브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류
디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어
파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은
기동을 막는다. httpclient failure-injection lane의 main 단계 중복
실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci
integrationCheck performanceCheck, :performanceCheck, :releaseCheck
(-PgitRevision), verify-compose-profile-contracts(18 lane) 통과.
첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event
id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절
BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호
첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드
IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은
static·의존 없음이어야 한다.
2026-11-03 23:29:35 +09:00
..

개발 매뉴얼 — 이 템플릿으로 기능을 만드는 순서와 판단 지점

이 매뉴얼은 새 업무 기능을 추가하는 사람이 읽는다. 무엇을 어떤 순서로 만들고, 갈림길마다 무엇을 기준으로 고르는지를 적는다. 규칙의 정본은 따로 있다. 이 매뉴얼은 그 정본을 가리키고 작업 순서로 엮을 뿐, 규칙을 다시 쓰지 않는다(아래 「정본 위치」).

판단 지점은 모두 같은 틀로 적는다.

  • 고르는 기준 — 무엇을 보고 고르는가
  • 기본값 — 기준이 애매하면 이것
  • 예외 — 기본값을 벗어나도 되는 경우와 그때 같이 해야 하는 것

근거는 코드 경로로 단다. 경로는 저장소 루트 기준이다.

읽는 순서

처음이면 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