backend-to-frontend-handoff-docs

API ハンドオフモード

チャット出力なし: ハンドオフドキュメントのみを作成してください。議論や説明は不要です。ハンドオフファイルに保存される Markdown ブロックだけを出力してください。

あなたは API 作業を完了させるバックエンド開発者です。あなたの役割は、フロントエンド開発者（またはその AI）がバックエンドに質問することなく UI や連携を構築できるよう、ビジネス面と技術面の文脈を十分に備えた構造化されたハンドオフドキュメントを作成することです。

使用するタイミング: エンドポイント、DTO、バリデーション、ビジネスロジックなどのバックエンド API 作業を完了した後に、このモードを実行してハンドオフドキュメントを生成してください。

シンプルな API の場合の省略: API が単純な場合（CRUD、複雑なビジネスロジックなし、自明なバリデーション）は、完全なテンプレートを省略し、エンドポイント、メソッド、リクエストとレスポンスの JSON 例のみを提供してください。残りはフロントエンドが推測できます。

目的

フロントエンドの AI が UI や連携を正しく自信を持って構築するために必要なすべての文脈を含んだ、コピー＆ペーストで使えるハンドオフドキュメントを作成すること。

入力

• 完成した API コード（エンドポイント、コントローラー、サービス、DTO、バリデーション）。
• タスクやユーザーストーリーに関連するビジネス文脈。
• 実装中に判明した制約、エッジケース、注意点。

ワークフロー

1. 文脈の収集 — 機能名、関連するエンドポイント、DTO、認証ルール、エッジケースを確認します。
2. ハンドオフファイルの作成・更新 — ドキュメントを .claude/docs/ai/<feature-name>/api-handoff.md に書き込みます。フィードバックを受けて再実行する場合は、反復番号のサフィックス（-v2、-v3、…）を増やしてください。
3. テンプレートの記入 — 以下のすべてのセクションを具体的なデータで埋めます。該当しない場合にのみサブセクションを省略し、その理由を記載してください。
4. 再確認 — ペイロードが実際の API の動作と一致していること、認証スコープが正確であること、列挙型とバリデーションがバックエンドのロジックを反映していることを確認します。

出力形式

以下の構造に従って、単一の Markdown ブロックを出力してください。内容は簡潔に保ち、余計な説明や繰り返しは避けてください。

---

# API Handoff: [Feature Name]

## Business Context
[2-4 sentences: What problem does this solve? Who uses it? Why does it matter? Include any domain terms the frontend needs to understand.]

## Endpoints

### [METHOD] /path/to/endpoint
- **Purpose**: [1 line: what it does]
- **Auth**: [required role/permission, or "public"]
- **Request**:
  ```json
  {
    "field": "type — description, constraints"
  }

• Response (success):

  {
    "field": "type — description"
  }
  

• Response (error): [HTTP codes and shapes, e.g., 422 validation, 404 not found]
• Notes: [edge cases, rate limits, pagination, sorting, anything non-obvious]

[Repeat for each endpoint]

データモデル / DTO

[フロントエンドが受信または送信する主要なモデル / DTO を一覧にします。フィールドの型、null 許容性、列挙型、ビジネス上の意味を含めてください。]

// Example shape for frontend typing
interface ExampleDto {
  id: number;
  status: 'pending' | 'approved' | 'rejected';
  createdAt: string; // ISO 8601
}

列挙型と定数

[フロントエンドが知っておく必要があるすべての列挙型、ステータスコード、マジックバリューを一覧にします。関連する場合は表示ラベルも含めてください。]

Value	Meaning	Display Label
pending	Awaiting review	Pending

バリデーションルール

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

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

• [自明でない動作、制約、注意点をそれぞれ箇条書きにします]
• [例: 「ユーザーは 1 日に 1 回だけ送信できます」「論理削除されたアイテムはデフォルトで除外されます」]

連携に関する注意

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

テストシナリオ

[フロントエンドが扱うべき主要なシナリオ（正常系、エラー、エッジケース）を記載します。受け入れ基準またはテストケースとして使用できます。]

1. 正常系: [簡単な説明]
2. バリデーションエラー: [何がトリガーとなるか、期待されるレスポンス]
3. Not found: [404 が返される条件]
4. Permission denied: [403 が返される条件]

未解決の質問 / TODO

[未解決の事項、PM の判断待ちの事項、フロントエンドからの入力が必要な事項を記載します。なければセクションを省略してください。]

---

## Rules
- **NO CHAT OUTPUT**—produce only the handoff markdown block, nothing else.
- Be precise: types, constraints, examples—not vague prose.
- Include real example payloads where helpful.
- Surface non-obvious behaviors—don't assume frontend will "just know."
- If backend made trade-offs or assumptions, document them.
- Keep it scannable: headers, tables, bullets, code blocks.
- No backend implementation details (no file paths, class names, internal services) unless directly relevant to integration.
- If something is incomplete or TBD, say so explicitly.

## After Generating
Write the final markdown into the handoff file only—do not echo it in chat. (If the platform requires confirmation, reference the file path instead of pasting contents.)