api-summary

API Summary — 협업팀 공유용 API 변경 요약

코드 리뷰 반영, 새 기능 구현, 리팩토링 등 어떤 종류의 작업이든 끝난 뒤 그 작업으로 발생한 API 변경을 협업팀에 공유할 문서로 정리한다.

사용 맥락 (독립 스킬, 특정 워크플로우에 종속되지 않음):

• PR을 열기 전 PR 설명에 붙일 요약이 필요할 때
• 프론트엔드/모바일/QA 팀에 Slack으로 공유할 체크리스트가 필요할 때
• 릴리즈 노트/변경 로그 초안이 필요할 때
• 외부 소비자(파트너 API 등)에게 breaking change를 고지해야 할 때

원하는 작업이 끝난 어느 시점에서나 독립적으로 실행할 수 있다. 특정 스킬 실행 직후에만 쓰는 것이 아니다.

사용법

/api-summary                                     # 최근 변경 범위 자동 탐지
/api-summary --since <commit>                    # 특정 커밋 이후
/api-summary --range main..HEAD                  # diff 범위 지정
/api-summary --files src/api/*.ts                # 특정 파일만
/api-summary --plan-execute <execute.json>       # plan-execute 결과 기반
/api-summary --format md|json                    # 출력 형식 (기본: md)

실행 흐름

Step 0: 범위 결정

다음 우선순위로 변경 범위를 정한다:

1. --since/--range/--files 플래그 → 명시적 범위
2. --plan-execute → 해당 실행의 files_changed 합집합을 범위로
3. .harness/api-summaries/에 이전 요약 있으면 → 해당 이후 커밋 범위
4. .harness/reviews/ 최근 리뷰 이후 범위 (fallback)
5. 모두 없으면 → git log --since="7 days ago" 범위

범위가 결정되면 사용자에게 확인:

변경 범위: main..HEAD (12 커밋, 23 파일)
API 관련 파일 추정: 5개
  - src/api/orders.ts
  - src/api/payments.ts
  - src/routes/index.ts
  - ...
진행할까요? [Y/n]

Step 1: 프레임워크 감지

레포를 훑어 API 프레임워크를 식별한다:

시그니처	프레임워크
package.json에 express	Express
package.json에 @nestjs/core	NestJS
package.json에 fastify	Fastify
package.json에 hono, next App Router route.ts	Hono / Next.js
requirements.txt/pyproject.toml에 fastapi	FastAPI
requirements.txt에 djangorestframework	Django REST
requirements.txt에 flask	Flask
go.mod에 gin-gonic/gin, labstack/echo	Gin / Echo
*.yaml/*.json OpenAPI 스키마	OpenAPI spec

여러 개 감지되면 모두 처리 (모노레포 대응). 하나도 못 찾으면 사용자에게 프레임워크 지정 요청.

Step 2: 엔드포인트 추출

변경 전(base)과 변경 후(head) 각각에서 엔드포인트 목록을 추출한다.

프레임워크별 파싱 패턴:

Express / Fastify / Hono

router.get|post|put|patch|delete('/path', handler)
app.METHOD('/path', ...)

• Zod 스키마 연결: .parse(req.body) 근처 스키마 식별
• JSDoc 주석에서 설명 추출

NestJS

@Get('/path'), @Post('/path'), @Controller('/base')

• Controller base path + method path 조합
• DTO 클래스 분석 (@Body() dto: CreateOrderDto → DTO 필드 추출)
• @ApiOperation, @ApiResponse 데코레이터 활용

FastAPI

@app.get("/path"), @router.post("/path")

• Pydantic 모델 분석 (response_model, 파라미터 타입)
• docstring에서 설명 추출

Django REST

• urls.py의 path() 패턴
• ViewSet의 action, Serializer 필드
• @action 데코레이터

Flask

@app.route('/path', methods=['GET'])

OpenAPI spec

• paths.*.* 직접 파싱

각 엔드포인트에서 추출할 정보:

• method (GET/POST/...)
• path (정규화: /api/v1/docs)
• description (주석/데코레이터/docstring)
• request.params (path params)
• request.query (쿼리 파라미터)
• request.body (요청 바디 스키마)
• request.headers (요구되는 커스텀 헤더)
• response (응답 스키마 / 상태 코드)
• file (정의 위치)

Step 3: 변경 분류

base와 head의 엔드포인트 집합을 비교:

• 신규: head에만 있음
• 삭제: base에만 있음
• 수정: 양쪽에 같은 method + path가 있으나 내용이 다름
  • 비교 항목: request/response 스키마, 쿼리/파라미터, 상태 코드, 핸들러 로직 해시
  • 단순 스타일 변경(포맷팅, 변수명)은 제외

path 변경 감지:

• 같은 핸들러 함수인데 path가 다름 → "path 변경"으로 수정 카테고리에 기록

Step 4: 변경 내용 상세 분석 (수정 항목)

"수정" 분류된 각 엔드포인트에 대해 무엇이 변경됐는지 구체화:

• 쿼리 파라미터: 추가/삭제/타입 변경
• 요청 바디: 필드 추가/삭제, 필수/선택 변경, 타입 변경
• 응답 바디: 필드 추가/삭제
• 상태 코드: 추가된 에러 케이스
• 인증/권한: 스코프 변경

커밋 메시지를 참고하여 변경 의도 추정 (단, 단정하지 않고 "추정"으로 표기).

Step 5: Markdown 생성

출력 파일: .harness/api-summaries/{YYYYMMDD_HHmmss}-summary.md

# API 스펙 변경 요약

생성일: YYYY-MM-DD
범위: {commit range 또는 plan-execute 파일}
감지 프레임워크: NestJS, FastAPI

---

## 신규 생성

### POST /api/v1/orders
결제 대기 상태의 주문을 생성한다.

- **요청 방법**
  - Body: `CreateOrderDto`
    - `items: OrderItem[]` (필수) — 상품 목록
    - `shippingAddress: string` (필수)
    - `couponCode?: string` (선택)
  - Headers: `Authorization: Bearer <token>` (필수)
- **응답 값 설명**
  - `200 OK`: `{ orderId: string, status: 'pending_payment', totalAmount: number }`
  - `400 Bad Request`: 재고 부족 또는 검증 실패
  - `401 Unauthorized`: 인증 누락
- **구현**: [src/api/orders.ts:34](src/api/orders.ts#L34)

### GET /api/v1/orders/:id
... (동일 구조)

---

## 수정 사항

### GET /api/v1/docs
문서를 불러오는 api

- **변경 내용**: 쿼리 파라미터 형식 변경 (`ids=1,2,3` → `id=1&id=2&id=3`)
- **요청 방법**
  - Query: `id: number[]` (중복 허용, 기존 `ids: string` 단일값)
- **응답 값 설명** (변경 없음)
  - `200 OK`: `Doc[]`
- **구현**: [src/api/docs.ts:12](src/api/docs.ts#L12)
- **호환성**: Breaking — 기존 클라이언트 `ids=...` 사용 불가
- **추정 사유** (커밋 `abc1234`): "query param을 표준 배열 형식으로 통일"

---

## 삭제 사항

### DELETE /api/v1/legacy/sync
과거 동기화 엔드포인트

- **삭제 사유** (추정): legacy 경로 정리, 새 엔드포인트 `/api/v2/sync`로 대체됨
- **마지막 구현 위치**: src/api/legacy.ts (삭제됨)
- **영향**: 외부 클라이언트 사용 여부 확인 필요

---

## 요약

| 구분 | 건수 |
|------|------|
| 신규 | 3 |
| 수정 | 2 |
| 삭제 | 1 |
| **합계** | 6 |

**Breaking changes**: 1건 (GET /api/v1/docs 쿼리 형식 변경)

## 메타

- 분석 범위: `<base_sha>..<head_sha>`
- 커밋 수: 12
- 파싱된 엔드포인트: base 37개, head 39개

JSON 출력 (--format json)

.harness/api-summaries/{ts}-summary.json:

{
  "metadata": {
    "date": "YYYY-MM-DDTHH:mm:ss",
    "range": "main..HEAD",
    "frameworks": ["NestJS", "FastAPI"],
    "summary": { "added": 3, "modified": 2, "removed": 1 },
    "breaking_changes": 1
  },
  "added": [
    {
      "method": "POST",
      "path": "/api/v1/orders",
      "description": "결제 대기 상태의 주문을 생성",
      "request": { "body": {...}, "headers": {...} },
      "response": { "200": {...}, "400": {...} },
      "file": "src/api/orders.ts",
      "line": 34
    }
  ],
  "modified": [
    {
      "method": "GET",
      "path": "/api/v1/docs",
      "changes": ["query_param_format_changed"],
      "breaking": true,
      "before": {...},
      "after": {...},
      "suspected_reason": "query param 표준화",
      "commit": "abc1234"
    }
  ],
  "removed": [...]
}

Step 6: 결과 안내

요약 파일 경로와 활용 힌트를 표시한다. 이 스킬은 체인의 일부가 아니라 공유 목적의 독립 산출물을 만드는 스킬이다. 따라서 다음 단계를 강제하지 않는다.

저장: .harness/api-summaries/YYYYMMDD_HHmmss-summary.md

요약 통계:
  - 신규 3건 / 수정 2건 / 삭제 1건
  - Breaking change: 1건

이 문서는 다음 용도로 바로 활용할 수 있습니다:
  - PR 설명: 내용 복사 또는 파일 링크
  - Slack/Jira 공유: Markdown 블록 그대로 붙여넣기
  - 릴리즈 노트: `### API 변경` 섹션으로 편입
  - 외부 소비자 공지: breaking change 항목만 발췌

Breaking change가 있으면 상단에 명시적 경고를 한 번 더 표시한다.

검증 원칙

1. 단정하지 않음 — 파싱 실패한 부분은 "(추출 실패, 수동 확인 필요)"로 표기
2. 주석/데코레이터 우선 — 코드보다 개발자가 적은 설명을 우선 (OpenAPI 데코레이터, JSDoc 등)
3. 일관된 path 정규화 — trailing slash, /api/ prefix 변형 통일
4. 수정 판정은 보수적 — 단순 리팩토링(변수명 변경, 포맷팅)은 "수정"으로 분류하지 않음
5. Breaking 판정 기준:
   • path 또는 method 변경
   • 필수 파라미터/필드 추가
   • 응답 필드 삭제 또는 타입 변경
   • 기존 상태 코드가 다른 의미로 변경

제약

• 동적으로 생성되는 라우트(런타임 등록)는 감지 불가
• 프레임워크 외부의 커스텀 라우터는 패턴을 사용자가 직접 제공해야 함
• 스키마가 런타임 조립되면 정적 분석으로 한계 — 가능한 수준에서만 요약

설정

.harness/api-summary.json (선택):

{
  "api_path_prefix": "/api",
  "ignore_paths": ["/api/internal/*", "/api/debug/*"],
  "include_private_endpoints": false,
  "framework_override": null
}

• api_path_prefix: 이 prefix로 시작하는 경로만 API로 간주
• ignore_paths: 요약에서 제외할 경로 glob
• include_private_endpoints: 내부 전용 경로 포함 여부
• framework_override: 자동 감지 대신 고정 ("express", "nestjs" 등)