api-contract-until-match

API 계약 일치까지 (API Contract Until Match)

API 응답이 OpenAPI나 JSON Schema 계약과 일치할 때까지 반복 — 문서와 구현 사이의 드리프트를 잡는다.

이 루프는 언제 쓰나

OpenAPI 스펙이나 JSON Schema로 API 계약을 정해 뒀는데, 실제 핸들러 응답이 슬그머니 스펙과 어긋나기 시작할 때 씁니다. 필드 이름이 바뀌었거나, 타입이 다르거나, 필수 필드가 빠졌거나 — 문서는 그대로인데 구현만 표류(drift)하는 상황입니다. 한 번 시작하면 에이전트가 계약 테스트 실행 → 불일치 수집 → 최소 수정 → 재실행을 스스로 반복하며 계약과 구현을 다시 맞춥니다. 핵심은 한 번에 가장 작은 변경 하나만 적용해, 핸들러의 타입·검증을 고치거나 (코드가 정답인 경우) 스펙을 바로잡는 것입니다.

루프 흐름

수동 시작 → 계약 테스트 실행 → 구현/스펙 수정 → 재실행 →〔피드백 게이트〕계약 테스트 전부 통과?
                ↑                                                       │ 아니오
                └───────────────────────────────────────────────────────┘
                                                                        │ 예
                                                                      종료

매 반복(pass)마다 하는 일

1. 계약 테스트 실행 — openapi.yaml 또는 schema fixture에 대고 계약 테스트를 돌립니다. 모든 불일치를 엔드포인트와 필드 단위로 나열합니다.

   npm run test:contract
   

2. 구현 또는 스펙 수정 — 가장 작은 변경을 적용합니다. 핸들러의 타입·검증을 고치거나, 코드가 정답(canonical)이라면 스펙을 바로잡습니다.

가드레일 (점수 조작 방지 규칙)

종료 조건을 "가짜로" 통과시키지 못하게 막는 규칙입니다. 반드시 지키세요.

• 체크 명령이나 종료 기준을 고쳐서 억지로 성공시키지 않는다.
• 체크를 건너뛰거나 비활성화·우회해서 종료 조건을 통과시키지 않는다.
• 여러 번 반복해도 막히면, 지표를 조작하지 말고 멈추고 블로커를 보고한다.

Claude Code에서 실행하기

가장 간단합니다. 아래 kickoff 프롬프트를 그대로 붙여넣으면 에이전트가 스스로 반복합니다.

"API 계약 일치까지(API Contract Until Match)" 루프를 시작합니다.

목표: API 구현이 공개된 계약(contract)과 일치한다
최대 반복: 10
매 반복 사이 실행: npm run test:contract
종료 조건: 계약 테스트 스위트가 종료 코드 0으로 끝날 때

1단계: 계약 테스트를 실행한다. 스키마/응답 불일치를 최소 diff로 하나씩 고치고, 다시 실행한다.

이 루프를 스스로 페이싱(self-pace)하라. 매 반복 후 체크 명령을 실행하고 출력을 읽어, 종료
조건이 충족되지 않았을 때만 계속한다. 종료 조건이 통과하거나 최대 반복에 도달하면 멈춘다.
매 회차마다 한 줄 상태 업데이트를 남긴다.

팁: npm run test:contract는 예시입니다. 프로젝트의 계약 테스트 명령에 맞게 바꾸세요 — 예를 들어 Dredd는 dredd openapi.yaml http://localhost:3000, Schemathesis는 schemathesis run openapi.yaml --url http://localhost:3000, Pact는 npm run test:pact 등입니다.

팁 / 변형

• 체크 명령 교체: 계약 검증 도구는 생태계마다 다릅니다. JS/TS는 Jest + jest-openapi 또는 Dredd, Python은 Schemathesis(schemathesis run ...), 소비자 주도 계약은 Pact를 쓰세요. 핵심은 "응답이 스펙과 맞는지"를 종료 코드로 판정하는 명령이면 됩니다.
• 스펙 vs 코드, 무엇이 정답인가: 매 수정 전에 "스펙이 진실인가, 코드가 진실인가"를 먼저 정하세요. 계약이 공개 API라면 스펙을 보존하고 핸들러를 고치고, 내부 API에서 코드가 앞서 있다면 스펙을 코드에 맞춥니다.
• 수렴이 멈추면: 같은 불일치가 2회 반복되면 가드레일대로 멈추고, 어떤 엔드포인트·필드가 왜 안 맞는지 가설과 함께 사람에게 보고하게 하세요.
• 연관 루프: 스펙 파일 자체를 lint하고 라우트와 동기화하려면 looping:openapi-sync-until-valid, 코드 변경 후 문서를 맞추려면 looping:docs-sync-after-edits, 전체 테스트를 green까지 돌리려면 looping:test-until-green.

Start the "API Contract Until Match" loop.

Goal: API implementation matches the published contract
Max iterations: 10
Between iterations run: npm run test:contract
Exit when: contract test suite exits 0

Step 1: Run contract tests. Fix each schema/response mismatch with minimal diffs, then re-run.

Self-pace this loop. After each iteration, run the check command, read the output, and only continue if the exit condition is not met. Stop when the exit condition passes or max iterations is reached. Give a short status update each pass.