「検討した?」に答えるための草案設計──260行のプロポーザルを53行に削ぎ落とした話

前回の記事で、自律エージェントを保留にした翌日に「調査レシピ方式」という発想に辿り着いた話を書きました。

調査レシピ方式の設計がある程度まとまってきた時期に、別の問題が浮上しました。

「プロポーザルが読みにくい」という指摘です。

受けた瞬間、確かにと思いつつ、正直どこをどう直せばいいかがすぐには分かりませんでした。Claude Code と一緒に構造を見直してみたら、原因は意外にシンプルだった。同じ話を3回していた。

何が問題だったか

最初に書いた提案ドキュメントは、こんな構成でした。

- エグゼクティブサマリ
- §1: 出発点となる分析
- §2: アプローチ比較
- §3: 方針B（調査レシピ方式）
- §4: 次のアクション
- §5: 残された検討事項

論理的に見えます。でも読んでみると——エグゼクティブサマリで「方針 B を推奨」と言い、§2で「方針 B を推奨する根拠」を書き、§3で「方針 B の詳細」を書く。同じ結論が3回登場する。

Claude Code がこれを指摘したとき、「あ、確かに」とすぐに腹落ちしました。書いているときは各セクションを独立して考えているので気づきにくいんですが、読む側から見ると、同じ内容の言い換えを延々と読まされている状態になっていた。

草案の目的を問い直す

書き直すにあたって、まず「このドキュメントは誰に何をするためのものか」を確認しました。

草案を持って関係者に話すとき、よく出るのがこういう質問です。

「この件、どうなってるの? 検討した?」

プロポーザルを渡しているのに、その場でゼロから説明し直すようでは本末転倒です。「はい、その件はここで検討済みです。詳しくはこのセクションを」と言えれば十分なはず。

草案の役割は、意思決定の材料を全部詰め込むことではなく、「検討済みテーマのインデックス」を提供することだった。この再認識で、構成が大きく変わりました。

削ぎ落とした後の構成

新しい5セクション構成はこうなりました。

1. 本書の位置づけ
   草案。「検討した?」への答え合わせ用スナップショット

2. いま考えていること
   方針B（調査レシピ方式）を数行で + 詳細ドキュメントへのリンク

3. そう考えている理由
   94件分析と比較の要点だけ（各3〜5行）+ 詳細ドキュメントへのリンク

4. これまで検討してきたこと（インデックス表）
   各ドキュメントを1行ずつ。現在の扱い（本筋/保留/資産/独立）を明記

5. 議論したい・未決のこと
   論点だけを箇条書きで

削ったもの:

残したもの:

結果、260行 → 53行になりました。半分以下どころか、4分の1。

削ぎ落とした後の方が、今何を考えていてどこが未決かが1〜2分で把握できる。全部詰め込んでいた頃より、情報密度は上がっています。逆説的ですが、削る方が伝わる量が増えることがある。

用語は概念と合っていないといけない

ドキュメント整理の中で、もう一つ気になることが出てきました。用語の問題です。

ドキュメント群の中に「PSIRT」という言葉が何度か登場していました。社内では既存の Excel シートの名称に「PSIRT 表」という呼称が使われており、それが引用される形で自然と使われていたのです。

ところで、PSIRT（Product Security Incident Response Team）はセキュリティインシデント専門の用語です。今回扱っているのは、DB のカラム桁不足・テーブル同期漏れ・外部 API 障害といった一般的な開発インシデントで、セキュリティ特有のものではありません。

概念として、合っていない。

こういうケースの整理は少し繊細です。「PSIRT 表」という既存の Excel シート名は社内の固有名詞として引用されているだけなので、それを勝手に変えるのは越権行為になる。一方、私が新たに提案したリポジトリ名には「psirt」を含んでいましたが、それは修正できます。

整理するとこうなりました。

地味な修正ですが、後から読んだ人が「なぜセキュリティ用語が使われているんだろう？」と余計な疑問を持つのを防ぐためには必要だと思いました。概念と用語がずれていると、資料を読んでいる最中に不要な引っかかりが生まれる。 その引っかかりが、本来の議論を邪魔する。

ドキュメントの中で使う言葉は、その言葉が指す概念と合っていた方がいい。書いているときには見過ごしやすいのですが。

現時点での状態

ドキュメント群はいまこんな構成になっています。

docs/impact-analysis/
├── 01-proposal.md               全体方針（方針B中心に再構成）
├── 02-incident-analysis.md      94件分析の詳細
├── 03-approach-comparison.md    アプローチ比較
├── 04-rule-management.md        プレイブック設計（過去資産）
├── 05-agent-design.md           エージェント設計（過去資産）
├── 06-review-recipe.md          調査レシピ方式の草案（現在の本筋）
├── 07-autonomous-agent-approach.md  自律調査方式（保留中の代替案）
├── 08-derivative-initiatives.md    派生施策（4件）
├── 09-incident-data-management.md  インシデントデータ管理
├── 10-operations-coordination.md   関係者調整マター
└── 11-phase0-work-guide.md         Phase 0 作業手順

01-proposal.md が「スナップショット」として機能する形になったので、「ここはどうなってる？」という質問に対して「04を見てください」「07で保留の経緯をまとめています」と指差せるようになりました。

これを持って関係者との対話に進む段階に来ています。Phase 0 の実施計画（対象 PR の選定・評価シートの設計）や、派生施策の先行着手判断など、具体的な論点の整理はこれからです。続きはまた書きます。

参考

技術文書の構造設計や「伝わる書き方」を体系的に学びたい方には、以下の書籍が参考になります。