Prune For Readers

---
name: prune-for-readers
description: ドキュメントやコードコメントから、読者にとって価値の無い記述を取り除いて最終状態だけにする。作業の過程・暫定の注記・自明な説明が残っているときに使う。
---

# Prune for Readers

## 入力

`$ARGUMENTS`

対象が指定されていればそれを、無ければ**直近の変更で書いた**ドキュメントとコードコメントを対象にする。

## 原則

永続テキストは**これから読む人のため**にある。書いた人の作業過程を記録する場所ではない。

判定は 1 つ。**その記述が、今後この文書を読む人の判断を変えるか。**

変えないなら落とす。書いた時点では意味があった情報でも、読む時点で価値が無いなら残さない。

## 落とすもの

| 種類 | 例 |
|---|---|
| **作業の過程** | 試して変えた選択肢、検討して却下した案、命名や設定値の変遷 |
| **時点に依存する注記** | 「暫定的に」「今のところ」「将来的には」「一旦」 |
| **コードを読めば分かること** | 処理の逐語訳、変数名の言い換え |
| **文書の自己言及** | 「このセクションでは〜を説明する」「以下に示す」 |
| **一般論** | その場に固有でない、どこにでも書ける説明 |

## 残すもの

| 種類 | 例 |
|---|---|
| **判断の根拠** | なぜこの設計か。他の選択肢が今も有効な場合はその対比を含む |
| **知らないと踏む地雷** | 素直な実装が壊れる理由、ライブラリの落とし穴 |
| **外部制約** | 仕様・API・法令など、コードからは読み取れない縛り |
| **意図的な逸脱** | 通常と違うことをしている理由 |

判断に迷う記述は、**それを消したとき読者が困るか**で決める。困らないなら落とす。

## 対象外

| 対象 | 理由 |
|---|---|
| ADR・Design Doc | 意思決定の記録が目的 |
| commit message・PR 本文 | 変更を述べるのが役割 |
| CHANGELOG | 履歴そのもの |

## 手順

1. 対象のドキュメント・コメントを読む
2. 各記述を上の判定にかけ、落とすものを挙げる
3. 書き換える。理由を述べる必要があるなら、**選んだものの性質**で説明する
4. 判断が割れるものは書き換えず、ユーザーに提示する