ドキュメントの位置づけ

ドキュメントが担う役割

ドキュメントは、主に 2 つの役割を担う。

• 実装を担う AI が、一貫した判断を下すための材料になる。AI は文面を手がかりに実装するため、書かれた内容がそのまま判断の質を左右する。
• 将来の自分が判断の経緯を追えるようにする。決定の背景や前提が残れば、同じ議論を繰り返さずに済み、後から判断の根拠をたどれる。

残すべきこと

役割を果たすために残すのは、コードからは読み取れない情報である。

• なぜ — 設計判断や採用理由、却下した案など、コードに表れない意図を書く。外部調査や参照した文献・資料もここに含む。
• 決定の記録 — 重要な技術選定や方針を、背景とともに残す。残し方は 意思決定の記録 に従う。
• 全体像 — 個々のコードからは見えない構造や関係を示す。
• 前提と制約 — 守るべき条件や外部との取り決めを明記する。プロダクトの要件・仕様もここに含む。
• 経緯と落とし穴 — 知らないとつまずく注意点を残す。
• 固まった概念 — 仕様が確定し、変わりにくい事柄を扱う。

残すべきでないこと

次の情報は載せない。

• コードを読めば分かること — 実装の逐語的な説明や自明な手順は書かない。コード自体を読みやすく保つ。
• すでに正本がある情報 — 重複の扱い に従う。
• 確定前の推測や揺れる情報 — まだ動く要件や頻繁に変わる詳細は、固まってから書く。
• 古く誤った記述 — 役目を終えた記述は更新するか削除する。
• 秘密情報 — 認証情報やトークンなどは置かない。

関連項目

• ドキュメント体系のつくり方 — どこに何を置くか
• 一つのドキュメントの書き方 — どう書くか