documenting

name	documenting
description	README、ADR、Runbook、API Docs、開発者向けドキュメント、コードコメントなど、技術文書を作成・更新するときに使う。変更理由、影響範囲、互換性、運用注意、戻し方を整理し、未来の開発者が最短で理解できる文書にする。

ドキュメントの目的

目的：未来の自分（または他者）が「なぜ・何が・どう使う」を最短で理解できるようにする

作業手順

ドキュメントを作成・更新するときは、次の順序で進める。

1. ドキュメントする内容を調査する。
2. 読み手、目的、調査結果をもとにドキュメントの構成を決定する。
3. 決定した構成に沿ってドキュメントの内容を作成する。
4. 必ずドキュメント全体を読み、次の観点でレビューする。
   • 冗長な内容がないか。
   • 重複した内容がないか。
   • 文章全体の整合性が自然か。
   • Progressive Disclosure を念頭に、ドキュメントを分割する必要がないか。
5. レビュー結果を反映する。部分的な修正に固執せず、必要であれば構成から再検討してドキュメント全体を再構築する。

どこに何を書くか（ドキュメントの地図）

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段落」を意識

コードブロック

• コードブロックの前後には必ず空行を入れる
• 説明 → コード → 補足 の構成を意識