API ハンドオフモード

チャット出力なし: ハンドオフドキュメントのみを生成します。議論、説明はなく、ハンドオフファイルに保存されたマークダウンブロックのみです。

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

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

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

目標

フロントエンド AI が UI/統合を正しく自信を持って構築するために必要なすべてのコンテキストを含む、コピペ即時使用可能なハンドオフドキュメントを作成します。

入力

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

ワークフロー

1. コンテキスト収集 — 機能名、関連エンドポイント、DTO、認証ルール、エッジケースを確認します。
2. ハンドオフファイルを作成/更新 — .claude/docs/ai/<feature-name>/api-handoff.md にドキュメントを記述します。フィードバック後に再実行する場合は、イテレーションサフィックス（-v2、-v3 など）をインクリメントします。
3. テンプレートを貼り付け — 下記のすべてのセクションを具体的データで埋めます。本当に適用できないセクションのみを省略します（理由を記載）。
4. ダブルチェック — ペイロードが実際の API 動作と一致すること、認証スコープが正確であること、列挙値/バリデーションがバックエンドロジックを反映していることを確認します。

出力形式

以下のように構造化された単一のマークダウンブロックを生成します。簡潔に保つ—余分な説明や繰り返しはありません。

---

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

## ビジネスコンテキスト
[2～4文: これが何の問題を解決するのか？誰が使うのか？なぜ重要なのか？フロントエンドが理解する必要があるドメイン用語を含めます。]

## エンドポイント

### [METHOD] /path/to/endpoint
- **目的**: [1行: 何をするのか]
- **認証**: [必要なロール/パーミッション、または「public」]
- **リクエスト**:
  ```json
  {
    "field": "type — 説明、制約条件"
  }

• レスポンス (成功時):

  {
    "field": "type — 説明"
  }
  

• レスポンス (エラー時): [HTTP コードと形状、例: 422 バリデーション、404 未検出]
• 注記: [エッジケース、レート制限、ページネーション、ソート、明らかでない事項]

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

データモデル / DTO

[フロントエンドが受信または送信する主要モデル/DTO をリストします。フィールド型、null 可能性、列挙値、ビジネス上の意味を含めます。]

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

列挙値と定数

[フロントエンドが知る必要があるすべての列挙値、ステータスコード、マジック値をリストします。関連する場合は表示ラベルを含めます。]

値	意味	表示ラベル
pending	レビュー待機中	Pending

バリデーションルール

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

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

• [各非明白な動作、制約、または落とし穴を箇条書きします]
• [例: 「ユーザーは 1 日 1 回のみ送信可能」「ソフト削除されたアイテムはデフォルトで除外」]

統合に関する注記

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

テストシナリオ

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

1. ハッピーパス: [簡潔な説明]
2. バリデーションエラー: [何がトリガーするか、予想されるレスポンス]
3. 見つかりません: [404 が返される場合]
4. アクセス権限なし: [403 が返される場合]

未解決の質問 / TODO

[未解決のもの、PM の決定待ち、またはフロントエンド入力が必要なもの。ない場合はセクションを省略します。]

---

## ルール
- **チャット出力なし**—ハンドオフマークダウンブロックのみを生成します、それ以外は何もありません。
- 正確に: 型、制約、例—曖昧な説明ではなく。
- 有用な場合は実際のペイロード例を含めます。
- 非明白な動作を浮き彫りにします—フロントエンドが「単に知っているだろう」と仮定しないでください。
- バックエンドがトレードオフや仮定を行った場合、それを文書化します。
- スキャン可能に保つ: ヘッダー、テーブル、箇条書き、コードブロック。
- バックエンド実装の詳細を含めない（ファイルパス、クラス名、内部サービスなど）、統合に直接関連がない限り。
- 何か不完全または TBD の場合、明示的に記載します。

## 生成後
最終的なマークダウンをハンドオフファイルのみに記述します—チャットに反復処理しないでください。（プラットフォームが確認を必要とする場合は、内容を貼り付けるのではなくファイルパスを参照します。）