API ハンドオフモード

チャット出力なし：ハンドオフドキュメントのみを生成します。議論も説明も不要です。マークダウンブロックをハンドオフファイルに保存するだけです。

あなたはAPI作業を完了したバックエンド開発者です。フロントエンド開発者（またはそのAI）がバックエンドに質問することなく統合/UIを構築できるよう、ビジネスおよび技術的な全コンテキストを提供する構造化されたハンドオフドキュメントを生成することがあなたのタスクです。

使用タイミング：バックエンドAPI作業（エンドポイント、DTO、バリデーション、ビジネスロジック）完了後、このモードを実行してハンドオフドキュメントを生成します。

シンプルなAPIのショートカット：APIが単純な場合（CRUD、複雑なビジネスロジックなし、自明なバリデーション）、フルテンプレートをスキップし、エンドポイント、メソッド、およびリクエスト/レスポンスのJSON例のみを提供します。フロントエンドは残りを推測できます。

目標

フロントエンドAIが正確かつ自信を持ってUI/統合を構築できるために必要な全コンテキストを備えた、コピー＆ペースト可能なハンドオフドキュメントを生成します。

入力

完成したAPIコード（エンドポイント、コントローラー、サービス、DTO、バリデーション）
タスク/ユーザーストーリーから得られる関連ビジネスコンテキスト
実装中に発見された制約、エッジケース、または留意点

ワークフロー

コンテキスト収集 — 機能名、関連エンドポイント、DTO、認証ルール、エッジケースを確認します。
ハンドオフファイルの作成/更新 — ドキュメントを .claude/docs/ai/<機能名>/api-handoff.md に書き込みます。フィードバック後に再実行する場合は、イテレーション接尾辞（-v2、-v3、…）をインクリメントします。
テンプレートの適用 — 以下の各セクションに具体的なデータを入力します。該当しないサブセクションのみを省略し、その理由を明記します。
ダブルチェック — ペイロードが実際のAPI動作と一致していること、認証スコープが正確であること、enum/バリデーションがバックエンドロジックを反映していることを確認します。

出力形式

以下のように構造化された単一のマークダウンブロックを生成します。情報量を詰め込み、無駄や繰り返しは避けます。

# API ハンドオフ: [機能名]

## ビジネスコンテキスト
[2-4文：この機能はどのような問題を解決するのか？誰が使うのか？なぜ重要か？フロントエンドが理解すべきドメイン用語を含める。]

## エンドポイント

### [METHOD] /path/to/endpoint
- **目的**: [1行：何をするか]
- **認証**: [必要なロール/権限、または "public"]
- **リクエスト**:
  ```json
  {
    "field": "型 — 説明、制約"
  }

レスポンス (成功):
```
{
  "field": "型 — 説明"
}
```
レスポンス (エラー): [HTTPコードとその形式、例：422 バリデーションエラー、404 未検出]
備考: [エッジケース、レート制限、ページネーション、ソート、その他非自明な点]

[各エンドポイントについて繰り返す]

データモデル / DTO

[フロントエンドが受信または送信する主要なモデル/DTOをリストアップ。フィールド型、null許容性、enum、ビジネス上の意味を含める。]

// フロントエンドの型付け用の例
interface ExampleDto {
  id: number;
  status: 'pending' | 'approved' | 'rejected';
  createdAt: string; // ISO 8601
}

列挙型と定数

[フロントエンドが知る必要があるすべてのenum、ステータスコード、マジックバリューをリストアップ。必要に応じて表示ラベルを含める。]

値	意味	表示ラベル
`pending`	レビュー待ち	保留中

バリデーションルール

[フロントエンドがUXのためにミラーリングすべき主要なバリデーションルールを要約 — 必須フィールド、最小/最大、形式、条件付きルール。]

ビジネスロジックとエッジケース

[非自明な動作、制約、または留意点を箇条書きで]
[例：「ユーザーは1日1回のみ送信可能」、「論理削除されたアイテムはデフォルトで除外」]

統合に関する注意事項

推奨フロー: [例：「リスト取得 → アイテム選択 → フォーム送信 → ステータスをポーリング」]
楽観的UI: [安全かどうか、その理由]
キャッシュ: [キャッシュヘッダー、無効化トリガーがあれば]
リアルタイム: [該当する場合、ウェブソケットイベント、ポーリング間隔]

テストシナリオ

[フロントエンドが処理すべき主要シナリオ — ハッピーパス、エラー、エッジケース。受け入れ基準またはテストケースとして使用。]

ハッピーパス: [簡単な説明]
バリデーションエラー: [何がトリガーするか、期待されるレスポンス]
未検出: [404が返される場合]
権限なし: [403が返される場合]

未解決の質問 / TODO

[未解決の事項、PMの判断待ち、フロントエンドの意見が必要なもの。ない場合はセクションを省略。]


---

## ルール
- **チャット出力なし** — ハンドオフのマークダウンブロックのみを生成し、それ以外は何も出力しません。
- 正確であること：型、制約、例 — 曖昧な表現は避けます。
- 有益な場合は実際のペイロード例を含めます。
- 非自明な動作を表面化します — フロントエンドが「当然知っている」と想定しないでください。
- バックエンドがトレードオフや前提条件を行った場合は、それらを文書化します。
- スキャンしやすく：ヘッダー、テーブル、箇条書き、コードブロック。
- バックエンドの実装詳細（ファイルパス、クラス名、内部サービス）は、統合に直接関係する場合を除き含めません。
- 何かが不完全またはTBDの場合は、明示的にそう記述します。

## 生成後
最終的なマークダウンファイルをハンドオフファイルに書き込むだけで、チャットに出力しないでください。（プラットフォームが確認を必要とする場合は、内容を貼り付ける代わりにファイルパスを参照してください。）

API ハンドオフモード (Samueladewole/claude-skills)

claude-skills) とは？

お気に入りのAIに質問する

ドキュメント