backend-docs

バックエンドのドキュメント

コードの根拠に基づいて、バックエンドシステムの客観的な Markdown ドキュメントを作成します。ユーザーが選択したドキュメントの種類のみを生成してください。明示的に依頼されていない限り、ドキュメント一式は作成しないでください。

ドキュメントの選択

ユーザーがドキュメントの種類を指定していない場合は、次の中から1つ以上を選ぶよう尋ねてください。

ユーザーのニーズ	テンプレート
アーキテクチャとバックエンド設計	templates/architecture-design.md
開発者向けオンボーディング	templates/developer-onboarding.md
ギャップ分析と改善の機会	templates/gap-analysis.md
API コントラクトとエンドポイントの動作	templates/api-contracts.md
境界づけられたコンテキストマップと DDD ドキュメント	templates/bounded-context-map.md

ユーザーが出力先パスを指定せずに「バックエンドのドキュメント」を依頼した場合は、docs/backend/ の下に、テンプレート名をファイル名として選択したファイルを作成してください。リポジトリに、より明確なドキュメント規約がある場合は、その規約に従ってください。

引数のルール：

• --mode は、選択されたドキュメントの種類として扱います。
• --backendPath は、調査対象のバックエンドパス、モジュール、境界づけられたコンテキスト、ルートグループ、またはスコープとして扱います。
• --outputPath は、指定された Markdown の出力先として扱います。
• --mode が指定されていない場合は、ユーザーの表現からドキュメントの種類を推測するか、選択するよう尋ねてください。

選択ルール：

• 依頼に境界づけられたコンテキスト、ドメインマップ、サブドメイン、ユビキタス言語、コンテキスト境界、DDD マッピング、またはドメイン領域に関するドキュメントの推奨事項が含まれる場合は、bounded-context-map.md を選択してください。
• DDD も観点の一つである場合でも、主な目的がリスク、コードの不備、違反、または改善の機会を明らかにすることであれば、gap-analysis.md を選択してください。
• 主な目的が、バックエンドの構造や、その設計理由を説明することであれば、architecture-design.md を選択してください。
• ドキュメントの種類によって成果物が大きく異なり、依頼から優先すべき読み手のニーズを判断できない場合に限り、確認の質問をしてください。

ワークフロー

ステップ 1：スコープの確認

対象となるバックエンド、モジュール、サービス、境界づけられたコンテキスト、またはルートグループを特定します。依頼の範囲が広い場合は、まず最も価値の高い領域のみをドキュメント化し、対象外となる範囲を記載してください。

次の情報を収集します。

• ドキュメントの種類と対象読者。
• 対象パスまたはドキュメント規約。
• 特定できる場合は、バックエンドの技術スタックとランタイム。
• 現状、提案する設計、またはその両方のどれを記述するか。

ステップ 2：ルールと既存ドキュメントの確認

実装の詳細を読む前に、references/discovery-workflow.md を読み、プロジェクトのルールを確認してください。

優先順位：

1. プロジェクトの指示：AGENTS.md、CLAUDE.md、.cursor/rules/、.windsurf/rules/、CONTRIBUTING.md。
2. 既存のドキュメント：docs/、ADR、RFC、アーキテクチャのメモ、オンボーディングドキュメント。
3. コードのコントラクト：ルート定義、スキーマ、生成された OpenAPI の設定、データベーススキーマ、マイグレーション、ジョブ、キュー、統合、テスト。

プロジェクトのルールがこのスキルと競合する場合は、プロジェクトのルールを優先してください。

ステップ 3：コードから根拠を収集

エントリーポイントから動作まで、バックエンドの流れを追跡します。大きなコードブロックを貼り付けるのではなく、ファイルを参照してください。

次の項目を確認します。

• アプリケーションの起動処理、依存性注入、ルーティング、ミドルウェア、認証、テナント管理。
• コントローラー、ハンドラー、ユースケース、サービス、ドメインモデル、リポジトリ、データアクセス、外部クライアント。
• API のリクエストとレスポンスのスキーマ、エラー形式、ステータスコード、生成されたドキュメント、クライアントとのコントラクト。
• データベーステーブル、リレーションシップ、マイグレーション、トランザクション、バックフィル、安全性に問題のあるマイグレーションパターン。
• バックグラウンドジョブ、Webhook、キュー、イベントフロー、スケジュールされたタスク、再試行、冪等性、障害処理。
• テスト、オブザーバビリティ、ランブック、フィーチャーフラグ、ロールバック手順、運用上のリスク。

事実は「確認された事実」として記述し、コードやドキュメントに直接記載されていない結論には「推論」と明記してください。

ステップ 4：関連するリファレンスのみを読み込む

段階的開示を活用します。

• ドキュメントの構成と簡潔さについては、references/documentation-principles.md を読みます。
• バックエンドの根拠収集とソーススキルのルーティングについては、references/source-skill-map.md を読みます。
• アーキテクチャ、API、DDD、結合度、データ、品質チェックについては、references/backend-quality-lenses.md を読みます。
• Hono、Zod/OpenAPI、Drizzle、スキーマ検証、生成された API ドキュメント、移行の根拠については、references/framework-contract-notes.md を読みます。
• 選択したドキュメント形式に対応するテンプレートのみを templates/ から読みます。

ステップ 5：Markdown ドキュメントを作成する

選択したテンプレートを構成として使用します。対象読者にとって簡潔で役立つドキュメントにしてください。

生成する各ドキュメントでは、次の点を守ってください。

• 対象範囲、読者、最終レビュー日から始めます。
• 入手可能な場合は、ファイルパスと行番号を示して、具体的なコードやドキュメントを根拠として引用します。
• 現状と推奨事項を分けて記載します。
• 一覧、リスク、API、ギャップ、次のアクションには表を優先して使用します。
• 関係や実行時のフローを明確にする場合に限り、図を含めます。
• 不明点や前提は明記し、不足している情報を推測で補わないでください。
• ドキュメントを更新すべきタイミングを説明する短いメンテナンス注記で締めくくります。

ステップ 6：完了前に検証する

最終回答の前に、次の点を確認します。

• 作成または編集したドキュメントを読み直します。
• 選択したテンプレートに従っていることを確認します。
• 自明でない主張すべてに根拠があるか、推論であることが明示されているかを確認します。
• 無関係なテンプレートを生成していないことを確認します。
• リンクとファイルパスを確認します。
• ドキュメントの書式設定や Markdown の lint に使える検証コマンドがある場合は、プロジェクトで推奨されるコマンドを実行します。

出力ルール

• リポジトリにドキュメントの言語についての規定がある場合を除き、ユーザーの言語で記述します。
• 簡潔で技術的な文章を使用します。宣伝文句や一般論は避けてください。
• 大きなソースコードブロックを重複して掲載せず、ソースのパスへのリンクを使用します。
• ユーザーがその形式を選択した場合、またはリポジトリの慣例で求められる場合を除き、ADR、RFC、TDD を黙って作成しないでください。
• ドキュメント作成中にバックエンドを変更しないでください。ギャップが見つかった場合は、推奨事項として記録します。

例

アーキテクチャと設計

ユーザーの依頼：「請求サービスのバックエンドアーキテクチャをドキュメント化してください。」

対応：templates/architecture-design.md を選択し、プロジェクトのルールと請求関連のコードを調査します。コンポーネントと実行時のフローを整理し、現行アーキテクチャ、決定事項、リスク、改善の機会をまとめた Markdown ドキュメントを 1 つ作成します。

オンボーディング

ユーザーの依頼：「新しいバックエンド開発者がこの API を理解できるよう、オンボーディング用のドキュメントを作成してください。」

対応：templates/developer-onboarding.md を選択し、プロジェクトのドキュメントとコードからセットアップコマンドや主要なフローを特定します。ローカル環境のセットアップから安全な最初のコントリビューションまで進められる、実用的なガイドを作成します。

ギャップ分析

ユーザーの依頼：「このモジュールのバックエンドドキュメントに不足している点と、アーキテクチャ上の問題を見つけてください。」

対応：templates/gap-analysis.md を選択し、プロジェクトのルールに加えて、DDD、結合度、API、データ、テストの観点から分析します。根拠、重大度、次のアクションを含む、優先順位付きの指摘事項を作成します。

境界づけられたコンテキストマップ

ユーザーの依頼：「認証の境界づけられたコンテキストをマップし、追加すべきバックエンドドキュメントを提案してください。」

対応：templates/bounded-context-map.md を選択し、ドメイン分析、戦術的 DDD、結合度、API、データ、プロジェクトルールの観点から分析します。境界、関係、モデルの所有権、リスク、不明点、ドキュメントに関する推奨事項を含むコンテキストマップを 1 つ作成します。