| name | documenting |
| description | README、ADR、Runbook、API Docs、開発者向けドキュメント、コードコメントなど、技術文書を作成・更新するときに使う。変更理由、影響範囲、互換性、運用注意、戻し方を整理し、未来の開発者が最短で理解できる文書にする。 |
ドキュメントの目的
目的：未来の自分（または他者）が「なぜ・何が・どう使う」を最短で理解できるようにする
作業手順
ドキュメントを作成・更新するときは、次の順序で進める。
- ドキュメントする内容を調査する。
- 読み手、目的、調査結果をもとにドキュメントの構成を決定する。
- 決定した構成に沿ってドキュメントの内容を作成する。
- 必ずドキュメント全体を読み、次の観点でレビューする。
- 冗長な内容がないか。
- 重複した内容がないか。
- 文章全体の整合性が自然か。
- Progressive Disclosure を念頭に、ドキュメントを分割する必要がないか。
- レビュー結果を反映する。部分的な修正に固執せず、必要であれば構成から再検討してドキュメント全体を再構築する。
どこに何を書くか（ドキュメントの地図）
README（プロジェクト全体の入口）
- 何のリポジトリか（1〜3行）
- 主要機能・スコープ
- 開発・実行方法（最短コマンド）
- 依存（DB、外部サービス、必要な環境変数）
- よくあるトラブル（FAQ）
README はサブディレクトリにも置く
ADR（Architecture Decision Record：設計判断の記録）
- 「判断」が入った変更
- トレードオフがある選択
- 将来の方向性に影響する決定（境界、依存、DB方針など）
- 既存の ADR は、その時点の判断記録として内容を変更しない
- 判断を変更する場合は新しい ADR を作成し、新しい ADR から置き換え対象の ADR を参照する
Runbook / Ops（運用・障害対応）
- 障害時の切り分け手順
- ログ/メトリクスの見方
- リカバリ手順（ロールバック、再実行、データ修復）
- 定期作業（ジョブ、メンテ、バックアップ）
API Docs（外部IF）
- エンドポイント、入力/出力
- 認証・認可
- エラー形式
- 互換性ポリシー（破壊的変更の扱い）
DEV Docs（開発者向け）
- アーキテクチャ概要（レイヤー、依存方向）
- モジュール構成
- テスト方針（どの層で何を担保するか）
- ローカル環境（devcontainer/compose）
AGENTS.md（エージェント向け常時コンテキスト）
- リポジトリ固有の作業ルール
- 必ず使うコマンド、検証手順、配布手順
- 変更時に常に影響する注意点
- エージェントが毎回知っていないと危険な制約
AGENTS.md は常時読まれる前提で、長くなりすぎないようにする。詳細、例、例外、長いチェックリストは docs、skill、references に逃がす。
