docs

ドキュメント

一貫性のある軽量な構成で、docs/ にプロジェクトのドキュメントを作成・管理します。

成果物

以下の成果物を維持してください。

1. docs/SUMMARY.md — Agent Context Guide を含むドキュメントのエントリーポイント（常に再生成）
2. docs/architecture/ — システム設計、インフラストラクチャ、コンポーネント間の連携、データフロー、機能のフロー。ファイルやコードの構成ではなく、システムの動作 に焦点を当てます。
3. docs/codebase/ — ファイルの整理方法、ディレクトリ構成、エントリーポイント、主要モジュールとその役割。コード内の配置場所 に焦点を当てます。
4. docs/code-standard/ — コーディング規約、命名規則、スタイルガイド、環境設定、チームが従う独自のルールやパターン。既存のコードベースに合ったコードの書き方、ベストプラクティス、チームの規約に焦点を当てます。一貫性の維持にとても重要です。
5. docs/project-pdr/ — プロダクトの目標、ユースケース、ビジネスルール、制約、判断の根拠。ユースケースや要件に関するファイルを多く用意するのが望ましいです。

README.md も、現在のドキュメントへのリンクとプロジェクト概要に沿った状態に保ってください。

ワークフロー

ステップ 1：コンテキストの確認

プロジェクトをスキャンして、ドキュメントに記載すべき内容を把握します。

1. 既存のドキュメントがあれば読みます（docs/SUMMARY.md と各トピックフォルダー）。
2. README.md と主要な設定ファイル（package.json、tsconfig.json、Cargo.toml など）を読みます。
3. ソースディレクトリをスキャンして、プロジェクトの構成、エントリーポイント、主要コンポーネントを把握します。
4. 既存のドキュメントを更新する場合は、最近の変更を確認するため git log --oneline -20 を確認します。

事実に焦点を当てます。機能、アーキテクチャ、技術スタック、ディレクトリ構成、ワークフローを確認してください。コードから明らかでない要件を捏造したり、ビジネスロジックを推測したりしないでください。

ステップ 2：動作の推定

• 現在の docs/ の状態に基づき、初回のドキュメント作成が必要か、既存ドキュメントの段階的な更新が必要かを推定します。
• docs/ が存在しない、または明らかに不完全な場合は、初期化の手順を実行します。
• docs/ が標準的な構成ですでに存在する場合は、更新の手順を実行します。
• 該当する場合は、推定した動作を簡潔に述べます。

ステップ 3：ドキュメントの作成

ドキュメントがない、または不完全な場合の初期化

1. docs/ と 4 つのトピックフォルダー（architecture/、codebase/、code-standard/、project-pdr/）を作成します。
2. 各トピックフォルダーについて、以下を行います。 a. 関連情報を得るためにコードベースをスキャンします。 b. コードベースのスキャン結果に基づいて内容を作成します。 c. コードベースから見つかった内容に応じて、トピック固有のファイルを作成します。各ファイルには内容に合った名前を付けます（例：components.md、conventions.md）。汎用的な名前（overview.md、index.md、main.md）は使用しないでください。内容が 2 つ以上の明確に異なるサブトピックを扱う場合は、複数のファイルに分けます。各フォルダーに最低 1 ファイルを作成します。
3. 「コンテンツ要件」で指定された形式に従い、Agent Context Guide を含む docs/SUMMARY.md を作成します。
4. docs/SUMMARY.md へのリンクを README.md に追加します。

各ファイルには、プロジェクトに即した具体的な内容を記載します。プレースホルダーや汎用テンプレートは避けてください。

ドキュメントがすでにある場合の更新

1. 変更点を特定します。現在のコードと既存のドキュメントを比較します。git log --oneline とソースファイルのスキャンを使って、新規・変更・削除されたコンポーネントを特定します。
2. 有用な既存の内容とセクション構成を維持します。
3. 古くなったセクションや不正確なセクションは、最初から書き直さず、その箇所を更新します。
4. 新たに見つかった機能、コンポーネント、規約を追加します。
5. 明らかに古くなった記述を削除します。
6. 内容の変更に応じて、詳細ファイルを追加・変更・削除します。
7. 現在のファイルに合わせて docs/SUMMARY.md を再生成します。実際にディスク上に存在するファイルのみを記載し、Agent Context Guide を維持します。
8. ドキュメントへのリンクが変わった場合は、README.md を更新します。

重要：目的は、すべてを書き直すことではなく、段階的に必要な箇所だけを更新することです。

ステップ 4：README の同期

README.md に以下が含まれていることを確認します。

• プロジェクトの簡潔な概要
• クイックスタート（プロジェクトにある場合）
• docs/SUMMARY.md へのドキュメントリンク

ステップ 5：品質を検証する

完了する前に、以下を確認してください。

• docs/SUMMARY.md が存在し、実際にディスク上に存在するすべての詳細ファイルを記載している（存在しないファイルが含まれていない）
• 各トピックフォルダーに、そのトピックに固有のファイルが少なくとも 1 つある
• トピックフォルダーに汎用的なファイル名（overview.md、index.md、main.md）がない
• README.md のリンクが docs/SUMMARY.md を参照している
• SUMMARY.md が簡潔で、Agent Context Guide を含み、すべてのセクションのファイルテーブルを含んでいる
• ファイル間で用語が統一されている
• ドキュメントとコードの間に矛盾がない
• パスとコンポーネント名が正確である
• 内容が簡潔で、具体的かつ実行可能である

内容要件

SUMMARY.md の形式

プロジェクトの概要、簡潔な Agent Context Guide、各ドキュメントセクションのファイルテーブルを含めます。

references/summary-template.md のテンプレートに厳密に従ってください。

Agent Context Guide は、プロジェクトのコンテキスト読み込みに限定してください。

• docs/SUMMARY.md が存在する場合は、最初に読む
• タスクに関連する詳細ドキュメントのみを読み込む
• 実装規約については Code Standard ドキュメントを優先する
• ドキュメントがコードやユーザーの意図と矛盾する場合は、大幅な変更を行う前に、利用可能な入力や質問を確認する

このガイドを使って、一般的なエンジニアリング原則、Git のルール、詳細な質問ツールの手順を重複して記載しないでください。

トピックファイルのルール

• 各ファイルでは、フォルダー内の特定のサブトピックを 1 つ扱う
• 内容を表すスラッグ名を付ける：components.md、conventions.md、product-goals.md
• 汎用的な名前は使用しない：overview.md、index.md、main.md、general.md
• 行数の目標を設けず、内容を絞って簡潔に保つ

エッジケース

• 最小限／空のプロジェクト：コードベースにコードがほとんどない場合、トピックファイルは短く、事実に即した内容にします。任意のサイズ目標を満たすために内容を水増ししないでください。現時点で記載できる内容が本当にない場合は、セクションに「TBD — プロジェクトの成長に合わせて文書化」と記載します。各フォルダーにファイルが 1 つだけの場合でも、その内容を表す名前を付けてください。
• docs/ 内のカスタムファイル：4 つの標準トピックフォルダー以外にユーザー作成のファイル（例：docs/API.md、docs/deployment.md）がある場合は保持し、SUMMARY.md の「Other」に記載します。移動や名前変更はしないでください。
• モノレポ：プロジェクトに複数のパッケージ／アプリが含まれる場合は、全体の構成を architecture/components.md に記載し、各パッケージの目的を明記します。各パッケージに独自の完全なドキュメント一式を用意する必要はありません。規模に応じた内容にしてください。

ルール

• ドキュメントは事実に基づくものにし、要件を創作しないでください。
• 冗長な説明より、簡潔な更新を優先してください。
• ドキュメントを現在の実装に沿った内容にしてください。
• 不確かな場合は、前提を明示して確認を求めてください。
• 確実に推測できない情報（ビジネス目標、曖昧なモジュールの担当範囲、規約の矛盾、不明確なアーキテクチャ上の判断）については、的を絞った質問をしてください。