Files
clean-architecture-backend-…/docs/work
DongHyeonka 1443510638 fix(idempotency)!: 이미 적용된 전이는 그 전이를 적용한 핸들에게만 확인한다
문제: 이미 적용된 전이를 다시 보낸 호출에 Redis·PostgreSQL 저장소와
in-memory fake가 다르게 답한다.
- 같은 attempt가 넘겨받기 전 핸들로, 넘겨받은 뒤 적용된 complete를 다시
  보내면 Redis·PostgreSQL은 ALREADY_COMPLETED_SAME_RESULT, fake는 NOT_OWNER.
- 같은 경우의 markFailed는 Redis ALREADY_MARKED_SAME_OPERATION, PostgreSQL
  OPERATION_CONFLICT, fake NOT_OWNER. markFailed를 적용한 핸들이 응답을
  잃고 다시 보내면 fake만 NOT_OWNER.
- release한 핸들로 start하면 PostgreSQL은 NOT_OWNER, Redis·fake는 ABSENT.
- 같은 원인(재생 판정이 "어느 핸들이 적용했나"를 보지 않음)이 다른 전이에도
  있다. PostgreSQL은 기록된 renew·release와 digest가 다른 핸들을 모두
  OPERATION_CONFLICT로 답해, 주인이 renew가 돌려준 핸들로 다시 renew해도
  거절하고 넘겨받기 전 핸들의 renew·release도 OPERATION_CONFLICT다. fake는
  적용한 핸들이 start·renew를 다시 보내도 NOT_OWNER다.

방법: 소유자 결정(2026-11-06) 「넘겨받기 전 핸들의 재전송」「해제된 핸들로
start」대로 맞춘다. "적용한 핸들"은 owner identity가 같고 기록보다
revision이 하나 낮은 핸들이다. 라운드6에서 start에 쓴 기준을 모든 전이에
쓴다.
- Redis TRANSITION과 command fake: ALREADY 조건에서 "start가 아니면 아무
  핸들" 분기를 지우고 rev == handle rev + 1만 남긴다. 다른 핸들은 revision
  검사로 내려가 NOT_OWNER·WRONG_STATE.
- PostgreSQL: replayVerdict가 적용한 핸들일 때만 재생(같은 digest → 이미
  처리됨, 다른 digest → OPERATION_CONFLICT)으로 읽는다. 다른 핸들은 owner
  검사로 내려가 NOT_OWNER. complete 재생 판정도 owner token 대신 적용한
  핸들을 본다.
- fake: 마지막으로 적용한 전이와 그 핸들·인자(renew lease, fail disposition)
  를 기억해 start·renew·complete·markFailed 재전송에 저장소와 같게 답한다.
- release한 핸들의 start는 계약이 ABSENT·NOT_OWNER를 둘 다 받고 포트
  Javadoc(IdempotencyStartOutcome)에 적는다. 코드 동작은 그대로.
버린 대안: PostgreSQL complete·fail 재생을 전이 digest 비교만으로
하기(complete digest에 replay TTL이 들어가 같은 결과·다른 TTL 재전송이
RESPONSE_CONFLICT가 된다), Redis를 원래 주석 의도대로 두고 fake·PostgreSQL을
"operation의 아무 핸들"로 넓히기(소유자 결정과 반대, 넘겨받기 전 핸들이 남의
결과를 자기 것으로 확인받는다), 재생 핸들을 attempt만으로 가리기(같은
attempt가 넘겨받으면 attempt가 올라가지만 renew 뒤의 낡은 핸들은 attempt가
같다).
공유 계약 IdempotencyStoreContract에 10케이스를 더했다. 포트 결과 enum
Javadoc 넷, application-core CLAUDE.md·README, persistence-jpa·cache-redis
README, TESTING_STRATEGY, 결정 색인, 업그레이드 안내 5절을 같이 고쳤다.

위험·한계: 템플릿의 호출자(IdempotencyExecutor)는 넘겨받기 전 핸들로 다시
보내지 않고 renew·release를 부르지 않아 HTTP 동작은 같다. store 포트를 직접
부르는 코드는 넘겨받기 전 핸들의 재전송에 NOT_OWNER를 받고, PostgreSQL에서
renew를 이어 부를 수 있게 된다. fake로 응답 유실을 흉내 내던 테스트는 이제
"이미 처리됨"을 받는다. 적용한 핸들이 markFailed를 다른 retention·disposition
으로 다시 보낼 때의 답은 저장소마다 다르고 IdempotencyFailOutcome Javadoc과도
다르다(범위 밖, 보고에 적음).

검증: desktop, 공유 잠금, 기준 73d39212.
- RED(기준 커밋 + 계약 테스트만, 로그 ~/r8-f4-red-logs/): in-memory fake
  계약 59 중 4 실패(적용한 핸들의 start·renew·markFailed 재전송,
  "expected: ALREADY_MARKED_SAME_OPERATION but was: NOT_OWNER" 등), Redis
  command fake 2·실 Redis(redisContainerContractTest) 2 실패("expected:
  NOT_OWNER but was: ALREADY_COMPLETED_SAME_RESULT"·"…ALREADY_MARKED_SAME_
  OPERATION"), 실 PostgreSQL(jpaPlatformContractTest) 5 실패(complete는
  ALREADY_COMPLETED_SAME_RESULT, markFailed·renew·release는
  OPERATION_CONFLICT, 두 번째 renew는 "expected: RENEWED but was:
  OPERATION_CONFLICT"). release한 핸들의 start 케이스는 동작 변경이 없어
  처음부터 셋 다 통과한다. lane마다 실패 수는 위 계약 실패 수와 같다.
- GREEN(이 커밋과 같은 트리 377d1232, 로그 ~/r8-f4-green-logs/): 네 leaf
  check(application-core 422·skip 19 fake 시간 케이스, persistence-jpa 664,
  cache-redis 225, redis-runtime 65), 네 leaf testQualityCheck,
  redisContainerContractTest 100, jpaPlatformContractTest 429,
  postgresqlIdempotencyIntegrationTest 10, fake를 쓰는 leaf(composition:
  idempotency check 32, redis-sdk test 310, web test 329, sample-portfolio
  test 339), documentContractTest 66 — 모두 rc=0, 실패 0.
- scripts/check-work-docs.py, git diff --check 통과.

BREAKING CHANGE: IdempotencyStorePort 구현은 이미 적용된 전이의 재전송을 그
전이를 적용한 핸들(기록보다 revision이 하나 낮은 핸들)에게만 "이미 처리됨"
으로 확인하고 다른 핸들은 NOT_OWNER로 답해야 한다. 직접 구현한 store는
IdempotencyStoreContract의 새 케이스로 확인한다.
2026-11-07 01:01:41 +09:00
..

작업 매뉴얼

이 폴더는 이 repo에서 하는 모든 일의 절차서다. 사람과 AI 세션이 같은 절차를 쓴다. 읽는 순서는 하나다: 루트 CLAUDE.md(지도) → 이 README → 맡은 일의 playbook 하나. 규칙의 정본은 AGENTS.md와 registry(src/config/architecture/modules.json)다. 이 폴더는 규칙을 다시 쓰지 않고, 일하는 순서를 정한다.

1. 어떤 playbook인가

맡은 일 playbook
새 업무 기능이나 새 capability 모듈을 만든다 new-feature.md
있는 코드를 리뷰·수정·리팩터링·최적화한다. 구조·테스트 구조를 바꾼다 improve.md
바꾸기 전에 대안을 비교하고 소유자 결정을 받는다 research-design.md
매뉴얼·안내 문서를 쓰거나 고친다 docs-writing.md
게이트를 돌린다, 릴리스한다, 파생 서비스에 템플릿 변경을 넘긴다 operate.md
큰 일을 나눠 다른 세션에 맡긴다 delegate.md

둘에 걸리면 이렇게 고른다. 결정이 먼저 필요하면 research-design이다. 동작이 바뀌는 코드가 있으면 new-feature나 improve다. 문서만 바뀌면 docs-writing이다.

2. 크기 정하기

  • 크기는 작음·중간·큼 셋이다. 정의와 크기별로 할 단계는 design-docs conventions/work-thinking-order.md 2절이 정본이다.
  • 요약: 작음은 파일 몇 개·새 결정 없음·되돌리기 쉬움, 중간은 leaf(또는 문서 폴더) 하나 안의 여러 파일이나 소유자 없이 정할 작은 결정 하나, 큼은 새 체계·아키텍처·공개 계약·소유자 결정이 필요한 일이다.
  • brief(작업 지시문)에 크기가 있으면 그대로 한다. 올릴 수는 있고 내릴 수는 없다. 올리면 이유를 보고에 쓴다.
  • brief가 없으면 스스로 정한다. 망설여지면 큰 쪽이다.
  • 이 repo에서 "경계"는 registry의 leaf 하나다. 파일 수가 아니라 바뀌는 경계와 영향으로 정한다.
  • 아래는 파일이 하나여도 큼이다: 공개 계약(HTTP wire 계약 docs/web/http-contract.md, 오류 코드 레지스트리, API surface 스냅숏, env 키), 파생 서비스가 따라 고쳐야 하는 변경, 새 leaf, 보안 정책.
  • 큰 일은 만들기 전에 멈추고 소유자 검토를 받는다(research-design.md).

3. 모든 작업의 공통 단계

  1. 기준 커밋을 고정한다. git rev-parse HEAD를 산출물과 보고에 적는다.
  2. 이미 정한 것을 읽는다: reference/decisions.md, docs/reviews/에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다.
  3. 소유 leaf를 찾는다. registry의 source_path로 정하고, 가장 가까운 src/**/CLAUDE.md를 읽는다.
  4. 스킬을 고른다. 정본은 AGENTS.md 「Superpowers Workflow」다. playbook에 작업별 스킬이 있다.
  5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다.
  6. 무거운 실행(Gradle, Docker, 테스트, 게이트)은 operate.md 「실행 위치」대로 한다.
  7. 일이 다른 leaf·계층이나 brief 범위를 넘어야 하면 거기서 멈추고 묻는다(5절).
  8. 완료를 말하기 전에 검증한다(superpowers:verification-before-completion). 돌리지 못한 검증은 못 돌렸다고, 이유와 함께 쓴다(HARD-STOP 6).

4. 커밋

  • 기본 정책은 human-only다(AGENTS.md). 에이전트는 stage·commit·amend·push하지 않는다.
  • 예외는 하나다. brief 7절이 허용한 것만 그 작업의 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 커밋만 허용됐으면 push하지 않는다(desktop 검증은 operate.md 4.1절 「push 전에 검증하기」).
  • 그때도 main 병합, main·다른 브랜치 push, force push, PR 병합은 하지 않는다. 그것은 소유자가 한다.
  • 메시지 형식은 design-docs conventions/commit-and-pr.md를 따른다. AI 꼬리말과 자리표시자(TBD, TODO, 채우지 않은 칸)를 넣지 않는다.

5. 막혔을 때

  • 소유자만 정할 수 있는 것(공개 계약, 파생 서비스 동작, 보안 정책, 새 leaf, 되돌리기 비싼 선택)은 근거와 권하는 안을 붙여 한 번 묻고, 그 항목만 멈춘다.
  • brief를 준 쪽이 있으면 그쪽에 묻는다. 없으면 소유자에게 묻는다.
  • 묻는 형식: 항목 · 선택지 · 권하는 안과 이유 · 정할 사람.

6. 보고

  • 맨 앞에 결과(완료 / 부분 / 못 함)와 브랜치·커밋을 쓴다.
  • 그다음 변경, 확인(명령 · 실행 위치 · rc · 로그 경로), 범위 밖에서 본 것(위치와 내용, 고치지 않음), 남은 문제를 쓴다. 남은 문제를 숨기지 않는다.
  • 보고는 쉬운 한국어로 쓴다. 코드·명령·로그 인용만 원문 그대로 둔다.
  • 숫자(테스트 수, 실패 수, 태스크 이름)는 로그에서 옮긴다. 기억으로 쓰지 않는다.
  • 사고 순서 흔적 칸을 둔다(conventions/work-thinking-order.md 3절). 다른 세션이 맡긴 일이면 design-docs conventions/delegation-loop.md 5절 양식을 쓴다.

7. 필요할 때만 읽는 문서

문서 내용
reference/gates.md 게이트 목록, 바꾼 것에 맞는 게이트, 결과 기록 형식, 거짓 통과 막기
reference/review-criteria.md 결함 정의, 심각도, 증거·통제 수준, 점검 항목, 리뷰 문서 양식
reference/defect-patterns.md 반복해서 나온 결함의 모양과 막는 기준
reference/decisions.md 이미 정한 결정의 색인, 결정을 다시 여는 조건과 기록하는 법
evidence.md 이 매뉴얼의 규칙이 나온 사건과 지난 리뷰 ID

8. 이 폴더를 고칠 때

  • 분량 상한: 지도 120줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + README + playbook 하나) 350줄. reference/는 상한이 없다.
  • 본문에 지난 리뷰 ID·묶음 이름·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 evidence.md로 옮긴다.
  • 고친 뒤 python3 scripts/check-work-docs.py가 통과해야 한다. 절차는 docs-writing.md다.