Claude Code などの AI エージェントに Design doc や PR 説明文を書かせると、内容は正しいのに、読むと妙に疲れることがあります。この感覚を言語化し、Skill の指示を変えるだけでどこまで改善するかを実測した記事が Qiita に公開されました。
- 元記事: 生成AIが書いたドキュメントを読みたくない（依田 健人さん、2026年9月14日）
- 紹介ポスト: @connect24h
紹介ポストの一文がこの記事の要点をよく表しています。
AIが書いた文章は、正しいのに読みにくい。……原因は精度ではなく、重要度を選別せず、結論を後回しにし、テンプレートを律儀に埋め、自明な案にも両論併記するから。
元記事の実験では、Skill（Claude Code に作業手順や書き方のルールを渡す指示ファイル。Agent Skills）の指示を変えただけで、Design doc が 8,521 文字から 1,239 文字に、見出しが 32 個から 6 個に減りました。
本記事では、AI の文章が読みにくくなる 4 つの癖、Before/After の比較結果、自分の Skill に持ち帰るときのチェックポイントを順に整理します。
AI の文章が疲れる 4 つの癖
元記事は、読みにくさの原因を「精度」ではなく「書き方の癖」に求めています。
- 網羅と重要度を区別しない — 思いついた観点をすべて同じ重みで並べる。読み手は、どこが重要かを自分で選別しなければならない
- 結論が最後に来る — 検討過程を順に説明してから結論を書く。読み手は結論にたどり着くまで、すべての情報を頭の中に保持し続けなければならない
- テンプレートの見出しを律儀に埋める — 「背景」「目的」「用語定義」など、中身が薄くても定型セクションを作る
- 自明な項目にも両論併記する — 採用しなかった案にも、メリット・デメリットを丁寧に書き下す
どれも「間違い」ではありません。むしろ「丁寧」と評価されがちな振る舞いです。だからこそ、指示で明示的に止めない限り、エージェントはこの書き方を続けます。
検証：実装は同じ、Skill の指示だけを変える
元記事では、EC サイトのカートに割引クーポン機能を追加する要件を使っています。同じ要件を 2 種類の Skill で Claude Code に実装させ、比較しました。実装とテスト結果は同じまま、変えたのはドキュメントの書き方に関する指示だけです。
Before：工夫なしの指示
Before の Skill に書かれていたのは、次のような「よくある」指示です。
- 検討した設計方針やその背景、メリット・デメリットなどを詳しく記載する
- 実装者以外が読んでも設計の意図がわかるように、丁寧に説明を書く
人間の後輩に頼むなら自然な指示ですが、AI はこれを文字どおり実行します。その結果、採用しなかった代替案 4 つにもそれぞれ詳しい説明が付きました。
After：Design doc の書き方を指定した指示
After の Skill には、次のガイドが追加されています（元記事の After 節より引用）。
## Design docの書き方
- 冒頭に結論（採用した設計とその理由）を3行以内で書く。詳細はその後に続ける
- 検討した代替案は表で比較する（案・却下理由の2列で十分。メリット/デメリットを毎回文章で書き下さない）
- 採用しなかった選択肢の説明は、却下理由が伝わる最小限の長さにする
- 「やらないこと（Non-goals）」を書き、スコープ外の一般論・将来の拡張可能性の羅列は書かない
- 用語定義・背景・目的・対象読者のような定型セクションは、読み手がその技術用語を知らないと判断できる場合のみ書く。自明な場合は省略する
- 見出しは意味のある単位でのみ作る。同じ内容を複数の見出しで繰り返さない
- 迷ったら削る。書いた後に「このセクションがなくてもレビュアーは意思決定を理解できるか」を自問し、できるなら削除する結果：Design doc は約 7 分の 1、PR 説明文は約 3 分の 1
| 項目 | Before | After |
|---|---|---|
| Design doc 行数 | 284 行 | 41 行 |
| Design doc 文字数 | 8,521 文字 | 1,239 文字 |
| Design doc 見出し数 | 32 個 | 6 個 |
| PR 説明文の文字数 | 1,232 文字 | 396 文字 |
Design doc は行数・文字数ともに約 7 分の 1、PR 説明文も約 3 分の 1 になりました。1 つの要件での比較なので、数字そのものは参考値です。それでも、指示を変えただけで分量がこれだけ変わるという事実は、長さの原因が AI の能力ではなく指示側にあることを示しています。
ガイドの各項目が何を止めているか
After のガイドを先ほどの 4 つの癖に対応させると、狙いがはっきりします。
| 癖 | 対応する指示 |
|---|---|
| 網羅と重要度を区別しない | Non-goals を書く／将来の拡張可能性の羅列は書かない／迷ったら削る |
| 結論が最後に来る | 冒頭に結論を 3 行以内で書く |
| テンプレートの見出しを律儀に埋める | 定型セクションは必要な場合のみ／見出しは意味のある単位でのみ |
| 自明な項目にも両論併記する | 代替案は「案・却下理由」の 2 列の表／却下理由が伝わる最小限の長さ |
ポイントは、どの指示も「何を書くか」ではなく 「何を書かないか」「どこで止めるか」 を定めていることです。特に最後の自問「このセクションがなくてもレビュアーは意思決定を理解できるか」は、汎用性が高いと感じます。削除の判断基準を、読み手の目的（意思決定の理解）に固定しているからです。
「詳しく丁寧に」を頼んでいるのは人間側
紹介ポストは次のように締めくくられています。
AIの文章が長いのは、AIが下手だからとは限らない。「詳しく丁寧に」と頼み、網羅性だけを評価している人間側の設計も疑った方がいい。
Skillに書くべきは、何を書くかだけではない。何を書かないかだ。
AI に長い文章を書かせるコストはほぼゼロですが、読むコストは人間が払います。Before の指示は「書き手の抜け漏れ」を防ぐことに最適化されていて、「読み手の時間」を守る制約がどこにもありません。網羅性は評価しやすい指標なので、放っておくとそちらに寄っていきます。
自分の Skill に持ち帰るなら
ここからは元記事を踏まえた筆者の応用です。Design doc 以外にも、同じ考え方はそのまま使えます。
- PR 説明文: 冒頭に「何を変えたか」を 1〜3 行。変更ファイルの羅列はしない（diff を見ればわかる）
- 調査レポート: 結論と推奨を先頭に。調べたが無関係だった事項は書かない
- コミットメッセージ: 「なぜ」を書き、「何を」はコードに任せる
Skill を書くときは、出力の型（見出し・テンプレート）を与えるだけでなく、次の 3 点を明示しておくとよさそうです。
- 結論をどこに、何行で書くか
- 省略してよいセクションと、その判断基準
- 書いた後に削るための自問（読み手はこれがなくても判断できるか）
まとめ
- AI のドキュメントが読みにくい原因は精度ではなく、網羅と重要度を区別しない／結論が最後に来る／テンプレートの見出しを律儀に埋める／自明な項目にも両論併記する、という 4 つの癖にある
- 実装を変えず Skill の指示だけを変えた比較で、Design doc は 8,521 → 1,239 文字、見出しは 32 → 6 個に減った
- 効いたのは「冒頭に結論 3 行」「代替案は表」「Non-goals を書く」「迷ったら削る」といった 書かないことの指定
- 「詳しく丁寧に」とだけ頼む指示は、読み手の時間を守る制約を欠いている。Skill には何を書かないかも書く