AIとの作業の型i-Willink
AIへの開発の頼み方——伝える・確かめさせる・縛る
AIに開発を頼んで思った結果にならないとき、原因の多くは言い回しではなく、AIから見えない情報・終わりを確かめる手段・破れない決まりのどれかが欠けていることです。公式の案内と私たちの運用から、頼み方の型をまとめます。
AIに開発を頼むときに効くのは、うまい言い回しより3つの準備です。AIから見えない情報を伝える、終わったかを確かめる手段を渡す、絶対に破れない決まりは指示でなく仕組みで縛る。
AIに頼んだのに使えないコードが返ってくると、もっとうまい言い回しがあるのではと考えがちです。けれど最近のモデルは、多少雑な頼み方でも意図を読み取ります。うまくいかない原因は、たいてい言い回しの外にあります。
私たちは、開発の多くをAI(Claude Code)に任せています。この記事では、Claude Code の公式の案内が挙げる「うまくいかないときの原因」に沿って、頼み方の型を整理し、私たちが実際に使っている例を添えます。ほかのAIの道具でも、考え方はそのまま使えます。
この記事の要点
- 1頼むときは、対象のファイル・症状・「直った」の状態を先に書く。AIがコードを読んでも分からないことだけを伝える
- 2「終わりました」を信じず、テストや検査のように機械で確かめられる手段を一緒に渡す
- 3絶対に破れない決まりは、強い言葉で書き足すより、仕組み(フックや検査)で止める
うまくいかない原因は、だいたい3つ
思った物と違う、終わったと言うのに終わっていない、してはいけないことをした。この3つのどれかで、それぞれ打ち手が違います。
Claude Code の公式の案内は、作業が思いどおりに進まないときの原因を、ほぼ次のどれかだと整理しています。
- 思っていた物と違う物ができた: AIがコードを読んでも得られない情報が欠けている
- 終わったと言ったのに、終わっていなかった: AIが自分の作業を確かめる手段を持っていなかった
- してはいけないことをした、必ずやる手順を飛ばした: 指示だけでは、それを保証できない
どれも「もっと丁寧に頼む」では直りません。足りないものを足す、という発想で見ると、打ち手がはっきりします。以下、順に書きます。
伝える: コードから分からないことだけ書く
対象のファイル、起きている症状、「直った」と言える状態を先に書きます。AIがコードを読めば分かることは書かなくて構いません。
最近のAIは、作業の最初にコードを読み、ファイルの構成や書き方の決まり、テストの道具を自分で見つけます。技術の組み合わせを長々と説明する必要はあまりありません。足りないのは、コードの中に無い情報です。会議で決めたこと、ある人の頭の中にしかない公開の手順、テストに必要な設定値、などです。
頼み方も同じ考え方で具体的にします。公式の案内の例を日本語にすると、次のような違いです。
| こう頼むより | こう頼む |
|---|---|
| ログインの不具合を直して | 時間切れのあとにログインできないと報告がある。認証のフォルダのトークン更新を見て、再現する失敗テストを書いてから直して |
| カレンダーの部品を足して | 既存の◯◯の部品の書き方にならって、月を選べて年をまたいで送れるカレンダーを作って。新しいライブラリは足さないで |
2つの妥当なやり方のどちらを選ぶか好みがあるなら、それも先に書きます。コードからは読み取れないからです。反対に、どこを直すべきか一緒に探したい段階なら、「このファイルで改善できるところは?」のような大まかな頼み方で十分です。
何度も伝えることは、毎回の指示でなく、AIが毎回読む説明書(Claude Code なら CLAUDE.md)に書きます。ただしこのファイルは毎回すべて読まれるので、短く保ちます。私たちは、毎回読むルール集を「1本足すなら1本退役させる」と決めています。経緯はミスを反省で終わらせず1行のルールにするに書いています。
確かめさせる: 終わりを機械で判定する
「終わりました」という申告でなく、テストや型の検査、表示の確認のように、機械が判定できる終わりの条件を一緒に渡します。
AIは、自分の作業を確かめる手段がないと、見た目で終わったと判断しがちです。そこで頼むときに、何が通れば終わりかを渡します。たとえば「この失敗テストが通るまで」「型の検査とリンターが通るまで」です。
私たちの実験では、AIが「目標の9割を達成した」と申告した作業を機械で測り直すと、実際は55.9%でした。それ以来、終わりの判定は、作業させたAIの申告ではなく、テストや数値の検査の結果で行っています。経緯はAIの「できました」は機械で確かめるにまとめました。
何を作るかがまだ固まっていないときは、いきなり作らせず、先にAIに質問させて仕様を書かせる方法もあります。仕様のファイルができたら新しい会話で作り始め、あとで確かめる役にも同じファイルを渡します。
縛る: 破れない決まりは仕組みで止める
指示やルール集に書いたことは、AIがほぼ毎回守りますが、保証はされません。例外を許せない決まりは、道具の設定で機械的に止めます。
公式の案内は、指示を2種類に分けています。AIが読んで判断するもの(頼み方、説明書)と、道具が必ず実行するもの(フック、禁止の設定、検査)です。どれだけ強い言葉で書いても、前者を守るかどうかは毎回AIの判断になります。
案内には、説明書の一行に強調を足し続けても守られないなら、その一行はフックに移すべきだという助言もあります。私たちも、変更履歴を強制的に書き換える操作や、中身のない変更記録のメッセージは、指示ではなく仕組みで止めています。AIが同じ操作をしようとしても、道具の側で弾かれます。
反対に、ただの好みにすぎないものまで仕組みで縛ると、AIが状況に合わせて判断する余地がなくなります。例外がありうることは説明書に、例外を許さないことは仕組みに、と分けています。
もうやらなくてよい頼み方
「重要」と大文字で強調する、「よく考えて」と書き足す、は今のモデルでは効き目が小さくなりました。
古いモデル向けに広まった頼み方の中には、今は要らないものもあります。公式の案内が挙げているのは、たとえば次のようなものです。
- 「重要」や大文字で強調する: 今のモデルは普通に書いた一行に従います。強調を重ねると、かえってその決まりを当てはめすぎます
- 「段階的に考えて」「丁寧に」と書く: ただの文として読まれ、考える深さの設定そのものは上がりません。深さは道具側の設定(effort)で変えます
一方で、作る範囲は今でも伝える価値があります。AIは頼まれたことを控えめに読み、最小限の物を作りがちです。空の状態やエラーの表示まで含めてほしいなら、そう書きます。どこまで作ってほしいかは、頼む人にしか分からないからです。
よくある質問
プロンプトのテンプレートを作っておくべきですか?
毎回同じ項目を書く作業(不具合の報告など)には役に立ちます。ただ、技術の組み合わせのようにAIがコードから読める情報は、テンプレートに入れなくて構いません。
ChatGPT や Cursor でも同じ考え方は使えますか?
見えない情報を伝える、終わりを確かめる手段を渡す、破れない決まりは仕組みで止める、という考え方は道具を選びません。設定の名前や仕組みは、それぞれの説明で確かめてください。
説明書(CLAUDE.md)には何を書けばよいですか?
作業の確かめ方(テストや検査のコマンド)、コードが誤解を招く場所、コードに無い決めごと、2回以上直させたことです。コードを読めば分かることは書きません。
AIの作業を見ていられないときは、どうすればよいですか?
終わりの条件と、止める条件(回数や金額の上限)を先に渡してから任せます。結果は申告でなく、検査の結果や変更の中身で確かめます。
参考・出典
- Best practices for Claude Code(Claude Code 公式ドキュメント)(うまくいかないときの原因の整理、具体的な頼み方の例、指示と仕組みの違い、もうやらなくてよい助言)
- Hooks reference(Claude Code 公式ドキュメント)(道具の側で操作を止める仕組み)