Files
clean-architecture-backend-…/docs/manual
DongHyeonka 1885bf8da7 fix!: 2차 재리뷰가 찾은 결함 29건을 고친다
문제: 재리뷰 수정 커밋(bbe944bd)만 다시 본 2차 재리뷰가 Important 7건,
Minor 22건을 찾았다. 결과 불명 503 뒤 같은 키를 다시 보내면 Redis
store가 lease 지난 실행을 넘겨받아 작업을 다시 돌렸다. replay TTL이
lease보다 짧으면 lease 도중 key가 사라져 같은 키가 두 번 실행됐다.
@SystemInvoked 규칙이 매뉴얼 09장의 이벤트 소비 경로까지 막았다. V22가
outbox_event에 가장 강한 잠금을 lock_timeout 없이 걸었다. prod의
fixture- 거부가 HOSTNAME 같은 비밀 아닌 값까지 막았다. 데모 허용 목록의
test·demo 프로필로 sample이 뜨지 않았다. 기동 rule bean의 @Value 필드가
조용히 null이 됐다.

방법: 영역별 4묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 9.1절이다.
- 두 멱등성 store가 같은 계약을 따른다. lease가 지난 실행 기록은 다시
  돌리지 않고 포기로 표시해 500 RECOVERY_REQUIRED로 답한다. 기록 수명은
  lease + replay TTL이고, replay-ttl < processing-lease면 기동이 실패한다.
- 사용자 transport만 @SystemInvoked use case에 닿지 못한다. 메시지
  handler·scheduler는 새 표시 @SystemCaller(reason)를 달고 use case를
  생성자에서 new로 만든다. 매뉴얼 경로를 테스트로 고정했다.
- 아직 어디에도 적용되지 않은 마이그레이션(V20·V22·알림 V11~V13·sample
  V8_1·grpc V002·V003)에 lock_timeout 5s를 넣고, 텍스트 검사기와 실 PG
  lane을 더했다. 이미 배포된 24개는 동결 목록으로 둔다.
- fixture- 검사는 비밀로 분류된 값만 본다. sample은 local·test·demo에서
  object storage를 끈다. 기동 rule bean에 주입 멤버가 있으면 모든
  프로필에서 기동이 실패한다. 리뷰어가 제안한 "static @Bean 선언 강제"는
  문제없는 등록을 막고 @Value 필드는 통과시켜서 버렸다.
- 이 수정 전에 move된 파일의 쿼터 차이를 찾는 쿼리와 재계산 SQL을
  docs/fileserver/operations.md에 적었다.

위험·한계: lease 뒤 늦게 끝난 첫 시도의 결과는 기록되지 않는다(그 요청도
500). @SystemCaller가 없는 메시지 handler, 주입 멤버가 있는 기동 rule,
working-directory 없이 ./gradlew를 부르는 workflow 명령은 파생 서비스에서
새로 실패하거나 세지지 않는다(업그레이드 안내 B-14~16·B-36·B-39).
spotbugsTestFixtures는 게이트 밖이고 기준 커밋에서도 실패하며, 새 검사기의
정규식 경고 8건이 더해졌다. 실제 CI runner 실행은 확인하지 못했다(Gitea
repo의 Actions가 꺼져 있다).

검증: ci, 두 빌드의 verifyStrictLaneStages --dry-run, mainCheck,
:integrationCheck, -p optional-platforms ci integrationCheck
performanceCheck, :performanceCheck, :releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 첫 실행 통과. 쿼터 재계산
SQL은 실 PostgreSQL 16에서 차이 2행 → 0행을 확인했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 9·9.1·10절
BREAKING CHANGE: replay-ttl < processing-lease 설정은 기동 실패, ledger
release가 claim token을 받는다, HttpBodyReadException(IOException 하위)이
본문 실패를 싣는다, 기동 rule·비밀 목록 bean의 주입 멤버 금지,
verifyStrictLaneStages가 workflow 명령의 working-directory로 빌드를 정한다.
2026-11-04 01:47:50 +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