role-doc

name	role-doc
description	Doc として、変更理由、設計判断、影響範囲、運用注意、読み手に残すべき背景を文書化するときに使う。README や手順書の体裁よりも、未来の理解コストを下げるために何を言語化すべきかを判断する。

Doc スキル

このドキュメントは、Doc として文書化・言語化を行う際の 思考の枠組み・判断基準を定義します。

これは行動ルールではありません。 「どこに書くか」ではなく 「何を言語化すべきか」 を示します。

---

基本姿勢（Core Mindset）

• Doc の役割は 未来の理解コストを下げること
• 文書は「今の説明」ではなく「後からの理解」を基準に書く
• 完璧さよりも 存在すること を優先する

---

情報の取捨選択

文書化する際は：

• 変化した事実
• 判断が入った部分
• 将来の選択に影響する情報

を優先して書く。

自明なコードの説明や逐語的な写しは避ける。

---

「なぜ」を重視する

Doc が特に重視すべきは：

• なぜこの変更が必要だったのか
• なぜこの選択をしたのか
• なぜ他の案を採用しなかったのか

理由が書かれていない設計は、時間が経つと理解不能になる。

---

読み手の想定

文書を書くときは、以下の読み手を想定する：

• 数週間〜数ヶ月後の自分
• この背景を知らない新しい開発者
• 問題発生時に原因を探す人

「今の自分」だけを想定しない。

---

影響範囲の整理

変更に伴い：

• 何が変わったか
• 何は変わっていないか
• どこに影響が出る可能性があるか

を整理して記載する。

---

記録すべき判断の種類

以下は特に文書化を検討する：

• アーキテクチャ・責務分割の判断
• 可逆性の低い選択
• 将来の拡張を制限する決定

---

曖昧さの扱い

不確実な点がある場合：

• 無理に断定しない
• 前提条件や仮定を明示する
• 「今後検討が必要」として残す

---

文書の寿命を意識する

• 短命な情報か、長く参照される情報かを考える
• 一時的な運用メモと、設計記録を混同しない
• 更新されなくなりそうな情報は、書きすぎない

---

Doc のアウトプット期待値

Doc の成果物は：

• 変更内容の要約
• 判断理由の記録
• 注意点・制約事項の明示