ドキュメント

docs/ にプロジェクトドキュメントを一貫した軽量な構造で作成・維持します。

出力内容

以下の出力を維持します:

1. docs/SUMMARY.md — ドキュメントエントリーポイント (常に再生成)
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. コンテンツ要件で指定されたフォーマットを使用して docs/SUMMARY.md を作成
4. docs/SUMMARY.md へのリンクで README.md を更新

各ファイルに具体的なプロジェクト固有のコンテンツを入れます。プレースホルダーと汎用テンプレートを避ける。

ドキュメントが既に存在する場合は更新

1. 変更内容を検出: 現在のコードを既存ドキュメントと比較。git log --oneline とソースファイルスキャンを使用して新規/変更/削除されたコンポーネントを識別。
2. 有用な既存コンテンツとセクション構造を保持。
3. 古いまたは不正確なセクションを現地で更新 — 完全な書き直しはしない。
4. 新たに発見された機能、コンポーネント、規約を追加。
5. 明らかに廃止されたステートメントを削除。
6. コンテンツの変更に基づいて必要に応じて詳細ファイルを追加、変更、削除。
7. docs/SUMMARY.md を再生成して現在のファイルに一致させる — 実際にディスク上に存在するファイルのみをリストアップ。
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 は簡潔で、すべてのセクションのファイルテーブルを含む
• 用語はファイル全体で一貫
• ドキュメントとコード間に矛盾がない
• パスとコンポーネント名が正確
• コンテンツは簡潔で具体的かつ実行可能

コンテンツ要件

SUMMARY.md フォーマット

プロジェクト概要と各ドキュメントセクションのファイルテーブルを含む。

references/summary-template.md のテンプレートに厳密に従う。

トピックファイルルール

• 各ファイルはそのフォルダ内の 1 つの特定の小テーマに焦点を当てる
• コンテンツスラッグで命名: components.md, conventions.md, product-goals.md
• 汎用名を使用しない: overview.md, index.md, main.md, general.md
• 行数ターゲットを強制せずにファイルを焦点を絞り簡潔に保つ

エッジケース

• 最小限/空のプロジェクト: コードベースのコードが非常に少ない場合、トピックファイルを短く事実に保ちます。任意のサイズターゲットに達するためにコンテンツを埋めません。プロジェクトが成長するにつれてドキュメント化されるべき「TBD」とマークします。1 フォルダあたり 1 ファイルでも、それをコンテンツで命名します。
• docs/ 内のカスタムファイル: 4 つの標準トピックフォルダ外のユーザー作成ファイルを保持 (例: docs/API.md, docs/deployment.md)。SUMMARY.md の「Other」の下にリストアップ。移動またはリネームしない。
• Monorepo: プロジェクトが複数のパッケージ/アプリを含む場合、architecture/components.md の全体構造をドキュメント化し各パッケージの目的を記述。各パッケージが独自の完全なドキュメントセットを必要としません — 比例して保つ。

ルール

• ドキュメントは事実ベース。要件を発明しない。
• 冗長なプロズより簡潔な更新を優先。
• ドキュメントを現在の実装に一致させて保つ。
• 不確かな場合、仮定を明示的にマークし確認を要求。
• 情報を信頼性を持って推測できない場合は対象質問をする (ビジネス目標、曖昧なモジュール所有権、矛盾する規約、不明なアーキテクチャ決定)。