OpenAPI 스펙 동기화 워크플로우 - diff 리포트 및 /api-sync 명령 포함

# 이 프로젝트에 OpenAPI 스펙 동기화 워크플로우 설정 다른 저장소에서 사용하는 것과 동일한 백엔드 스펙 워크플로우를 원합니다: 라이브 OpenAPI 스펙을 로컬 스냅샷과 비교하고 **프론트엔드 중심** 변경 보고서를 작성하는 스크립트, 그리고 그 보고서를 단계별 계획으로 전환하는 `/api-sync` 슬래시 명령어. 시작하기 전에 저장소에서 다음 항목을 채우세요 (알아낼 수 없을 때만 저에게 물어보세요): - **스펙 소스**: 직접 찾아보세요 - 파트 0 참조. 찾기 전에 URL을 묻지 마세요. 찾은 것이 스크립트의 기본값이 되며, `OPENAPI_URL` 환경 변수로 재정의할 수 있습니다. - **스냅샷 경로**: `api-spec/openapi.yaml` · **보고서 경로**: `api-spec/CHANGES.md` - **교차 참조할 소스 루트**: `src/` (이 저장소의 구조에 맞게 조정) - **응답 검증 라이브러리**: zod (이 저장소가 다른 것을 사용하면 조정) - **스냅샷을 git에 넣을까요?** yaml은 **gitignore** 처리하고 (히스토리에 너무 크고/시끄러움) **`CHANGES.md`는 커밋**하세요 - 생성된 보고서가 무엇이 언제 변경되었는지에 대한 지속적인 기록입니다. 또한 `api-spec/openapi-*.yaml` 및 `api-spec/CHANGES-*.md` (날짜가 있는 수동 아카이브)도 무시하세요. 먼저 이 저장소를 읽어보세요 (패키지 매니저, 스크립트 규칙, API 호출 및 응답 스키마 작성 방식) 그리고 그 스타일에 맞추세요. 경로를 임의로 만들지 마세요 - 실제 경로를 grep으로 찾으세요. --- ## 파트 0 - 무엇이든 작성하기 전에 스펙 찾기 먼저 이 작업을 수행하고 찾은 내용을 알려주세요. URL을 추측하지 말고, 이 단계가 빈 결과가 나올 때까지 묻지 마세요. **1. 문서 - 가장 저렴한 방법이며, 일반적으로 정확합니다.** `README.md`, `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, `docs/`, `.github/`, `.cursor/rules/` 아래의 모든 것, `*.http`/`*.rest` 스크래치 파일, 또는 위키 체크아웃. URL은 종종 산문("API 문서: …/swagger"), 설정 단계, 또는 백엔드 저장소 링크 옆에 있습니다: ```bash grep -rniE 'swagger|openapi|api-?docs|redoc|\/v3\/api-docs' --include='*.md' --include='*.mdx' --include='*.txt' --include='*.http' --include='*.rest' . | grep -v node_modules ``` 두 가지 주의사항: **Swagger UI 링크** (`…/swagger-ui/index.html`, `…/docs`, `…/redoc`)는 HTML 페이지이지 스펙이 아닙니다 - 그로부터 머신 URL을 유도하고 (`/swagger-ui/index.html` → `/v3/api-docs`, `/docs` → `/openapi.json`, `/redoc` → HTML의 `spec-url`) curl로 확인하세요. 그리고 문서 URL은 **오래되었을 수 있습니다** - 채택하기 전에 응답하는지 확인하고, README가 죽은 곳을 가리키면 알려주세요. **2. 저장소 안이나 근처에 이미 있는 스펙 파일** - 누군가 보통 하나를 벤더링해 두었습니다: ```bash find . -path ./node_modules -prune -o -iregex '.*\(swagger\|openapi\|api-docs\).*\.\(ya?ml\|json\)' -print git ls-files | grep -iE 'swagger|openapi|api-docs' ``` 또한 `node_modules/.cache/`, `.next/cache/`, `dist/`, `build/`, `coverage/` 및 gitignore된 `api/`, `api-spec/`, `docs/`, `schemas/` 폴더를 확인하세요 - 이전 코드젠 실행이 거기에 복사본을 남겼을 수 있습니다. 오래된 캐시 복사본도 유용합니다: 스냅샷을 시드할 **기준선**이므로 첫 번째 실제 diff가 "모든 것이 새 것" 대신 의미가 있습니다. 하나를 찾으면 신뢰하기 전에 얼마나 오래되었는지 말하세요 (`git log -1` / 파일 mtime). **3. 이미 소스를 명명하는 생성기 구성** - 이것은 팀이 실제로 사용하는 URL이나 경로를 가리키므로 가장 신호가 강한 히트입니다: ```bash grep -rniE 'openapi|swagger|api-docs' --include='*.json' --include='*.ts' --include='*.js' --include='*.mjs' --include='*.yaml' --include='*.yml' --include='.env*' --include='Makefile' --include='*.sh' -l . | grep -v node_modules ``` 특히 다음을 찾으세요: `openapi-typescript` / `orval.config.*` / `kubb.config.*` / `swagger-typescript-api` / `@hey-api/openapi-ts` 구성, package.json의 `openapi`-ish npm 스크립트, `.env*` API 기본 URL, `docker-compose.yml` 서비스 URL, CI 워크플로우 단계, 또는 소스 스펙을 인용하는 헤더 주석이 있는 커밋된 생성 클라이언트. **4. API 기본 URL에서 유도.** 기본 URL만 찾으면 이 백엔드의 프레임워크에 대한 일반적인 경로를 먼저 탐색하세요 - FastAPI `/openapi.json`, Spring/springdoc `/v3/api-docs` (+ `.yaml`), ASP.NET `/swagger/v1/swagger.json`, NestJS `/api-json`, Rails/rswag `/api-docs/v1/swagger.yaml`, 일반 `/openapi.yaml` 및 `/swagger.json`: ```bash curl -sS -o /dev/null -w '%{http_code} %{content_type} %{url_effective}\n' <BASE>/openapi.json ``` 어떤 것이 응답했는지 보고하세요. 모두 인증이 필요하면 말하세요 - 스크립트에 토큰을 넣지 마세요. **5. 아무것도 작동하지 않나요?** 그런 다음 저에게 물어보고, 무엇을 배제했는지 알려주세요. ### 스펙이 HTTP로 접근할 수 없는 경우 가져오기 설계를 강제하지 마세요. 소스를 단일 `SPEC_SOURCE`로 만드세요 - **URL, 로컬 경로, 또는 셸 명령** (예: 백엔드 저장소의 자체 `make openapi`, 또는 형제 체크아웃의 생성된 파일)일 수 있으며, 다음 순서로 해석됩니다: `--to <file>` 플래그 → `OPENAPI_URL` 환경 변수 → 발견한 기본값. 다운스트림의 모든 것 - diff, 보고서, 스냅샷 - 은 변경되지 않습니다. `CLAUDE.md`에 이 저장소가 어떤 것을 사용하는지와 새로 고치는 방법을 말하세요. ## 파트 1 - `scripts/sync-api.mjs` 의존성이 적은 단일 Node ESM 스크립트 (`js-yaml`이 유일한 새 의존성; 저장소의 패키지 매니저 사용). 플래그: ``` node scripts/sync-api.mjs 원격 가져오기 → 스냅샷과 diff → 보고서 작성 + 스냅샷 덮어쓰기 node scripts/sync-api.mjs --check diff만, 스냅샷은 건드리지 않음, 변경 시 exit 1 (CI 친화적) node scripts/sync-api.mjs --from <file> 스냅샷 대신 <file>과 diff node scripts/sync-api.mjs --to <file> 가져오기 대신 <file>을 "원격"으로 처리 (오프라인) node scripts/sync-api.mjs --json 원시 diff를 JSON으로 stdout에 추가 출력 ``` package.json에 `"sync:api": "node scripts/sync-api.mjs"` 추가. **스냅샷이 아직 없으면**: 가져온 스펙을 스냅샷으로 작성하고, "시드됨 - 백엔드가 배포된 후 다시 실행하여 diff 확인"을 출력하고, exit 0. 전체 API를 "새 것"으로 보고하지 마세요. 예외: 파트 0에서 더 오래된 캐시/벤더 스펙을 찾았다면, **그것**으로 스냅샷을 시드하고 첫 실행에서 라이브 스펙과 실제 diff를 실행하세요 - 기준선이 무엇을 의미하는지 알 수 있도록 캐시 복사본의 날짜를 알려주세요. ### diff해야 하는 것 `paths`를 `"GET /a/b"` → 작업 맵으로 평탄화하고 작업 *및* `components.schemas`를 별도로 diff: **작업** - 추가 / 제거 / 변경 - 매개변수: 새 것 (`required` 플래그), required↔optional 변경, enum 값 추가/제거 - 매개변수를 배열 인덱스가 아닌 `in:name` (또는 `$ref` 매개변수의 경우 `ref:Name`)으로 키 지정 - 요청 본문 및 성공 응답 스키마: `$ref` 이름이 변경되면 이름 변경을 보고; 모양이 **인라인** (`$ref` 없음)이면 여기서 속성을 diff - 이름 없는 스키마는 여기서 diff하거나 어디서도 diff하지 않음. `allOf: [$ref]` 래퍼를 기본 이름으로 해석하고, `oneOf`/`anyOf` 유니온을 `A | B`로 렌더링 (유니온 멤버 획득/상실은 실제 동작 변경). - 새/제거된 비-2xx 상태 코드 - 보안 요구 사항 변경, 새로 `deprecated` **스키마** - 속성 추가 (required 표시) / 제거 / 타입 변경 - enum 값 추가 또는 제거 (스키마 및 각 속성에서, `items.enum` 포함) - required↔optional 변경 ### 이 보고서를 가치 있게 만드는 두 가지 1. **응답 산문에서 `error_code` 추출.** 기계 오류 코드는 보통 각 비-2xx 응답의 `description` 텍스트 외에는 문서화되지 않으므로 ("… 이미 활성 멤버 (already_member)"), 처리해야 할 새 분기는 스키마 수준 diff에는 *아무것도 변경되지 않은 것처럼* 보입니다. **어휘가 아닌 문맥으로** 파싱하세요: `(...)` 안의 토큰, `error_code`-ish 산문 뒤의 토큰, 그리고 일부 스키마의 리터럴 `error_code` enum에 나타나는 snake_case 토큰. 필드 이름이나 enum 값과 충돌하는 토큰을 필터링하지 **마세요** - 그 충돌이야말로 가장 중요한 코드입니다. "필드 X" 표현으로 도입된 토큰은 제외 (그것들은 필드 이름이지 코드가 아님). 추가된 코드를 보고하고, 문서화가 중단된 코드에 대해서는 소스에서 `"that_code"`를 grep하고 **어느 파일이 그것을 분기하는지** 말하세요 - 그것은 죽은 분기입니다. 2. **모든 변경 사항을 실제 코드와 교차 참조.** `git ls-files --cached --others --exclude-standard <src root>`를 통해 모든 소스 파일을 한 번 로드 (이 세션에서 추가된 호출 사이트가 포함되도록 추적되지 않은 파일 포함; 작업 트리에서 삭제된 파일은 건너뜀), 그런 다음: - **경로에 대한 호출 사이트**: 경로 매개변수를 단일 세그먼트 와일드카드로 바꾸고 일치가 따옴표/백틱/`?`에서 끝나야 하므로 `/orgs/{id}`가 `/orgs/${id}/archive`와 일치하지 않도록 함. 제거/변경된 각 작업은 호출 사이트를 나열하거나 "⛔ 호출 사이트 없음". - **스키마 미러**: 스펙 스키마의 응답 검증 미러를 보유한 파일 찾기 - `fooBarSchema`를 어디서나 일치시키고, **`schemas.ts` 안에서만** 순수 PascalCase 이름도 일치 (다른 곳에서는 관련 없는 TS 식별자와 충돌). 이 저장소가 실제로 사용하는 명명 규칙에 맞게 조정 - 먼저 grep. - 경로가 이미 `src/`에서 참조되는 새 작업은 "⚠️ 경로 이미 참조됨 - 메서드 확인" 메모를 받음. ### 보고서 형식 (`api-spec/CHANGES.md`) 생성 날짜, 기준선 레이블, 스펙 `info.version`, 작업 및 스키마 수의 before→after가 있는 헤더; 작은 추가/제거/변경 테이블; 그런 다음 이 순서로 섹션: - `## 🔴 제거된 작업 - 호출하면 깨짐` (호출 사이트 포함) - `## 🟡 변경된 작업` (변경당 중첩 불릿 + 호출 사이트) - `## 🟢 새 작업`, 경로 영역별 그룹화 (첫 세그먼트, 이 API의 접두사에 대한 합리적인 특수 사례 포함) - 요약, 응답 스키마, 요청 본문 스키마 - `## 🔴 제거된 스키마` (미러 파일 포함) - `## 🟡 변경된 스키마` - **미러된 것이 먼저 정렬되고 미러 파일로 굵게 표시**, 왜냐하면 그것들이 오늘 파싱을 깨뜨릴 수 있는 것들이기 때문; 나머지는 정보용 - `## 🟢 새 스키마` (쉼표로 구분된 한 줄) 변경 사항이 없으면 본문은 정확히 "마지막 스냅샷 이후 변경 사항 없음." 파일 상단에 "손으로 편집하지 마세요"를 넣으세요. 결정이 명확하지 않은 곳에 스크립트 주석을 유지하세요 (error_code 휴리스틱, 경로 매처의 끝 앵커, 추적되지 않은 파일이 포함되는 이유) - 미래의 내가 그것을 읽습니다. ## 파트 2 - `.claude/commands/api-sync.md` 워크플로우를 실행하는 슬래시 명령어 (`/api-sync [scope]`, scope 선택 사항, `implement`도 허용). 프론트매터: `description` + `argument-hint`. 단계: 1. **Diff** - `npm run sync:api` 실행, `api-spec/CHANGES.md` 읽기. 보고서가 플래그할 수 있지만 결정할 수 없는 두 가지 판단 호출을 지적: 라이브 호출 사이트의 변경된 **요청 본문**은 스키마 미러가 없어도 실행 가능 (본문을 수동으로 작성하므로), 새 **`error_code`**는 아직 없는 분기 - 필드 오류라면 토스트가 아닌 필드에 인라인으로 렌더링해야 함. 보고서에 변경 사항이 없다고 하면 그렇게 말하고 중지 - 작업을 만들지 마세요. 2. **모든 항목 분류**: Breaking (P0) · 조용히 잘못됨 - 미러된 스키마가 필수 필드를 얻거나 enum 값이 검증기가 거부하는 값으로 증가 (P0) · 이제 불완전 - 수동으로 작성된 요청 본문이 필드를 얻거나, 분기하지 않는 새 `error_code` (P1) · 화면 언모킹 (P1) · 화면 확장 (P2) · 순수 새 기능 (P3) · 백엔드 전용 (드롭). 항목을 건너뛰지 마세요; 어디에도 맞지 않으면 열린 질문으로 나열하세요. 가정하지 말고 코드에 대해 각 분류를 검증하세요 - 명명된 미러 파일을 열고, 목 픽스처를 grep하고, 화면이 존재하는지 확인하세요. 3. **계획 작성** - `ROADMAP.md` (또는 이 저장소의 해당 항목; 없으면 생성)에 날짜가 있는 섹션, 우선순위로 정렬되고 각 단계가 독립적으로 배포되도록 단계화. 항목당: 변경되는 엔드포인트와 파일, 사용자가 오늘 할 수 없는 것을 나중에 할 수 있는 것 (작업의 요점 - "엔드포인트 X 연결"이 아님), 그리고 차단 여부와 누구에게. 항목당 한 줄. 그런 다음 이 저장소가 유지하는 모든 커버리지/트래커 문서를 업데이트. 4. **채팅으로 보고** - 백엔드가 배포한 것을 평이한 언어로 한 단락, 지금 깨진 것이 있으면 수정할 파일, 단계를 각각 한 줄, 그리고 백엔드 개발자에게만 진짜 질문. 거기서 중지; 인수에 `implement`가 포함된 경우에만 **1단계만** 빌드하고, 이 저장소의 typecheck + lint를 실행하고 계속하기 전에 보고하세요. ## 파트 3 - 연결 - gitignore 항목 추가. - `CLAUDE.md`에 짧은 **백엔드 변경 워크플로우** 섹션 추가 (없으면 생성): 스냅샷은 로컬이고 gitignore되며, `CHANGES.md`는 커밋된 기록이고, `CHANGES.md`는 생성되므로 손으로 편집하지 말고, 백엔드 개발자가 배포했다고 말할 때 `/api-sync`, `npm run sync:api -- --check`로 드리프트 감지, 큰 백엔드 변경 전에 날짜가 있는 `api-spec/openapi-YYYY-MM-DD.yaml`을 커밋된 참조 지점으로 아카이브하는 습관. - 스크립트를 한 번 실행하여 스냅샷을 시드하고, 첫 번째 보고서를 보여주세요 - 스펙이 어디서 왔는지에 대한 한 줄 메모와 캐시 복사본에서 시드한 경우 얼마나 오래되었는지.