■ 1. 問題意識
- AIが書いたドキュメントの読みにくさ:
- Claude CodeにDesign docやPRを書かせると、情報量は多いのに何を決めたのかが頭に入ってこない
- 気を張って読まないと、一番知りたい結論を読み落とす
- この疲労感の正体を実際のGitHub PRで検証する
- 対象読者:
- Claude CodeなどのAIエージェントに設計書やPRを書かせている人
- Skillやプロンプトの設計を見直したい人
- 生成AIが書いたドキュメントのレビューに疲れた経験がある人
■ 2. AIの文章で疲れる4つの原因
- 前提:
- 内容が間違っているわけではなく、むしろ大抵は正しい
- それでも疲れる理由は4つに集約される
- 網羅と重要度を区別しない:
- 人間は書くべきことと省いてよいことを無意識に取捨選択している
- 生成AIはこの選別が働きにくく、思いつく観点をすべて同じ重みで並べる
- 決定的な判断と自明な前提が同じ文量で説明される
- 重要度を仕分けする作業を読み手が肩代わりさせられる
- 結論が最後に来る:
- 人間は「結論から言うと」と先に言い切ることが多い
- 生成AIは検討過程を順に再生し、最後にまとめとして結論を書く構成を取りがち
- 読み手は結論に着くまで、すべての情報を頭に保持し続ける必要がある
- テンプレートの見出しを律儀に埋める:
- 「背景」「目的」「用語定義」「今後の拡張性」などの定型見出しを、中身が薄くても埋めようとする
- 見出しの数だけ「読まなければならない」という圧力が生まれる
- 自明な項目にも両論併記する:
- 「メリット・デメリット」の型を一度採用すると、不採用案にも機械的に当てはめる
- 要件を読めば最初から成立しないとわかる案にすら丁寧な説明が付く
■ 3. 検証の題材と条件
- 題材:
- ECサイトのショッピングカートに対する割引クーポン適用ロジック
- 要件:
- カートには複数の商品（カテゴリ・単価・数量）が入っている
- クーポンは金額固定割引・割合割引・送料無料の3種類
- 各クーポンに最低購入金額・有効期限・対象カテゴリという適用条件がある
- 併用不可のクーポンが1つでもあれば、割引額が最大のクーポン1枚だけを採用する
- 期限切れなど不正なクーポンは無視し、残りのクーポンで計算を続行する
- 実験条件:
- DDD/OOP的な設計で実装することだけを指定し、Design docの書き方は指定しない
- 工夫なしのSkillと、Design docの書き方に手を入れたSkillで同じ要件を実装させ、PRを比較する
■ 4. Before: 工夫なしのSkill
- Skillの内容:
- Issueを読み、Design docを書いて実装し、PRを作る手順を並べただけのもの
- 設計方針・背景・メリット・デメリットなどを詳しく丁寧に書くよう指示している
- Specificationパターン採用の記述:
- 適用条件を独立したSpecificationクラスで実装し、AndSpecificationで組み合わせる判断
- この判断1つにも単一責任の原則、開放閉鎖の原則などのメリットが並ぶ
- クラス数の増加、間接参照によるコード追跡コストといったデメリットも並ぶ
- 不採用の代替案も4つ列挙:
- 例として、優先順位フィールドで併用可否を判定する案が挙がる
- 要件に「割引額が最大のクーポンを採用する」と明記されており、最初から成立しない案
- それでも採用案と同じ分量でメリット・デメリットが説明される
- 「自明な項目にも両論併記する」がそのまま表れた例
- 膨らんだ分量:
- 「用語定義」「今後の拡張性」まで章が並ぶ
- Design docは284行・8521文字・見出し32個
- PR説明文は1232文字で、実装ファイルの一覧を律儀に書き出している
- コード自体は正しい:
- pytestのテスト24件がすべてPASSし、動作に問題はない
- 問題は設計判断を人間が追うためのドキュメントの分量
- 疲れる本当の理由:
- 情報が間違っているからではない
- 「採用したのはどれで、なぜか」という最重要情報が、不採用案や自明なメリット・デメリットに埋もれる
- 読み終えても結論を拾うのに時間がかかる
■ 5. After: 書き方を指定したSkill
- 追加したDesign docの書き方ガイド:
- 冒頭に結論（採用した設計とその理由）を3行以内で書き、詳細は後に続ける
- 代替案は案・却下理由の2列の表で比較し、メリット・デメリットを毎回文章で書き下さない
- 不採用の選択肢の説明は、却下理由が伝わる最小限の長さにする
- Non-goalsを書き、スコープ外の一般論や将来の拡張可能性の羅列は書かない
- 用語定義・背景・目的・対象読者などの定型セクションは、読み手が用語を知らない場合のみ書く
- 見出しは意味のある単位でのみ作り、同じ内容を複数の見出しで繰り返さない
- 迷ったら削り、そのセクションなしでレビュアーが意思決定を理解できるなら削除する
- 4つの原因との対応:
- Non-goalsは網羅と重要度の混同への対処
- 結論の先頭配置は結論が最後に来る問題への対処
- 定型セクションの省略は見出しを律儀に埋める癖への歯止め
- 代替案の表化は自明な項目への両論併記の防止
- 比較条件:
- 同じIssueで作り直し、実装はBeforeと完全に同一にしてドキュメントの書き方だけを比較する
- 代替案の表:
- 4つの代替案が案と却下理由の表1つにまとまる
- if-else直書きは、条件が増えるほど関数が肥大化し単体テストもしづらいため却下
- バリデーション関数の集合は、条件が状態を持てずクロージャが必要で読みにくいため却下
- ルールエンジンは、非エンジニアが条件を変更できる利点はあるが今回の要件規模には過剰
- 優先順位フィールドは要件と乖離するため却下
- 読みやすさの変化:
- 結論を読めば採用した設計と理由が3行でわかる
- 表を見れば却下理由がひと目でわかる
- 用語定義や対象読者の定型セクションは省いた
- Specification・Strategyパターンは記事の読者なら説明なしで読めると判断した
■ 6. 定量比較
- Design doc行数:
- Before 284行、After 41行
- Design doc文字数:
- Before 8521文字、After 1239文字
- Design doc見出し数:
- Before 32個、After 6個
- PR説明文文字数:
- Before 1232文字、After 396文字
- 差の大きさ:
- Design docは行数・文字数ともに7倍前後、PR説明文はおよそ3倍の差
- 実装は一字一句同じであり、差はすべてドキュメントの書き方から生まれている
■ 7. Skill設計のポイント
- Non-goalsの明記:
- スコープ外の一般論を書かせず、網羅と重要度を混同させない
- 結論の先頭配置:
- 詳細は結論を補強する形で後ろに続ける
- 定型セクションの抑制:
- 用語定義や背景説明は本当に必要な場合だけ書かせる
- 代替案の表化:
- 文章でメリット・デメリットを書き下すと、それだけで数行ずつ増える
- 削除の判断基準:
- そのセクションなしでもレビュアーが意思決定を理解できるかを基準として与える
- 明示の必要性:
- どれも特別な工夫ではない
- 明示的にSkillへ書かない限り、生成AIは網羅する方向にしか倒れない
■ 8. 結論
- 疲れの原因:
- 内容の正しさではなく、AIの4つの癖にある
- 重要度を選別しないこと、結論を後回しにすること
- 型を律儀に埋めること、自明な項目にも両論併記すること
- Skillの効果:
- 同じ要件でも、Skillに対処を明示するだけでDesign docの分量が7倍近く変わった
- 見直すべき点:
- AIの出力そのものを疑う前に、Skillやプロンプトで「何を書かないか」を指定できているかを見直す
- 検証資料:
- 使用したIssueとBefore/Afterの2本のPRはリポジトリに残している
- Before/Afterそれぞれで使ったSKILL.mdの全文もAppendixに掲載している