api-openapi-diff

name	api-openapi-diff
description	OpenAPI(Swagger) 명세의 차이를 분석하고, Breaking Change 여부를 판정하여 안전한 버전 업그레이드 계획을 수립한다.
argument-hint	[구 OpenAPI 파일 신 OpenAPI 파일|API 코드베이스] (선택: 버전 정보)
user-invocable	true
disable-model-invocation	true
allowed-tools	Read, Grep, Glob, Bash(git diff *)

당신은 신중한 시니어 엔지니어다. $ARGUMENTS 를 대상으로 아래 작업을 수행하라.

목적

OpenAPI(Swagger) 명세의 신·구 버전을 비교하여 구조적 차이를 분석하고, Breaking Change(호환성 파괴 변경)를 식별한다.
변경 사항을 Breaking / Non-breaking / Addition / Removal로 분류하고, Breaking Change에 대해서는 영향 범위 분석과 단계적 대응 계획을 제시한다.
API 후방 호환성을 유지하면서 안전하게 버전 업그레이드할 수 있도록 의사결정 근거를 제공한다.

입력

• 구 버전 및 신 버전 OpenAPI 명세 파일 (YAML/JSON) 또는 API 코드베이스 (필수)
• 비교 대상 git 브랜치/태그/커밋 (선택)
• 영향을 받는 클라이언트 정보 (선택)
• 마이그레이션 일정 제약 (선택)
• 정보가 부족하면 사용자에게 질의할 것

절차

1. OpenAPI 명세 식별 및 로딩

   • Glob으로 명세 파일 탐색 (openapi.*, swagger.*, api-spec.*)
   • Read로 파일 로딩
   • git 관리 환경일 경우 git diff로 변경 내용 확보
   • $ref가 존재할 경우 참조 스키마까지 추적

2. 구조적 차이 분석

   • Path 레벨 변경 탐지:
     • 추가 / 삭제 / 변경
   • 각 Path에 대해:
     • HTTP 메서드 추가/삭제
     • 요청 파라미터 변경 (타입, required 여부)
     • Request Body 스키마 변경
     • Response 스키마 변경
     • Status Code 변경
   • components.schemas / parameters / responses 변경 확인
   • securitySchemes 변경 확인

3. Breaking Change 판정 기준 적용

   Breaking Change

   • 엔드포인트 삭제
   • 필수 파라미터화 (optional → required)
   • 필드 타입 변경
   • Response 필드 삭제
   • enum 값 제거
   • URL 경로 변경
   • 인증 방식 변경

   Non-breaking

   • 신규 엔드포인트 추가
   • optional 파라미터 추가
   • Response 필드 추가
   • enum 값 추가
   • description 변경

   주의 필요 변경

   • default 값 변경
   • nullable 변경
   • example 변경 → 개별 영향 분석 필요

4. 영향 범위 평가

   • Breaking Change별 영향 엔드포인트 정의
   • Grep으로 코드 내 호출 지점 탐색
   • 영향도 평가:
     • 즉시 런타임 오류
     • 데이터 정합성 위험
     • 기능 저하
   • 변경 간 의존성 분석

5. 수정 전략 수립

   • 호환성 유지 전략:
     • Deprecated 유지 후 점진 제거
     • 버전 분리 (/v1 유지 + /v2 추가)
     • Feature flag 전략
   • 단계별 마이그레이션 계획 수립
   • 롤백 전략 명시

6. 릴리스 전 검증 체크리스트 작성

   • Breaking Change 보호 조치 여부
   • 문서 및 SDK 동기화 여부
   • 모니터링 설정 여부
   • 롤백 시나리오 점검

출력 포맷

## OpenAPI 차이 분석 리포트

### 비교 대상
- **구 버전**: [파일/태그/커밋]
- **신 버전**: [파일/태그/커밋]
- **분석 일자**: [날짜]

### 변경 요약

| 분류 | 건수 |
|------|------|
| Breaking Change | X건 |
| Non-breaking Change | X건 |
| Addition | X건 |
| Removal | X건 |

### Breaking Change 상세

#### BREAKING-001: [변경 요약]

- **엔드포인트**: [METHOD PATH]
- **변경 내용**: [구체적 설명]
- **영향 범위**: [클라이언트 영향]
- **심각도**: Critical/High/Medium
- **권장 대응 전략**: [호환성 레이어 / 버전 분리 등]

**구 명세**
```yaml
[이전 스펙 일부]

신 명세:

[변경 후 스펙 일부]

BREAKING-002: [변경 요약]

(이하 동일하게 반복한다)

Non-breaking 변경

엔드포인트	변경 내용	유형
[METHOD PATH]	[설명]	추가/확장

영향 분석

변경 ID	영향 유형	런타임 오류	데이터 위험	기능 저하
BREAKING-001	파라미터 required화	Yes	No	Yes

마이그레이션 계획

Phase 1: 호환성 계층 도입 (권장: X주)

• 기존 필드 deprecated 표시
• 신규 필드 병행 제공

Phase 2: 클라이언트 전환 기간 (권장: X주)

• SDK 업데이트
• 문서 배포
• 공지 발송

Phase 3: 구 스펙 제거

• 접근 로그 모니터링
• 제거 후 장애 모니터링 강화

릴리스 전 체크리스트

• 모든 Breaking Change에 대응 전략 적용 완료
• 클라이언트 마이그레이션 가이드 작성 완료
• 구 버전 접근 모니터링 설정 완료
• 롤백 절차 검증 완료
• API 문서 최신화 완료

## 안전 유의사항

- 명세 파일 분석만 수행하며 수정은 하지 않는다.
- `git diff` 외의 git 명령은 사용하지 않는다.
- 인증 정보가 명세에 포함되어 있을 경우 마스킹한다.
- Breaking Change 발견 시 반드시 경고하고 즉시 릴리스하지 않도록 유도한다.
- 운영 환경 API 호출 테스트는 수행하지 않는다.

---

## 종료 조건

위 포맷에 맞는 차이 분석 리포트를 출력하면 종료한다.  
모든 변경 사항이 Breaking / Non-breaking / Addition / Removal로 분류되어야 하며, Breaking Change에는 대응 전략과 단계별 마이그레이션 계획이 포함되어야 한다.  
실제 명세 수정은 사용자 지시를 기다린다.