「コメントは最小限にして」とAIへの指示書に書いたのに、出てきたコードはコメントだらけ。そんな経験はありませんか。
指示の書き方が悪いのか、AIが言うことを聞かないのか。判断がつかないまま注意書きを足していき、指示書だけが長くなっていく。これは多くの現場で起きていることです。
この記事では、AIへの指示が守られない理由と、実際に数字で効果が出た書き方を紹介します。結論を先に言うと、AIへの指示は「いつも読ませるルール」ではなく「作業手順に組み込んだ検査」にすると効きます。
AIへの指示が守られないのは「思い出せない」から
指示書に書いたルールは、AIがその場で思い出せなければ、書いていないのとほぼ同じです。
理由は、AIが渡された文章のすべてを同じ重さで扱うわけではないからです。大規模言語モデルには、一度に読み込める文章量の上限があります。これをコンテキストウィンドウと呼びます。指示書が長くなるほど、一つひとつのルールはその中に埋もれていきます。
身近な例で考えてみましょう。入社初日に分厚い新人研修マニュアルを渡されたとします。ひととおり目は通しました。それでも3か月後の現場で「あれは何ページに書いてあったか」を思い出せる人は、ほとんどいないはずです。AIへのルール文書も、これと同じ状態になりがちです。
つまり守られない原因は、書いた内容ではなく「思い出す前提で設計していること」にあります。
AIへの指示は「ルール」より「手順」に埋めたほうが効く
同じ内容でも、ルール文書に書くか作業手順に組み込むかで、結果は変わります。
これを実測した報告があります。あるチームがAIの書くコメントを減らそうとして、まずルール文書に「コメントは最小限に」と明記しました。結果、追加されたコード内のコメント比率は18.5%から19.1%へと、ほぼ変化しませんでした。
そこで書く場所を変えます。プルリクエストを作る手順のほうに、追加行からコメント行だけを抜き出して確認する工程を入れました。すると数字が動きました。
- 1件あたりのコメント行数が、中央値で27行から21行へ
- 100〜300行規模の変更でのコメント比率が、19.2%から17.3%へ
- 長いコメントのかたまりを含む件数の割合が、77%から65%へ
差が出た理由ははっきりしています。「文書を読んだときに思い出す」やり方から、「作業の途中で機械的に抜き出して判定する」やり方へ変わったからです。記憶に頼る部分が減れば、そのぶん守られる確率は上がります。
AIへの指示書は200行未満に絞るのが目安
指示書は、長く書くほど効くわけではありません。むしろ短く絞ったほうが効きます。
Claude Codeの指示書であるCLAUDE.mdの場合、公式ドキュメントが「1ファイルあたり200行未満を目安に」と明記しています。長いファイルほどコンテキストを消費し、指示への追従が下がるから、というのが公式の理由づけです。実際に整理してみると、多くのプロジェクトは40行前後に収まるという報告もあります。
削る候補として挙げられているのは、次のような記述です。
- 設定ファイルやフォルダ構成を見れば分かること
- リンター(コードの書き方を自動で点検する道具)がすでに強制している規約
- 使っている技術の単なる列挙
- 互いに矛盾している禁止ルール
逆に残すべきものもあります。見ただけでは分からない環境の落とし穴とその回避策、禁止ではなく「周囲のコードに合わせる」といった判断の基準、削除や本番反映など実行前に確認してほしい操作、そして「どの手順書をいつ使うか」の案内です。
手順やチェックリストそのものは、指示書から切り出して別ファイルにします。必要なときだけ読み込ませる形にすれば、ふだんのやり取りを圧迫しません。
AIへの指示の話は、そのまま人とチームにも当てはまる
ここまでの話は、AI特有のものではありません。人に対する指示や、これから入るチームの運営にもそのまま当てはまります。
守られない規約には共通点があります。だいたいが「覚えていること」を前提にしている、という点です。
たとえば社内ウィキにコーディング規約が30ページあるのに、レビューでは毎回同じ指摘が出る現場があります。一方で同じ項目をリンターやCI(変更のたびに自動でテストを走らせる仕組み)に載せた途端、その指摘は消えます。規約を文書に書くのではなく、仕組みに落としたからです。
入社1〜3年目のうちに、この違いを体で覚えておくと後が楽になります。今日からできることを3つ挙げます。
- AIに同じ注意を2回以上したら、指示書に足す前に「自動で確認できる形」にできないか考える
- 自分の指示書を読み返し、設定ファイルを見れば分かる記述を消す
- チームで毎回同じ指摘が出る項目を1つ選び、自動チェックにできるか調べてみる
指示を増やすのではなく、確認できる形に変える。この発想の転換が要点です。
まとめ:AIへの指示は書く量より効かせ方
- AIへの指示が守られない原因は内容ではなく、「思い出す前提」で設計していること
- ルール文書に書いても数字は動かず、作業手順に検査を組み込むと動いた実例がある
- 指示書は200行未満を目安に絞り、手順は必要なときだけ読む別ファイルへ移す
まずは自分のAI指示書を開いて、設定ファイルを見れば分かる行を1つ消すところから始めてみてください。
あわせて読みたい
AIとの付き合い方は、次の記事もあわせて読むと整理しやすくなります。
コメント