문제
docs/architecture/backend-api-and-server-state-contract.md 4.1절(JSON
envelope)과 6절(Command와 idempotency)이 백엔드 계약을 직접 다시 적었다.
짝 백엔드가 바뀐 뒤 둘이 어긋난다.
- 4.1절 예시는 meta id를 늘 싣고 null 생략 규칙이 없다.
- 6절은 같은 키·다른 본문을 409 IDEMPOTENCY_KEY_REUSED로 적는다. 백엔드는
422 IDEMPOTENT_REQUEST_MISMATCH다. 처리 중 409의 retryable·Retry-After,
400 IDEMPOTENCY_KEY_INVALID도 없다.
- 4.2절 409 행이 "idempotency fingerprint" 충돌을 409로 적는다.
백엔드 http-contract.md 5절은 이 두 절이 자기 문서를 가리켜야 한다고
적는다.
고른 방법
- 4.1절·6절의 표와 예시를 지우고 백엔드 문서 링크(1절, 2절·4절)와 기준
버전(백엔드 리뷰 2026-11-01 15절 결정, 2026-11-03)만 적는다. 백엔드
변경은 아직 커밋이 없어 SHA 대신 결정 날짜를 적고, 커밋이 생기면 SHA로
바꾸라고 적었다.
- 프론트가 그 계약을 읽는 코드 위치만 남긴다. 표를 복사하지 않는다.
- 4.2절 409 행에서 멱등성 충돌을 빼고 6절을 가리킨다.
버린 대안
- 프론트 문서의 표를 백엔드 값으로 고쳐 두기: 다음 백엔드 변경에서 다시
어긋난다.
위험·한계
- 링크는 두 repo가 같은 상위 폴더에 나란히 있을 때만 열린다
(../../../clean-architecture-backend-template/...). verify:documentation은
repo 밖 링크를 검사하지 않는다.
- 6절에서 지운 권장 IdempotencyRecord와 불변조건은 짝 백엔드가 구현과
문서로 소유한다. 다른 백엔드를 붙이는 제품은 백엔드 문서를 기준으로 삼는다.
- 4.2절의 422 행(field validation)은 그대로다. 짝 백엔드는 필드 검증
실패를 400 VALIDATION_FAILED로 보낸다(백엔드 http-contract.md 4절). 이
차이는 이 변경 범위 밖이다.
검증
- node scripts/verify-documentation-readiness.ts: PASS_SCOPED.
Refs: clean-architecture-backend-template docs/web/http-contract.md 5절, docs/reviews/2026-11-01-maturity-review/README.md 14.3