| 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 に逃がす。
Skill / references（タスク別コンテキスト）
- 特定タスクでだけ必要な判断基準やワークフローは skill に置く
- skill の入口には最小限の判断基準だけを書く
- 詳細、例、チェックリスト、言語別ガイドは references に分ける
Inline（コード内コメント）
- 「なぜそうするか」（意図・背景）
- 直感に反する実装
- 将来の落とし穴
- 参照すべき仕様や ADR へのリンク（可能なら）
文書化の優先順位（何を書けば価値が高いか）
必ず書く価値が高いもの
- 変更の理由（Why）
- 変更の影響範囲（Blast radius）
- 破壊的変更・互換性（Breaking changes）
- 戻し方（Rollback / Revert）
- 運用上の注意（監視、アラート、再実行条件）
書きすぎない方が良いもの
- コードの逐語説明（読むだけで分かるもの）
- 更新されない前提の詳細（すぐ陳腐化する）
- ツール依存の細部（頻繁に変わる）
Progressive Disclosure（段階的開示）
入口になる文書には、判断に必要な最小情報だけを書く。読み手が必要な深さまで段階的に掘れるように、詳細は参照先へ分ける。
- 常に守る作業ルール、リポジトリ固有の注意、必須コマンドは AGENTS.md に置く。
- 特定タスクでだけ必要な判断基準や手順は skill に置く。
- skill の入口には要点だけを書き、詳細、例、チェックリストは references に分ける。
- 人間向けの背景、設計判断、運用手順は README や docs に置く。
- 入口文書を太らせず、必要に応じて詳細へ進める構造を優先する。
ADR のテンプレート
# ADR-XXXX: <短い結論>
## Context
- 背景・問題・制約
## Decision
- 何を選ぶか（結論）
## Alternatives
- 検討した案（簡潔に）
## Consequences
- 良い点 / 悪い点 / 将来の影響
## Notes
- 移行、ロールバック、関連リンク
記述スタイル・ルール
Markdown は「正しく表示されること」よりも
レンダリング後に読みやすいことを重視して記述してください。
要約のための文章と説明のための文章で段落を分ける。
- 要約（結論・ポイント）は短く簡潔に
- 説明（背景・理由）は詳細に
- 要約と説明は段落を分けて書く
段落は必ず 1 行空ける
- Markdown では 改行と段落は別
- 意味の区切りごとに 空行を入れる
- 「思ったより 1 行多めに空ける」くらいがちょうどよい
これは1つ目の段落。
これは2つ目の段落。
これは3つ目の段落。
見出しの扱い
これは段落。
箇条書きの前後も 1 行空ける
- 箇条書きの前後に空行を入れる
- 項目が長い場合は「1項目 = 1段落」を意識
コードブロック
- コードブロックの前後には必ず空行を入れる
- 説明 → コード → 補足 の構成を意識
