Files
clean-architecture-backend-…/docs/work
DongHyeonka 200019aa5c fix(idempotency)!: 두 멱등 저장소가 operation id·release·inspect에 같게 답한다
문제: 같은 호출에 Redis와 PostgreSQL 저장소(와 in-memory fake)가 다르게
답한다.
- owner token이 같아도 호출이 claim과 다른 operation id를 대면 Redis는
  다섯 전이(start·renew·complete·fail·release)를 OPERATION_CONFLICT로
  거절하고 PostgreSQL·fake는 적용한다. PostgreSQL은 CAS에 핸들의 claim
  operation만 쓰고 호출의 id는 last_transition_operation_id에 적기만 한다.
- PostgreSQL complete 재생은 operation id만 보고 owner를 보지 않아, 같은
  id를 쓴 다른 attempt의 늦은 complete를 이미 적용된 완료로 확인한다.
  Redis는 NOT_OWNER.
- fake의 claim·inspect는 같은 token·다른 operation에 OwnerOperationConflict
  ·OPERATION_CONFLICT를 내지 않는다. PostgreSQL·fake의 inspect는 완료된
  기록이면 그 응답을 재생하고 Redis는 OPERATION_CONFLICT.
- 기록이 없는 release에 Redis는 ALREADY_RELEASED_SAME_OPERATION, PostgreSQL
  ·fake는 ABSENT. Redis release는 revision을 보지 않아, 같은 attempt가 claim을
  넘겨받기 전 핸들로 지금의 claim을 지운다.

방법: 소유자 결정 (a)로 PostgreSQL·fake를 Redis에 맞춘다. owner token이
같고 호출 id가 기록의 claim id와 다르면 다섯 전이 모두 OPERATION_CONFLICT,
기록은 그대로. 나머지 셋은 "거절이 안전한 쪽, 운영 호출자 경로가 안 바뀌는
쪽"으로 정했다.
- complete 재생은 같은 owner token에만 확인한다(Redis에 맞춤).
- fake claim은 진행 중 기록에 OwnerOperationConflict, inspect는 같은 token·
  다른 operation이면 상태와 상관없이 OPERATION_CONFLICT. PostgreSQL inspect도
  완료 재생보다 이 검사를 먼저 한다.
- 기록 없는 release는 셋 다 ABSENT. Redis adapter가 ABSENT를 그대로 넘기고
  RELEASE 스크립트와 command fake가 핸들 revision을 본다. release한 기록을
  지울지 남길지는 저장소 선택이라 release 재시도는 ABSENT(Redis·fake)와
  ALREADY_RELEASED_SAME_OPERATION(PostgreSQL)으로 갈리는 것을 계약이 허용한다.
버린 대안: Redis를 PostgreSQL에 맞추기(Redis에는 전이 id를 둘 필드가 없어
인자가 죽는다), PostgreSQL release를 삭제로 바꾸기(release 뒤 기록 모양은
계약이 저장소 선택으로 정해 두었다), 기록 없는 release를 셋 다
ALREADY_RELEASED로(찾지 못한 것을 성공으로 확인한다 — JPA 설계 22.2와 반대).
공유 계약 IdempotencyStoreContract에 12케이스를 더했다. 포트·결과 enum
Javadoc, persistence-jpa·cache-redis README, TESTING_STRATEGY, application-core
CLAUDE.md, 결정 색인, 업그레이드 안내 5절을 같이 고쳤다.

위험·한계: 템플릿의 호출자(IdempotencyExecutor)는 늘 claim의 id를 넘기고
release를 부르지 않아 HTTP 동작은 같다. store 포트를 직접 부르며 전이마다
다른 id를 넘기던 코드는 OPERATION_CONFLICT를 받는다. PostgreSQL 통합
테스트가 그렇게 쓰고 있어 claim의 id로 바꿨다. last_transition_operation_id
열은 이제 늘 claim_operation_id와 같다(마이그레이션은 건드리지 않음).
같은 token의 넘겨받기 전 핸들로 이미 끝난 complete·markFailed를 다시 보내는
경우는 저장소마다 답이 다르다(범위 밖, 보고에 적음).

검증: desktop, 공유 잠금, 기준 06f520e6.
- RED(기준 커밋 + 계약만): in-memory fake 계약 49 중 8 실패, Redis
  command fake 2, 실 Redis(redisContainerContractTest) 2, 실 PostgreSQL
  (jpaPlatformContractTest) 7 — 실패 메시지가 위 차이 그대로("expected:
  OPERATION_CONFLICT but was: STARTED", "expected: ABSENT but was:
  ALREADY_RELEASED_SAME_OPERATION" 등).
- GREEN(이 커밋과 같은 트리): 네 leaf check(application-core 412·skip 19
  시간 케이스, persistence-jpa 664, cache-redis 215, redis-runtime 65),
  네 leaf testQualityCheck, jpaPlatformContractTest 419,
  postgresqlIdempotencyIntegrationTest 10, redisContainerContractTest 90,
  app-bootstrap integrationTest 10, sample integrationTest 63,
  documentContractTest 65, architectureTest 228, composition:idempotency
  check 32 — 모두 rc=0, 실패·skip 0(fake 시간 케이스 19 제외).
- scripts/check-work-docs.py, --links docs, git diff --check 통과.

Refs: docs/reviews/2026-11-03-rereview/round6/02-idempotency-outbound.md Declined to judge
BREAKING CHANGE: 멱등 store 포트를 직접 부르는 코드는 전이마다 claim의
operation id(IdempotencyOwner.claimOperationId())를 넘겨야 한다. 다른 id는
OPERATION_CONFLICT다. Redis release는 기록이 없으면 ABSENT를 돌려준다.
직접 구현한 store는 IdempotencyStoreContract의 새 케이스를 통과해야 한다.
2026-11-06 22:25:45 +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가 커밋을 허용하면, 그 작업의 자기 브랜치에만 커밋하고 push한다.
  • 그때도 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다.