| name | maintain-agent-dock-docs |
| description | Agent DockのREADME、VISION、DESIGN、DEPENDENCIES、リリース文書、AGENTSを作成、改訂、整理し、記述を読み手、時間範囲、効力、具体度に応じた正本へ配置する。文書の更新、実装結果の反映、方針変更、重複整理、文書間整合の確認を依頼されたときに使う。 |
Agent Dockの文書保守
README.md の「文書の役割と関係」を文書体系の正本として使う。
書こうとする内容の所属先を決めてから編集し、同じ決定や事実を複数の文書で再定義しない。
文書体系を確認する
README.md の「文書の役割と関係」を読む。- 変更対象の文書を全文読む。
- 対象が参照する上位文書と、対象を正本として参照する下位文書を読む。
- 現在の挙動を扱う場合は、対応するリリース文書、実装、テストを確認する。
READMEの文書体系と実際の文書構成が食い違う場合は、個別文書を先に直さず、どちらを正すかユーザーへ確認する。
記述の所属先を決める
編集前に、追加または変更する記述を次の軸で分類する。
- 読み手は、利用者、設計を判断する人、実装者、作業エージェントの誰か。
- 時間範囲は、長期的な方針、対象版の設計、現在の利用方法、特定版の成立事実のどれか。
- 効力は、規範、採択済みの設計判断、検証済みの事実、未決の提案のどれか。
- 具体度は、目的、責務、外部挙動、内部実装のどこまでか。
分類した記述を、READMEに定めた役割へ次のように割り当てる。
- 長期的な目的、概念、原則、成功基準、非目標は
VISION.md に置く。
- VISIONを実現する責務、不変条件、設計上の制約、対象範囲は
DESIGN.md に置く。
- 依存関係の採用、更新、再評価に共通して適用する方針は
DEPENDENCIES.md に置く。
- プロジェクトの概要、現在の導入方法と利用方法、文書への入口は
README.md に置く。
- 特定版で成立した機能、挙動、制限、変更履歴はその版のリリース文書に置く。
- 作業エージェントだけに適用する手順と制約は
AGENTS.md に置く。
- 未決事項と将来の作業候補はIssueに置き、採択済みの仕様として書かない。
- ファイル、関数、データ構造、一時的な実装順序はコードとテストを正とし、長期的に参照する必要がある場合だけ開発者向け文書を検討する。
適切な所属先が存在しない場合は、既存文書へ押し込まず、新しい長期文書が必要な理由と役割をユーザーへ示して承認を求める。
承認された新しい長期文書は、READMEの文書体系へ追加する。
変更の権限を確認する
ユーザーの依頼または既存の承認が変更内容を一意に定めている場合は、その範囲を追加確認なしで編集する。
新しい規範、設計判断、例外、文書間の優先関係を補う必要がある場合は、推測で確定せず、変更案と影響する文書を示してユーザーの承認を得る。
実装結果を文書へ反映するときは、計画や意図を成立済みの事実として扱わない。
コード、テスト、対象commitの差分、実行結果から確認できる範囲だけを書く。
正本へ集約して編集する
- 同じ内容が複数の文書にある場合は、一つを正本とし、ほかは要約とリンクにする。
- 内容を別の文書へ移す場合は、必要な事実を移動先へ保存してから元の重複を削る。
- 上位文書の変更が必要な場合は、上位文書から順に改定する。
- 規範文書へ、個別リリースの実装履歴、現在の完成状況、既知の不具合を混ぜない。
- リリース文書へ、対象版では採択していない将来仕様や新しい規範を混ぜない。
- READMEには現在の利用に必要な情報を残し、各版の詳細な履歴はリリース文書へリンクする。
全文を自己確認する
変更した文書を差分だけでなく全文で読み、次を確認する。
- 各記述が、その文書の読み手、時間範囲、効力、具体度に合っているか。
- 内部実装を同じ外部挙動のまま置き換えたときに古くなる記述が、設計上の制約として理由なく残っていないか。
- 上位文書と下位文書で、主体、対象、時点、決定の効力が矛盾していないか。
- 現在の挙動を述べるREADMEとリリース文書が、実装とテストに対応しているか。
- 同じ決定、条件、例外、履歴を複数の文書で正本のように定義していないか。
- 移動または削除した内容のうち、履歴として保存すべき事実を失っていないか。
完了時は、変更した正本、別の文書へ移した内容、ユーザーの判断を要した事項、確認に使った実装またはリリースを報告する。
