문제: 같은 호출에 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의 새 케이스를 통과해야 한다.
작업 매뉴얼
이 폴더는 이 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.md2절이 정본이다. - 요약: 작음은 파일 몇 개·새 결정 없음·되돌리기 쉬움, 중간은 leaf(또는 문서 폴더) 하나 안의 여러 파일이나 소유자 없이 정할 작은 결정 하나, 큼은 새 체계·아키텍처·공개 계약·소유자 결정이 필요한 일이다.
- brief(작업 지시문)에 크기가 있으면 그대로 한다. 올릴 수는 있고 내릴 수는 없다. 올리면 이유를 보고에 쓴다.
- brief가 없으면 스스로 정한다. 망설여지면 큰 쪽이다.
- 이 repo에서 "경계"는 registry의 leaf 하나다. 파일 수가 아니라 바뀌는 경계와 영향으로 정한다.
- 아래는 파일이 하나여도 큼이다: 공개 계약(HTTP wire 계약
docs/web/http-contract.md, 오류 코드 레지스트리, API surface 스냅숏, env 키), 파생 서비스가 따라 고쳐야 하는 변경, 새 leaf, 보안 정책. - 큰 일은 만들기 전에 멈추고 소유자 검토를 받는다(research-design.md).
3. 모든 작업의 공통 단계
- 기준 커밋을 고정한다.
git rev-parse HEAD를 산출물과 보고에 적는다. - 이미 정한 것을 읽는다: reference/decisions.md,
docs/reviews/에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다. - 소유 leaf를 찾는다. registry의
source_path로 정하고, 가장 가까운src/**/CLAUDE.md를 읽는다. - 스킬을 고른다. 정본은
AGENTS.md「Superpowers Workflow」다. playbook에 작업별 스킬이 있다. - 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다.
- 무거운 실행(Gradle, Docker, 테스트, 게이트)은 operate.md 「실행 위치」대로 한다.
- 일이 다른 leaf·계층이나 brief 범위를 넘어야 하면 거기서 멈추고 묻는다(5절).
- 완료를 말하기 전에 검증한다(
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.md3절). 다른 세션이 맡긴 일이면 design-docsconventions/delegation-loop.md5절 양식을 쓴다.
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다.