Claude Code로 행동에서 OpenAPI 생성하기, 솔직히 말하면

왜 OpenAPI 계약은 어긋나는가(그리고 왜 중요한가)

OpenAPI 계약은 API의 공통된 설명입니다: 어떤 엔드포인트가 있는지, 무엇을 보내고 무엇을 받는지, 오류는 어떻게 생겼는지. 서버와 그 호출 주체(웹 앱, 모바일 앱 또는 다른 서비스) 사이의 합의입니다.

문제는 드리프트입니다. 실행 중인 API는 변하는데 스펙은 그대로이거나, 스펙은 보기 좋게 정리되지만 구현은 이상한 필드를 계속 반환하거나 상태 코드가 빠지거나 오류 형태가 일관되지 않을 수 있습니다. 시간이 지나면 사람들은 OpenAPI 파일을 신뢰하지 않게 되고, 그냥 무시되는 문서가 됩니다.

드리프트는 보통 정상적인 압력에서 옵니다: 빠른 수정이 스펙 업데이트 없이 배포된다거나, 새로운 선택적 필드가 "임시로" 추가된다거나, 페이지네이션이 진화하거나, 팀들이 서로 다른 "진실의 출처"(백엔드 코드, Postman 컬렉션, OpenAPI 파일)를 업데이트할 때입니다.

정직하게 유지한다는 것은 스펙이 실제 동작과 일치한다는 뜻입니다. API가 때때로 충돌로 409를 반환한다면 그건 계약에 있어야 합니다. 필드가 nullable이면 그렇게 명시하세요. 인증이 필요하면 모호하게 두지 마세요.

좋은 워크플로우는 다음을 제공합니다:

• 의도된 동작과 관찰된 동작을 반영하는 OpenAPI 파일
• 클라이언트가 깨지기 전에 드리프트를 잡을 수 있는 간단한 검사 집합
• 코드베이스에 복사해 쓸 수 있는 구체적인 클라이언트 및 서버 검증 예제

마지막 포인트가 중요한 이유는 계약이 실제로 강제될 때만 도움이 되기 때문입니다. 정직한 스펙과 반복 가능한 검사는 “API 문서”를 팀들이 신뢰할 수 있는 것으로 바꿉니다.

코드가 아니라 의도된 동작에서 시작하세요

코드를 읽거나 라우트를 그대로 복사해서 시작하면 OpenAPI는 오늘 존재하는 것을 기술하게 됩니다. 거기에는 약속하고 싶지 않은 특이사항도 포함됩니다. 대신 호출자 관점에서 API가 무엇을 해야 하는지 설명하고, 그 다음 구현이 스펙과 일치하는지 검증하세요.

YAML이나 JSON을 작성하기 전에 엔드포인트마다 작은 사실 집합을 수집하세요:

• 무엇을 하는가(메서드와 경로)
• 무엇을 받는가(헤더, 쿼리, 경로 파라미터, 본문)
• 무엇을 반환하는가(성공 상태 코드, 응답 형태, 주요 헤더)
• 어떤 실패가 가능한가(가능한 오류, 상태 코드, 오류 바디 형태)
• 누가 호출할 수 있는가(인증과 역할, 관련 있으면)

그 다음 동작을 예제로 작성하세요. 예제는 구체적으로 하도록 강제하고 일관된 계약 초안 작성이 쉬워집니다.

Tasks API의 경우 해피 패스 예시는: “title로 작업을 생성하고 id, title, status, createdAt를 받는다.” 흔한 실패도 추가하세요: “title이 없으면 {\"error\":\"title is required\"}로 400을 반환한다.” 그리고 “인증 없이는 401” 같은 예시도요. 이미 엣지 케이스를 알고 있다면 포함하세요: 중복 제목 허용 여부, 존재하지 않는 작업 ID 처리 방식 등.

규칙을 코드 세부사항에 의존하지 않는 간단한 문장으로 캡처하세요:

• “title은 필수이며 1-120자입니다.”
• “리스트는 limit이 설정되지 않으면 최대 50개를 반환합니다(최대 200).”
• “dueDate는 ISO 8601 날짜-시간 형식입니다.”
• “쓰기 엔드포인트는 사용자 토큰을 요구합니다.”

마지막으로 v1 범위를 결정하세요. 확실하지 않다면 v1을 작게 명확하게 유지하세요(생성, 조회, 목록, 상태 업데이트). 검색, 대량 업데이트, 복잡한 필터는 나중으로 미뤄서 계약이 믿을 만하게 만드세요.

엔드포인트를 설명하는 가벼운 템플릿

Claude Code에게 스펙을 작성해 달라고 하기 전에 행동 노트를 작고 반복 가능한 형식으로 작성하세요. 목표는 모델이 실수로 공백을 추측으로 채우기 어렵게 만드는 것입니다.

좋은 템플릿은 실제로 사용할 만큼 짧고, 두 사람이 같은 엔드포인트를 비슷하게 설명할 만큼 일관적이어야 합니다. 구현 방식이 아니라 API가 무엇을 하는지에 집중하세요.

Endpoint behavior note template

Use one block per endpoint:

METHOD + PATH:
Purpose (1 sentence):
Auth:
Request:
- Query:
- Headers:
- Body example (JSON):
Responses:
- 200 OK example (JSON):
- 4xx example (status + JSON):
Edge cases:
Data types (human terms):

요청과 두 개 이상의 응답을 적어 두세요. 상태 코드와 실제 필드 이름을 가진 현실적인 JSON 바디를 포함하세요. 필드가 선택적이라면 한 예제에서 누락된 형태를 보여 주세요.

엣지 케이스를 명시적으로 지적하세요. 엣지 케이스는 스펙이 나중에 조용히 틀어지는 지점입니다: 빈 결과, 잘못된 ID(400 vs 404), 중복(409 vs 멱등 동작), 검증 실패, 페이지네이션 한도 등.

또한 스키마를 생각하기 전에 사람 말로 데이터 타입을 적어 두세요: 문자열 vs 숫자, 날짜-시간 형식, 불리언, 열거형(허용 값 목록). 그러면 보기 좋은 스키마가 실제 페이로드와 맞지 않는 일을 막을 수 있습니다.

Claude Code로 OpenAPI 스펙 초안 작성하기(작동하는 프롬프트)

Claude Code는 주의 깊은 필경사처럼 다루면 가장 잘 작동합니다. 행동 노트와 스펙이 어떤 형태여야 하는지에 대한 엄격한 규칙을 제공하세요. 단순히 “OpenAPI 스펙을 작성해줘”라고만 하면 보통 추측, 일관성 없는 명명, 누락된 오류 케이스가 생깁니다.

행동 노트를 먼저 붙여 넣고, 그다음 엄격한 지시 블록을 추가하세요. 실용적 프롬프트 예시는 다음과 같습니다:

You are generating an OpenAPI 3.1 YAML spec.
Source of truth: the behavior notes below. Do not invent endpoints or fields.
If anything is unclear, list it under ASSUMPTIONS and leave TODO markers in the spec.

Requirements:
- Include: info, servers (placeholder), tags, paths, components/schemas, components/securitySchemes.
- For each operation: operationId, tags, summary, description, parameters, requestBody (when needed), responses.
- Model errors consistently with a reusable Error schema and reference it in 4xx/5xx responses.
- Keep naming consistent: PascalCase schema names, lowerCamelCase fields, stable operationId pattern.

Behavior notes:
[PASTE YOUR NOTES HERE]

Output only the OpenAPI YAML, then a short ASSUMPTIONS list.

초안을 받으면 먼저 ASSUMPTIONS를 살펴보세요. 바로잡음의 핵심은 거기에서 시작됩니다. 올바른 것은 승인하고, 잘못된 것은 고쳐서 노트를 업데이트한 뒤 다시 실행하세요.

명명 일관성을 유지하려면 규칙을 미리 정하고 지키세요. 예를 들어: 안정적인 operationId 패턴, 명사형 태그 이름, 단수 스키마 이름, 하나의 공용 Error 스키마, 모든 곳에서 같은 인증 스킴 이름 사용 등입니다.

Koder.ai 같은 바이브-코딩 워크스페이스에서 작업한다면 YAML 파일을 일찍 실제 파일로 저장하고 작은 diff로 반복하는 것이 도움이 됩니다. 어떤 변경이 승인된 행동 결정에서 왔고, 어떤 것이 모델의 추측에서 왔는지 볼 수 있습니다.

스펙을 실행 중인 API와 비교하기 전에 검증하세요

실행 중인 API와 비교하기 전에 OpenAPI 파일이 내부적으로 일관된지 확인하세요. 희망사항과 모호한 표현을 가장 빨리 잡을 수 있는 장소입니다.

각 엔드포인트를 클라이언트 개발자라고 생각하고 읽어보세요. 호출자가 반드시 보내야 하는 것과 받을 것인지를 중심으로 보세요.

실용적인 리뷰 패스:

• 필수 vs 선택: 필수 필드를 올바르게 표시하고 “모두 선택” 같은 상태를 피하세요.
• 타입과 포맷: UUID, 이메일, 날짜-시간, 최소/최대값을 명시하세요.
• 예제: 엔드포인트당 현실적인 요청과 응답 예제를 최소 하나씩 추가하고 예제가 스키마와 일치하는지 확인하세요.
• 상태 코드: 행동 노트와 정렬시키세요(생성은 종종 201이지 200이 아닙니다). 400 vs 422 선택을 일관되게 하세요.
• 인증: 엔드포인트별로 무엇이 필요한지, 역할로 접근이 달라지는지 명확히 적으세요.

오류 응답은 추가 주의가 필요합니다. 하나의 공통된 형태를 골라 모든 곳에서 재사용하세요. 어떤 팀은 { error: string }처럼 매우 단순하게 유지하고, 다른 팀은 { error: { code, message, details } } 같은 객체를 씁니다. 어느 쪽이든 섞어 쓰지 마세요. 섞이면 클라이언트 코드에 특수 처리가 늘어납니다.

간단한 시나리오로 점검해 보세요. POST /tasks가 title을 요구한다면 스키마는 필수로 표시돼야 하고, 실패 응답은 실제로 반환하는 오류 바디를 보여야 하며, 해당 연산이 인증을 요구하는지 명확히 해야 합니다.

스펙과 실행 중인 API 구현을 비교하기

스펙이 의도된 동작처럼 읽히면, 실행 중인 API를 클라이언트가 오늘 경험하는 진실로 취급하세요. 목표는 스펙과 코드 사이에서 “이겨내기”가 아니라 차이를 조기에 표면화하고 각 항목에 대해 명확한 결정을 내리는 것입니다.

첫 번째 패스에서는 실제 요청/응답 샘플이 가장 단순한 옵션입니다. 로그나 자동화된 테스트도 신뢰할 수 있으면 좋습니다.

일반적인 불일치 항목을 주의하세요: 한 쪽에만 존재하는 엔드포인트, 필드명 또는 형태 차이, 상태 코드 차이(200 vs 201, 400 vs 422), 문서화되지 않은 동작(페이지네이션, 정렬, 필터링), 인증 차이(스펙은 공개인데 코드가 토큰을 요구함).

예: OpenAPI에 POST /tasks가 201과 {id,title}을 반환한다고 적혀 있는데, 실제 호출 결과는 200과 {id,title,createdAt}을 받는다면 생성된 클라이언트에는 "충분히 비슷함"이 아닙니다.

바로 편집하기 전에 각 차이를 어떻게 해결할지 결정하세요:

• 동작이 올바른데 문서화되지 않았다면 스펙을 수정하세요.
• 스펙이 합의된 계약이라면 코드를 수정하세요.
• 어느 쪽도 옳지 않다면 의도된 동작을 먼저 조정하고 둘 다 업데이트하세요.

모든 변경은 작고 검토 가능하게 유지하세요: 한 엔드포인트, 한 응답, 한 스키마 수정이 이상적입니다. 리뷰와 재테스트가 쉬워집니다.

계약에서 클라이언트 및 서버 검증 예제 생성하기

신뢰하는 스펙이 생기면 그것을 작은 검증 예제로 바꾸세요. 이것이 드리프트가 다시 생기는 것을 막는 도구입니다.

서버 측 검증(잘못된 요청 거부)

서버에서 검증은 계약과 일치하지 않는 요청을 빠르게 거부하고 명확한 오류를 반환하는 것을 의미합니다. 이는 데이터 보호와 버그 탐지에 유리합니다.

서버 검증 예제는 보통 세 부분으로 된 케이스로 표현됩니다: 입력, 기대 출력, 기대 오류(정확한 텍스트가 아닌 오류 코드나 메시지 패턴).

예(계약에 title이 필수이며 1~120자일 때):

{
  "name": "Create task without title returns 400",
  "request": {"method": "POST", "path": "/tasks", "body": {"title": ""}},
  "expect": {"status": 400, "body": {"error": {"code": "VALIDATION_ERROR"}}}
}

클라이언트 측 검증(변경을 조기에 포착)

클라이언트에서의 검증은 서버가 달라지기 전에 드리프트를 탐지하는 것입니다. 서버가 다른 형태를 반환하거나 필수 필드가 사라지면 테스트가 이를 알려야 합니다.

클라이언트 검사는 실제로 의존하는 것에 집중하세요. 예: “작업에는 id, title, status가 있다” 정도입니다. 모든 선택적 필드나 정확한 정렬까지 단언하면 사소한 변경에도 실패합니다.

몇 가지 가이드라인:

• 정확한 값보다는 존재와 타입을 확인하세요.
• 옵션 필드는 해당 기능에 중요하지 않다면 단언하지 마세요.
• 오류는 상태와 오류 코드를 확인하고 전체 메시지는 검사하지 마세요.
• 추가 필드는 계약이 명시적으로 금지하지 않는 한 허용하세요.

Koder.ai로 빌드하면 이러한 예제 케이스를 OpenAPI 파일 옆에 보관하고 동작이 바뀔 때 함께 업데이트할 수 있습니다.

예제 시나리오: 간단한 Tasks API 처음부터 끝까지

작업 생성 POST /tasks, 목록 GET /tasks, 단건 조회 GET /tasks/{id} 세 개의 엔드포인트가 있는 작은 API를 상상해 보세요.

한 엔드포인트에 대해 테스트 담당자에게 설명하듯 몇 가지 구체적 예제를 먼저 작성하세요.

POST /tasks의 의도된 동작 예시:

• 성공: { "title": "Buy milk" }를 보내면 새 작업 객체와 함께 201을 받고, id, title, done:false가 포함된다.
• 실패 1: {}를 보내면 { "error": "title is required" } 같은 오류로 400을 반환한다.
• 실패 2: { "title": "x" }(너무 짧음)를 보내면 { "error": "title must be at least 3 characters" } 같은 오류로 422를 반환한다.

Claude Code가 OpenAPI 초안을 만들면 이 엔드포인트 스니펫에는 스키마, 상태 코드, 현실적인 예제가 담겨야 합니다:

paths:
  /tasks:
    post:
      summary: Create a task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
            examples:
              ok:
                value: { "title": "Buy milk" }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
              examples:
                created:
                  value: { "id": "t_123", "title": "Buy milk", "done": false }
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingTitle:
                  value: { "error": "title is required" }
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                tooShort:
                  value: { "error": "title must be at least 3 characters" }

흔한 불일치는 미묘합니다: 실행 중인 API가 201 대신 200을 반환하거나 { "taskId": 123 }처럼 다른 필드명을 반환하는 경우입니다. 생성된 클라이언트는 이런 차이에 의해 깨집니다.

해결 방법은 한 가지 진실의 출처를 선택하는 것입니다. 의도된 동작이 맞다면 구현을 변경해 201과 합의된 Task 형태를 반환하게 하세요. 이미 프로덕션 동작이 의존되고 있다면 스펙(및 행동 노트)을 현실에 맞게 업데이트하고 누락된 검증과 오류 응답을 추가해 클라이언트가 놀라지 않도록 하세요.

계약을 부정직하게 만드는 흔한 실수들

계약이 규칙을 설명하는 대신 어느 날 API가 반환한 것을 기술하게 되면 부정직해집니다. 간단한 테스트: 새 구현이 오늘의 특이사항을 복사하지 않고도 이 스펙을 통과할 수 있는가?

과적합의 함정이 있습니다. 한 번의 응답을 캡처해서 그것을 법으로 만드는 일입니다. 예: 현재 API가 모든 작업에서 dueDate: null을 반환하니까 스펙에 항상 nullable이라고 적는 경우, 실제 규칙은 “status가 scheduled일 때 필요”일 수 있습니다. 계약은 규칙을 표현해야지 현재 데이터셋을 옮겨 적으면 안 됩니다.

오류는 정직성이 깨지는 지점입니다. 성공 응답만 스펙에 적어두기 쉽지만, 클라이언트는 기본적인 오류 정보를 필요로 합니다: 토큰이 없으면 401, 권한 부족이면 403, 알려지지 않은 ID면 404, 그리고 일관된 검증 오류(400 또는 422) 등.

다른 문제 패턴:

• 엔드포인트마다 이름과 타입이 달라짐(taskId vs id, priority가 문자열/숫자 등)
• 예제가 스키마와 모순됨(열거형 값 불일치, 날짜-시간 예제가 ISO 8601 아님)
• 결정을 피하려고 타입을 넓게 잡음(모두 string, 모두 선택적 등)
• 스펙이 마케팅 문구처럼 보임(“빠름”, “안전함”) 대신 테스트 가능한 계약이어야 함

좋은 계약은 테스트 가능해야 합니다. 스펙에서 실패하는 테스트를 쓸 수 없다면 아직 정직하지 않은 것입니다.

스펙을 공유하거나 공개하기 전에 하는 빠른 점검

OpenAPI 파일을 다른 팀에 넘기기 전에 “이 사람은 머리를 읽지 않고도 이걸 쓸 수 있는가?”를 빠르게 점검하세요.

먼저 예제를 확인하세요. 스펙이 유효하더라도 모든 요청/응답이 추상적이면 쓸모가 없습니다. 각 연산마다 현실적인 요청 예제와 성공 응답 예제를 최소 하나씩 포함하세요. 오류는 인증/검증 등 흔한 실패 케이스당 하나의 예제가 보통 충분합니다.

그다음 일관성을 확인하세요. 한 엔드포인트는 { "error": "..." }, 다른 엔드포인트는 { "message": "..." }를 반환하면 클라이언트는 분기 로직이 늘어납니다. 단일 오류 형태와 예제를 재사용하고 일관된 상태 코드를 선택하세요.

짧은 체크리스트:

• 필수 필드, 형식(email, uuid, date-time), 열거형이 명확한가
• 유사한 엔드포인트에서 상태 코드가 의도적이고 일관적인가
• 오류 응답에 스키마와 예제가 포함되어 있는가(상태 코드만 있는 게 아님)
• 실제 호출을 2-3개 실행해 페이로드를 스펙과 비교했는가
• 스펙만 보고도 하나의 작은 클라이언트 호출을 작성할 수 있는가(헤더, 필드명, null 허용 여부를 추측하지 않아도 되는가)

실용적 트릭: 한 엔드포인트를 골라서 당신이 API를 전혀 본 적이 없다고 치고 “무엇을 보내고 무엇을 받으며 무엇이 깨지는가?”에 답해 보세요. OpenAPI가 그 질문에 명확히 답하지 못하면 준비가 된 것이 아닙니다.

다음 단계: 습관으로 만들고 변경을 안전하게 유지하기

이 워크플로우는 릴리즈 당일에만 하는 것이 아니라 정기적으로 돌릴 때 효과가 납니다. 간단한 규칙을 정하고 지키세요: 엔드포인트가 변경될 때마다 실행하고, 스펙을 공개하기 전 다시 실행하세요.

소유권을 단순하게 유지하세요. 엔드포인트를 변경한 사람이 행동 노트와 스펙 초안을 업데이트합니다. 두 번째 사람이 스펙 대 구현의 diff를 코드 리뷰처럼 검토하세요. QA나 서포트 팀원들은 불명확한 응답과 엣지 케이스를 잘 발견합니다.

계약 편집을 코드 편집처럼 취급하세요. 채팅 기반 빌더인 Koder.ai를 쓴다면 위험한 변경 전 스냅샷을 찍고, 롤백을 사용하면 반복이 안전합니다. Koder.ai는 소스 코드 내보내기를 지원해 스펙과 구현을 리포지토리에서 나란히 유지하기 쉽습니다.

보통 느리지 않게 일하는 루틴:

• 새 엔드포인트를 추가할 때 행동 노트를 작성한다
• 스펙을 검증하고 계약 테스트를 통과한 뒤 머지한다
• 릴리즈 전에 실행 중인 API와 스펙을 비교한다
• 위험한 변경 전 스냅샷을 찍고, diff가 혼란스러우면 롤백한다

다음 행동: 이미 존재하는 한 엔드포인트를 하나 골라 보세요. 행동 노트 5-10줄(입력, 출력, 오류 케이스)을 작성하고, 그 노트로부터 OpenAPI 초안을 생성하고 검증한 다음 실행 중인 구현과 비교하세요. 하나의 불일치를 수정하고 재테스트한 뒤 반복하세요. 한 엔드포인트만으로도 이 습관이 자리잡기 쉽습니다.