Files
clean-architecture-backend-…/docs/work
DongHyeonka 7535a4ca7a fix(idempotency)!: 적용한 핸들의 재전송을 전이 종류와 인자로 가린다
문제: 전이를 적용한 핸들이 그 전이를 다시 보낼 때 세 저장소가 서로, 그리고
포트 Javadoc과 다르게 답한다(재리뷰 round8 RR8-04-01·02, 같은 원인).
- markFailed를 다른 disposition으로 다시 보내면 fake·Redis·PostgreSQL 모두
  NOT_OWNER다. 기록을 남이 가져갔다는 틀린 신호이고 Javadoc은
  OPERATION_CONFLICT라고 적는다.
- retention만 다르면 fake·Redis는 ALREADY_MARKED_SAME_OPERATION, PostgreSQL은
  fail digest에 retention이 들어 있어 OPERATION_CONFLICT다.
- Redis는 start가 돌려준 핸들로 renew한 뒤 그 핸들로 start를 보내면
  ALREADY_STARTED_SAME_OPERATION으로 답한다. renew도 기록을 EXECUTING·
  revision+1로 두어 TRANSITION이 상태와 revision만으로는 start와 구별하지
  못한다. executor는 그 답에 action을 실행해 이미 도는 작업을 한 번 더
  돌린다. fake·PostgreSQL은 NOT_OWNER다.
원인은 하나다. "적용한 핸들"을 revision 하나로만 가리고 전이 종류와 인자를
같이 보지 않는다.

방법: 소유자 결정(2026-11-07, 1103 README 19.4절 ② (a))대로 다른
disposition은 OPERATION_CONFLICT, 다른 retention은 "이미 처리됨"으로 맞춘다.
retention은 complete의 replay TTL처럼 결과를 얼마나 보관하나일 뿐이라
비교하지 않는다.
- Redis: 기록 hash에 lastKind(CLAIM·START·RENEW·COMPLETE·FAIL)를 남긴다.
  TRANSITION의 재전송 판정은 "rev == 핸들 rev + 1 그리고 lastKind == 이
  전이"다. 그 안에서 상태가 목표면 ALREADY, 아니면(다른 disposition의
  실패) OPERATION_CONFLICT. claim·takeover는 CLAIM을 써 넘겨받기 전 종류가
  남지 않게 한다. 어댑터가 전이 종류를 9번째 인자로 보낸다. 명령 fake를
  같이 고친다.
- PostgreSQL: fail 재생 판정이 두 실패 종류(FAIL_RETRYABLE·FAIL_ABANDONED)를
  모두 실패의 재생으로 읽는다. fail digest에서 retention을 뺀다.
- fake: 적용한 핸들의 markFailed 재전송에 disposition이 다르면
  OPERATION_CONFLICT.
- 공유 계약 IdempotencyStoreContract에 케이스 셋(다른 retention, 다른
  disposition과 기록 유지, renew 뒤 같은 핸들의 start)을 더했다.
- PostgreSqlIdempotencyIntegrationTest의 "다른 retention은 conflict" 케이스가
  옛 동작을 고정하고 있어 결정대로 "이미 처리됨, 처음 retention 유지"로
  바꿨다(...IsConfirmedAndKeepsItsRetention).
  IdempotencyFailOutcome·IdempotencyStartOutcome·IdempotencyStorePort Javadoc,
  결정 색인 2.4절(새 행과 「넘겨받기 전 핸들의 재전송」 적용 조건),
  application-core CLAUDE.md·README, cache-redis·persistence-jpa README,
  TESTING_STRATEGY, 업그레이드 안내 5절 행을 같이 고쳤다.
버린 대안: 다른 disposition을 NOT_OWNER로 두고 Javadoc만 고치기(19.4절 ②
(b), 소유자가 고르지 않음, 적용한 핸들에 "넘겨받혔다"는 틀린 신호),
다른 retention도 OPERATION_CONFLICT(② (c), Redis 기록에 retention을 더하고
Lua를 바꿔야 하며 보관 기간을 인자로 본다), Redis start 분기만
"renewedFromRev가 있으면 ALREADY 아님"으로 막기(같은 상태에 머무는 전이가
늘면 다시 갈라진다).

위험·한계: 템플릿 호출자(IdempotencyExecutor)는 같은 인자로만 다시 보내고
renew를 부르지 않아 HTTP 동작은 같다. 포트를 직접 부르는 코드만 답이
바뀐다. 이 배포 전에 쓰인 Redis 기록에는 lastKind가 없어, 새 프로그램이
그 기록의 전이를 재전송으로 보지 않는다. 핸들은 프로세스 메모리에만 있고
같은 프로세스는 같은 프로그램을 돌리므로, 새 프로그램이 옛 프로그램이
적용한 전이의 핸들을 받는 경로는 템플릿에 없다고 본다(실행으로 확인하지
않음). PostgreSQL도 같은 이유로 옛 fail digest(retention 포함)와 새
digest를 같은 핸들로 비교하는 경로가 없다고 보고 digest VERSION을 올리지
않았다.

검증: desktop, 공유 잠금, --no-build-cache, 기준 3eb3b067.
- RED(기준 커밋 + 계약 케이스만, 로그 ~/r9-g4-red-logs/red-summary.txt):
  fake 62 중 1 실패(다른 disposition "expected: OPERATION_CONFLICT but was:
  NOT_OWNER"), Redis 명령 fake 62 중 2·실 Redis(redisContainerContractTest)
  103 중 2 실패(다른 disposition, renew 뒤 start "expected: NOT_OWNER but
  was: ALREADY_STARTED_SAME_OPERATION"), 실 PostgreSQL 62 중 2 실패(다른
  disposition, 다른 retention "expected: ALREADY_MARKED_SAME_OPERATION but
  was: OPERATION_CONFLICT").
- GREEN(이 커밋과 같은 트리 5a74698d, 로그 ~/r9-g4-green-logs/와 pass2/,
  수는 결과 XML에서 셈 test-counts.txt): 네 leaf check(application-core 426·
  skip 19 fake 시간 케이스, cache-redis 228, redis-runtime 65,
  persistence-jpa 666)와 testQualityCheck, redisContainerContractTest 103,
  jpaPlatformContractTest 432, fake를 쓰는 leaf(composition:idempotency 32,
  redis-sdk 310, web 341, sample-portfolio 339), documentContractTest 67 —
  모두 rc=0, 실패 0. postgresqlIdempotencyIntegrationTest는 1차에서 위 옛
  케이스 1건이 실패했고, 고친 뒤 pass2에서 persistence-jpa spotlessCheck·
  check·testQualityCheck와 함께 10 중 실패 0, rc=0.
- scripts/check-work-docs.py rc=0, git diff --check 통과.

BREAKING CHANGE: IdempotencyStorePort 구현은 적용한 핸들이 markFailed를 다른
disposition으로 다시 보내면 OPERATION_CONFLICT, retention만 다르면
ALREADY_MARKED_SAME_OPERATION으로 답해야 하고, renew를 적용한 핸들의 start를
"이미 시작됨"으로 확인하면 안 된다(NOT_OWNER). 직접 구현한 store는
IdempotencyStoreContract의 새 케이스로 확인한다.
2026-11-07 07:50:40 +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, 채우지 않은 칸)를 넣지 않는다.
  • 커밋 하나에 논리 변경 하나다(같은 문서 3.1절). 수정 묶음도 결함(또는 같은 원인 하나)마다 커밋을 나누고, 동작 변경을 위한 리팩터링(규칙을 상수로 빼기 등)은 앞 커밋으로 나눈다. 나눈 커밋마다 그 커밋이 바꾼 것의 검사가 통과해야 한다(operate.md 4.1절 「push 전에 검증하기」).

5. 막혔을 때

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

6. 보고

  • 맨 앞에 결과(완료 / 부분 / 못 함)와 브랜치·커밋을 쓴다.
  • 그다음 변경, 확인(명령 · 실행 위치 · rc · 로그 경로), 범위 밖에서 본 것(위치와 내용, 고치지 않음), 남은 문제를 쓴다. 남은 문제를 숨기지 않는다.
  • 보고는 쉬운 한국어로 쓴다. 코드·명령·로그 인용만 원문 그대로 둔다.
  • 숫자(테스트 수, 실패 수, 태스크 이름)는 로그에서 옮긴다. 기억으로 쓰지 않는다. 테스트 수는 성공한 Gradle 로그에 없으니 결과 XML 사본에서 센다(reference/gates.md 4절).
  • 사고 순서 흔적 칸을 둔다(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로 옮긴다. 새 세션이 처음 읽는 AGENTS.md와 src/**/CLAUDE.md도 같다. 모듈 README·설계 문서·docs/reviews/**는 ID를 둔다.
  • 이 폴더, 루트 CLAUDE.md, AGENTS.md, src/**/CLAUDE.md를 고친 뒤 python3 scripts/check-work-docs.py가 통과해야 한다. 절차는 docs-writing.md다.