概要
AI エージェントに書かせた Design doc や PR 説明文は、内容は正しいのに読むと疲れる。原因は精度ではなく重要度を選別せず、結論を後回しにし、テンプレートを律儀に埋め、自明な案にも両論併記するという書き方の癖で、どれも「丁寧」と評価されがちなので指示で明示的に止めない限り続く。
Skill（Agent Skills の SKILL.md）の指示だけを変えた比較では、実装とテスト結果が同じまま Design doc が 8,521 文字から 1,239 文字、見出しが 32 個から 6 個に減った。Skill に書くべきは何を書くかだけではなく、何を書かないかである。
詳細
4 つの癖と、それを止める指示
| 癖 | 対応する指示 |
|---|---|
| 網羅と重要度を区別しない | Non-goals を書く／将来の拡張可能性の羅列は書かない／迷ったら削る |
| 結論が最後に来る | 冒頭に結論（採用した設計と理由）を 3 行以内で書く |
| テンプレートの見出しを律儀に埋める | 用語定義・背景・目的などの定型セクションは、読み手が知らないと判断できる場合だけ／見出しは意味のある単位でだけ |
| 自明な項目にも両論併記する | 代替案は「案・却下理由」の 2 列の表／却下理由が伝わる最小限の長さ |
どの指示も「何を書くか」ではなく、何を書かないか・どこで止めるかを定めている。最も汎用性が高いのは、書いた後の自問「このセクションがなくてもレビュアーは意思決定を理解できるか」で、削除の判断基準を読み手の目的に固定している。
比較結果（1 要件での参考値）
| 項目 | Before | After |
|---|---|---|
| Design doc 行数 | 284 行 | 41 行 |
| Design doc 文字数 | 8,521 | 1,239 |
| 見出し数 | 32 | 6 |
| PR 説明文 | 1,232 文字 | 396 文字 |
Before の Skill は「設計方針や背景、メリット・デメリットを詳しく」「実装者以外が読んでも分かるよう丁寧に」という、人間の後輩になら自然な指示だった。AI はこれを文字どおり実行し、採用しなかった代替案 4 つにもそれぞれ詳しい説明を付けた。
なぜ指示側の問題なのか
AI に長い文章を書かせるコストはほぼゼロだが、読むコストは人間が払う。「詳しく丁寧に」は書き手の抜け漏れを防ぐことに最適化されていて、読み手の時間を守る制約がどこにもない。網羅性は評価しやすい指標なので、放っておくとそちらに寄っていく。
自分の Skill に持ち帰る
出力の型（見出し・テンプレート）を与えるだけでなく、次の 3 点を明示する。
- 結論をどこに、何行で書くか
- 省略してよいセクションと、その判断基準
- 書いた後に削るための自問
同じ考え方は他の文書にもそのまま使える。
- PR 説明文 — 冒頭に「何を変えたか」を 1〜3 行。変更ファイルの羅列はしない（diff を見ればわかる）
- 調査レポート — 結論と推奨を先頭に。調べたが無関係だった事項は書かない
- コミットメッセージ — 「なぜ」を書き、「何を」はコードに任せる
関連ページ
- ハーネスエンジニアリング — Agent Skills をワークフロー層に置く設計
- Claude Cowork — Agent Skills の背景
- Claude Code — スキルの置き場所と呼び出し方
- Claude Opus 5.5 — 避けてほしいパターンを具体的に並べる指示の例