OpenAPIスペック同期ワークフロー、差分レポート付き、および/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`スクラッチファイル、またはwikiチェックアウト。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 ``` 2つの落とし穴：**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/`フォルダも確認 - 以前のコード生成実行がそこにコピーを残していることが多い。古いキャッシュコピーでも有用：それは**スナップショットをシードするベースライン**であり、最初の実際の差分が「すべてが新しい」ではなく意味のあるものになる。見つけた場合は、信頼する前にそれがどれだけ古いか（`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`っぽい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`環境変数 → 発見したデフォルト。下流のすべて - 差分、レポート、スナップショット - は変更なし。このリポジトリがどれを使うか、そしてそれをどう更新するかを`CLAUDE.md`に書いてください。 ## パート1 - `scripts/sync-api.mjs` 依存関係が少ないNode ESMスクリプト（`js-yaml`が唯一の新しい依存；リポジトリのパッケージマネージャーを使用）。フラグ： ``` node scripts/sync-api.mjs リモートをフェッチ → スナップショットと差分 → レポートを書き込み + スナップショットを上書き node scripts/sync-api.mjs --check 差分のみ、スナップショットは触らない、ドリフトしたらexit 1（CI向け） node scripts/sync-api.mjs --from <file> スナップショットの代わりに<file>と差分 node scripts/sync-api.mjs --to <file> <file>を「リモート」として扱い、フェッチしない（オフライン） node scripts/sync-api.mjs --json 生の差分もJSONとしてstdoutに出力 ``` package.jsonに`"sync:api": "node scripts/sync-api.mjs"`を追加。 **スナップショットがまだ存在しない場合**：フェッチしたスペックをスナップショットとして書き込み、「シード済み - バックエンドが出荷した後に再実行して差分を確認」と表示し、exit 0。API全体を「新しい」と報告しないでください。例外：パート0で古いキャッシュ/ベンダー提供スペックが見つかった場合、代わりに**それ**からスナップショットをシードし、初回実行でライブスペックとの実際の差分を実行 - ベースラインが何を意味するかわかるようにキャッシュコピーの日付を教えてください。 ### 差分を取るべきもの `paths`を`"GET /a/b"` → オペレーションマップにフラット化し、オペレーションと`components.schemas`を別々に差分： **オペレーション** - 追加 / 削除 / 変更 - パラメータ：新しいもの（`required`フラグ）、必須↔任意のフリップ、enum値の追加/削除 - パラメータを配列インデックスではなく`in:name`（または`$ref`パラメータの場合は`ref:Name`）でキー付け - リクエストボディと成功レスポンススキーマ：`$ref`名が変わった場合はリネームを報告；シェイプが**インライン**（`$ref`なし）の場合は、ここでそのプロパティを差分 - 名前のないスキーマはここかどこでも差分される。`allOf: [$ref]`ラッパーを基になる名前に解決し、`oneOf`/`anyOf`ユニオンを`A | B`としてレンダリング（ユニオンメンバーの獲得/喪失は実際の動作変更）。 - 新しい/削除された非2xxステータスコード - セキュリティ要件の変更、新たに`deprecated` **スキーマ** - プロパティ追加（必須マーク）/ 削除 / 型変更 - enum値の追加または削除（スキーマと各プロパティ、`items.enum`を含む） - 必須↔任意のフリップ ### このレポートを価値あるものにする2つのこと 1. **レスポンス散文からの`error_code`抽出。** マシンエラーコードは通常どこにも文書化されておらず、各非2xxレスポンスの`description`テキスト（「… すでにアクティブなメンバー（already_member）」）にのみあるため、処理する必要がある新しいブランチはスキーマレベルの差分では*何も変わっていない*ように見える。**語彙ではなく文脈で**パース：`(...)`内のトークン、`error_code`っぽい散文の後のトークン、およびいくつかのスキーマのリテラル`error_code`enumに現れる任意のsnake_caseトークン。フィールド名やenum値と衝突するトークンを**フィルタリングしない** - それらの衝突はまさに最も重要なコード。フィールドXという表現で導入されたトークン（それらはフィールド名でありコードではない）はドロップ。追加されたコードを報告し、文書化されなくなったコードについては、ソースで`"そのコード"`をgrepし、**どのファイルがそれで分岐しているか**を言う - それはデッドブランチ。 2. **すべての変更を実際のコードとクロスリファレンス。** `git ls-files --cached --others --exclude-standard <src root>`で全ソースファイルを一度ロード（このセッションで追加されたコールサイトがカウントされるように未追跡を含める；リストされているがワーキングツリーから削除されたファイルはスキップ）、その後： - **パスのコールサイト**：パスパラメータを単一セグメントワイルドカードに変換し、マッチが引用符/バッククォート/`?`で終わることを要求 - `/orgs/{id}`が`/orgs/${id}/archive`にマッチしないように。削除または変更された各オペレーションはコールサイトをリストするか、「⛔ コールサイトなし」。 - **スキーマミラー**：スペックスキーマのレスポンス検証ミラーを保持するファイルを見つける - `fooBarSchema`をどこでもマッチさせ、裸のPascalCase名は**`schemas.ts`内でのみ**（他の場所では無関係なTS識別子と衝突）。命名規則をこのリポジトリが実際に使うものに適応 - まずgrep。 - `src/`でパスがすでに参照されている新しいオペレーションには「⚠️ パスはすでに参照されています - メソッドを確認」ノート。 ### レポート形式（`api-spec/CHANGES.md`） 生成日、ベースラインラベル、スペック`info.version`、前→後のオペレーションとスキーマ数のヘッダー；次に小さな追加/削除/変更テーブル；次にセクション、この順序： - `## 🔴 削除されたオペレーション - 呼び出している場合は破壊的`（コールサイト付き） - `## 🟡 変更されたオペレーション`（変更ごとのネストされた箇条書き + コールサイト） - `## 🟢 新しいオペレーション`、パスエリアごとにグループ化（最初のセグメント、このAPIのプレフィックスに対する適切な特別ケース付き）- 概要、レスポンススキーマ、リクエストボディスキーマ - `## 🔴 削除されたスキーマ`（ミラーファイル付き） - `## 🟡 変更されたスキーマ` - **ミラーされたものを最初にソートし、ミラーファイルで太字** - これらは今日のパースを壊す可能性があるもの；残りは情報提供用 - `## 🟢 新しいスキーマ`（カンマ区切り1行） 何も変わっていない場合、本文は正確に「前回のスナップショットから変更なし。」ファイルの先頭に「手動で編集しないでください」を置く。 決定が明白でない場所ではスクリプトにコメントを残す（error_codeヒューリスティック、パスマッチャーの終端アンカー、未追跡ファイルを含める理由）- 未来の自分がそれらを読む。 ## パート2 - `.claude/commands/api-sync.md` ワークフローを実行するスラッシュコマンド（`/api-sync [scope]`、scopeは任意、`implement`も受け付ける）。フロントマター：`description` + `argument-hint`。ステップ： 1. **差分** - `npm run sync:api`を実行し、`api-spec/CHANGES.md`を読む。レポートがフラグできるが決定できない2つの判断事項を指摘：ライブコールサイトでの変更された**リクエストボディ**は、スキーマミラーがなくても実行可能（ボディを手動で構築するため）、そして新しい**`error_code`**はまだ持っていないブランチ - フィールドエラーの場合はトーストだけでなくフィールドにインラインでレンダリングする必要がある。レポートが変更なしと言う場合は、そう言って停止 - 作業を発明しないでください。 2. **すべての項目を分類**：破壊的（P0）・ 静かに間違っている - ミラーされたスキーマが必須フィールドを獲得したか、enumがバリデーターが拒否する値を増やした（P0）・ 現在不完全 - 手動構築のリクエストボディがフィールドを獲得したか、分岐していない新しい`error_code`（P1）・ 画面のモック解除（P1）・ 画面の拡張（P2）・ 完全に新しい機能（P3）・ バックエンドのみ（ドロップ）。項目をスキップしないでください；どこにも当てはまらない場合は、未解決の質問としてリスト。各分類を推測ではなくコードに対して検証 - 名前付きミラーファイルを開き、モックフィクスチャをgrepし、画面が存在することを確認。 3. **計画を書く** - `ROADMAP.md`（またはこのリポジトリの同等物；なければ作成）に日付付きセクション、それらの優先度で順序付けられ、各フェーズが独立して出荷できるように段階化。項目ごとに：変更されるエンドポイントとファイル、ユーザーが今日できないことで後でできること（作業のポイント - 「エンドポイントXを配線」ではない）、そしてブロックされているか誰に。項目ごとに1行。次に、このリポジトリが保持するカバレッジ/トラッカードキュメントを更新。 4. **チャットで報告** - バックエンドが平易な言葉の1段落で出荷したもの、修正するファイルとともに現在壊れているもの、各フェーズを1行ずつ、バックエンド開発者への本当の質問のみ。そこで停止；引数に`implement`が含まれる場合のみ、**フェーズ1のみ**を構築し、このリポジトリの型チェック + リントを実行してから続行する前に報告。 ## パート3 - 配線 - gitignoreエントリを追加。 - `CLAUDE.md`に短い**バックエンド変更ワークフロー**セクションを追加（なければ作成）：スナップショットはローカルでgitignoreされ、`CHANGES.md`がコミットされた記録、`CHANGES.md`は生成されるので手動編集しない、バックエンド開発者が何か出荷したと言ったら`/api-sync`、ドリフト検出に`npm run sync:api -- --check`、大きなバックエンド変更の前に日付付き`api-spec/openapi-YYYY-MM-DD.yaml`をコミットされた参照ポイントとしてアーカイブする習慣。 - スクリプトを一度実行してスナップショットをシードし、最初のレポートを見せてください - さらにスペックがどこから来たかの1行メモと、キャッシュコピーからシードした場合はそれがどれだけ古かったか。