maintain-agent-dock-docs

name	maintain-agent-dock-docs
description	Agent DockのREADME、VISION、DESIGN、DEPENDENCIES、リリース文書、AGENTSを作成、改訂、整理し、記述を読み手、時間範囲、効力、具体度に応じた正本へ配置する。文書の更新、実装結果の反映、方針変更、重複整理、文書間整合の確認を依頼されたときに使う。

Agent Dockの文書保守

README.md の「文書の役割と関係」を文書体系の正本として使う。 書こうとする内容の所属先を決めてから編集し、同じ決定や事実を複数の文書で再定義しない。

文書体系を確認する

1. README.md の「文書の役割と関係」を読む。
2. 変更対象の文書を全文読む。
3. 対象が参照する上位文書と、対象を正本として参照する下位文書を読む。
4. 現在の挙動を扱う場合は、対応するリリース文書、実装、テストを確認する。

READMEの文書体系と実際の文書構成が食い違う場合は、個別文書を先に直さず、どちらを正すかユーザーへ確認する。

記述の所属先を決める

編集前に、追加または変更する記述を次の軸で分類する。

• 読み手は、利用者、設計を判断する人、実装者、作業エージェントの誰か。
• 時間範囲は、長期的な方針、対象版の設計、現在の利用方法、特定版の成立事実のどれか。
• 効力は、規範、採択済みの設計判断、検証済みの事実、未決の提案のどれか。
• 具体度は、目的、責務、外部挙動、内部実装のどこまでか。

分類した記述を、READMEに定めた役割へ次のように割り当てる。

• 長期的な目的、概念、原則、成功基準、非目標は VISION.md に置く。
• VISIONを実現する責務、不変条件、設計上の制約、対象範囲は DESIGN.md に置く。
• 依存関係の採用、更新、再評価に共通して適用する方針は DEPENDENCIES.md に置く。
• プロジェクトの概要、現在の導入方法と利用方法、文書への入口は README.md に置く。
• 特定版で成立した機能、挙動、制限、変更履歴はその版のリリース文書に置く。
• 作業エージェントだけに適用する手順と制約は AGENTS.md に置く。
• 未決事項と将来の作業候補はIssueに置き、採択済みの仕様として書かない。
• ファイル、関数、データ構造、一時的な実装順序はコードとテストを正とし、長期的に参照する必要がある場合だけ開発者向け文書を検討する。

適切な所属先が存在しない場合は、既存文書へ押し込まず、新しい長期文書が必要な理由と役割をユーザーへ示して承認を求める。 承認された新しい長期文書は、READMEの文書体系へ追加する。

変更の権限を確認する

ユーザーの依頼または既存の承認が変更内容を一意に定めている場合は、その範囲を追加確認なしで編集する。 新しい規範、設計判断、例外、文書間の優先関係を補う必要がある場合は、推測で確定せず、変更案と影響する文書を示してユーザーの承認を得る。

実装結果を文書へ反映するときは、計画や意図を成立済みの事実として扱わない。 コード、テスト、対象commitの差分、実行結果から確認できる範囲だけを書く。

正本へ集約して編集する

• 同じ内容が複数の文書にある場合は、一つを正本とし、ほかは要約とリンクにする。
• 内容を別の文書へ移す場合は、必要な事実を移動先へ保存してから元の重複を削る。
• 上位文書の変更が必要な場合は、上位文書から順に改定する。
• 規範文書へ、個別リリースの実装履歴、現在の完成状況、既知の不具合を混ぜない。
• リリース文書へ、対象版では採択していない将来仕様や新しい規範を混ぜない。
• READMEには現在の利用に必要な情報を残し、各版の詳細な履歴はリリース文書へリンクする。

全文を自己確認する

変更した文書を差分だけでなく全文で読み、次を確認する。

• 各記述が、その文書の読み手、時間範囲、効力、具体度に合っているか。
• 内部実装を同じ外部挙動のまま置き換えたときに古くなる記述が、設計上の制約として理由なく残っていないか。
• 上位文書と下位文書で、主体、対象、時点、決定の効力が矛盾していないか。
• 現在の挙動を述べるREADMEとリリース文書が、実装とテストに対応しているか。
• 同じ決定、条件、例外、履歴を複数の文書で正本のように定義していないか。
• 移動または削除した内容のうち、履歴として保存すべき事実を失っていないか。

完了時は、変更した正本、別の文書へ移した内容、ユーザーの判断を要した事項、確認に使った実装またはリリースを報告する。