| name | openapi-sync-until-valid |
| description | openapi.yaml을 redocly·spectral·swagger-cli로 lint하고, 문서에 적힌 path·schema·status code가 실제 라우트 핸들러와 어긋난 부분(drift)을 매 회차마다 고쳐 lint가 0 에러로 통과할 때까지 자동 반복하는 닫힌 루프입니다. 사용자가 "openapi.yaml lint 통과할 때까지 고쳐줘", "OpenAPI 스펙 핸들러랑 동기화해줘", "스펙이랑 라우트 안 맞는 거 맞춰줘", "OpenAPI drift 고쳐줘", "API 명세 깨끗해질 때까지 돌려줘", "keep openapi.yaml valid and in sync", "lint the spec and fix drift", "sync openapi until valid"처럼 OpenAPI 명세를 검증하고 구현과 맞추고 싶을 때 사용하세요. (구분: 런타임 API 응답이 계약과 일치하는지 테스트로 검증하는 건 looping:api-contract-until-match, 코드 자체의 lint·타입체크는 looping:lint-typecheck-fix, 코드 변경 후 README·문서를 맞추는 건 looping:docs-sync-after-edits) |
OpenAPI 동기화·검증까지 (OpenAPI Sync Until Valid)
openapi.yaml을 lint하고, 문서화된 경로·스키마·상태 코드가 실제 핸들러와 어긋난 부분을 매 회차마다 고쳐 명세가 깨끗하게 통과할 때까지 반복합니다.
| 항목 | 값 |
|---|
| 카테고리 | API |
| 트리거 | 수동(manual) — 사람이 직접 시작 |
| 종료 조건(Exit) | OpenAPI lint가 종료 코드 0일 때 (openapi.yaml이 깨끗하게 lint되고 구현된 라우트와 일치) |
| 반복 한도(Max iterations) | 8 |
| 매 반복 체크 명령 | npx @redocly/cli lint openapi.yaml |
| 가드레일 | 강화됨(Hardened) |
| 지원 에이전트 | Cursor (프롬프트 전용이라 Claude Code·Codex에서도 그대로 동작) |
이 루프는 언제 쓰나
코드가 빨리 바뀌면서 openapi.yaml이 실제 구현과 따로 노는 상황에서 씁니다. 핸들러는 204를 돌려주는데 문서엔 200으로 적혀 있거나, 라우트는 추가됐는데 스펙에는 없거나, 스키마 필드가 빠지는 식의 drift가 쌓이면 클라이언트 SDK·문서·목 서버가 전부 거짓말을 하게 됩니다. 한 번 시작하면 에이전트가 명세 lint → 에러 수집 → 핸들러나 스펙 수정 → 재lint를 스스로 반복하며 npx @redocly/cli lint openapi.yaml이 0 에러로 통과하는 상태에 수렴시킵니다. 핵심은 문서를 위해 구현을 비틀거나 구현을 숨기려고 문서를 약화시키지 않고, 문서화된 경로·스키마·상태 코드가 실제와 맞아떨어지게 만드는 것입니다.
루프 흐름
수동 시작 → OpenAPI lint → 핸들러/스펙 동기화 → 재lint →〔피드백 게이트〕lint 0 에러?
↑ │ 아니오
└──────────────────────────────────────────────┘
│ 예
종료
매 반복(pass)마다 하는 일
- OpenAPI lint — openapi.yaml을 spectral 또는 swagger-cli로 검증합니다. 모든 에러를 줄 번호와 함께 나열합니다.
npx @redocly/cli lint openapi.yaml
- 핸들러 동기화 — 문서화된 경로(path)·스키마(schema)·상태 코드(status code)가 실제와 일치하도록 라우트 핸들러 또는 스펙을 수정합니다.
가드레일 (점수 조작 방지 규칙)
종료 조건을 "가짜로" 통과시키지 못하게 막는 규칙입니다. 반드시 지키세요.
- 체크 명령이나 종료 기준을 고쳐서 억지로 성공시키지 않는다.
- 체크를 건너뛰거나 비활성화·우회해서 종료 조건을 통과시키지 않는다.
- 여러 번 반복해도 막히면, 지표를 조작하지 말고 멈추고 블로커를 보고한다.
Claude Code에서 실행하기
가장 간단합니다. 아래 kickoff 프롬프트를 그대로 붙여넣으면 에이전트가 스스로 반복합니다.
"OpenAPI Sync Until Valid" 루프를 시작합니다.
목표: openapi.yaml이 깨끗하게 lint되고 구현된 라우트와 일치
최대 반복: 8
매 반복 사이 실행: npx @redocly/cli lint openapi.yaml
종료 조건: OpenAPI lint가 종료 코드 0일 때
1단계: openapi.yaml을 lint한다. lint가 통과할 때까지 스펙 에러와 핸들러 drift를 고친다.
이 루프를 스스로 페이싱(self-pace)하라. 매 반복 후 체크 명령을 실행하고 출력을 읽어, 종료
조건이 충족되지 않았을 때만 계속한다. 종료 조건이 통과하거나 최대 반복에 도달하면 멈춘다.
매 회차마다 한 줄 상태 업데이트를 남긴다.
팁: npx @redocly/cli lint openapi.yaml은 예시입니다. 명세 파일 위치(docs/openapi.yaml 등)나 검증 도구를 프로젝트에 맞게 바꾸세요.
팁 / 변형
- 검증 도구 교체: redocly 대신 spectral(
npx @stoplight/spectral-cli lint openapi.yaml)이나 swagger-cli(npx swagger-cli validate openapi.yaml)를 써도 됩니다. 팀의 규칙 세트(.spectral.yaml, redocly.yaml)에 맞춰 고르세요.
- JSON 명세: 명세를 JSON으로 관리한다면
openapi.yaml 대신 openapi.json을 넘기세요.
- drift 방향 정하기: 매 회차에서 "문서가 틀렸나, 구현이 틀렸나"를 먼저 판단하게 하세요. 의도된 동작이면 스펙을 고치고, 버그면 핸들러를 고칩니다 — 문서를 맞추려고 멀쩡한 핸들러를 비틀지 않도록.
- 막힐 때: 같은 lint 에러가 2회 반복되면 가드레일대로 멈추고, 원인 가설과 함께 사람에게 보고하게 하세요.
- 연관 루프: 런타임 응답이 계약과 맞는지 테스트로 검증하려면
looping:api-contract-until-match, 코드 변경 후 README·API 레퍼런스 동기화는 looping:docs-sync-after-edits, 코드 자체의 lint·타입체크는 looping:lint-typecheck-fix.
원본 영어 kickoff (loops.elorm.xyz 원문)
Start the "OpenAPI Sync Until Valid" loop.
Goal: openapi.yaml lints clean and matches implemented routes
Max iterations: 8
Between iterations run: npx @redocly/cli lint openapi.yaml
Exit when: OpenAPI lint exits 0
Step 1: Lint openapi.yaml. Fix spec errors and handler drift until lint passes.
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.
출처: https://loops.elorm.xyz/loops/openapi-sync-until-valid
