documentation-policy

name	documentation_policy
description	README.mdとblueprint.mdの役割分担と更新義務を定義するドキュメント管理ポリシー。

ドキュメント管理ポリシー

絶対ルール

README.md と blueprint.md は、あらゆる機能追加・変更・リファクタリング時に必ず両方を更新する。 片方だけの更新は禁止。

役割分担

README.md — プロダクトの公式仕様書（ユーザー向け）

主な読者: プロジェクトオーナー（ユーザー）、外部の開発者、コントリビューター

記載すべき内容:

• プロジェクトの概要とビジョン
• 技術スタック（フレームワーク、主要ライブラリ）
• 環境構築手順（.env.local の設定、npm install 等）
• 各環境（Development / Staging / Production 等）の定義と切り替え方法
• ファイル構成とアーキテクチャの概要
• 主要機能の詳細仕様（コアビジネスロジック、外部連携部分等）
• 運用フェーズ・ロードマップの現在地
• デプロイフロー

記載スタイル:

• システムの「何を」「どう使うか」を中心に
• 技術的詳細は必要最小限で、代わりにblueprint.mdへの参照を示す
• 外部に公開されても問題ない内容

blueprint.md — 設計・実装の詳細青写真（AI・開発チーム向け）

主な読者: AIエージェント（新規セッション含む）、開発チーム内部

記載すべき内容:

• 各機能の設計意図・技術的な背景
• コンポーネント間の依存関係
• データフロー（モック・本番DBの切り替え、外部Webhook機能等）
• 実装済み機能の詳細リスト（いつ、どのような方針で実装されたか）
• 既知の制約やTODO（将来対応予定の項目）
• .agents/skills/ 配下のスキル一覧と概要

記載スタイル:

• 「なぜこうなっているか」「次に何をすべきか」を明確に
• コードの具体的な関数名やファイルパスを含む技術的な詳細
• 新しいAIインスタンスがこれを読めば開発を継続できるレベルの情報量

更新タイミング

イベント	README	blueprint
新機能の追加	✅ 機能仕様を追記	✅ 設計意図と実装詳細を追記
既存機能の変更	✅ 変更された仕様を反映	✅ 変更理由と影響範囲を記録
リファクタリング	✅ アーキテクチャ変更があれば反映	✅ 構造変更の詳細を記録
規約・プロセス変更	✅ 開発手順に影響あれば反映	✅ スキル一覧・ルール変更を反映
バグ修正	− 通常は不要	✅ 既知の制約に影響あれば更新

AIエージェントへの指示

1. タスク完了時に README.md と blueprint.md の更新漏れがないかセルフチェックする
2. 更新が必要かどうか迷った場合は 更新する 側に倒す
3. walkthrough.md に「README/blueprintの更新有無」を必ず記載する