i-Willink

AIとの作業の型i-Willink

AIへの開発の頼み方——伝える・確かめさせる・縛る

AIに開発を頼んで思った結果にならないとき、原因の多くは言い回しではなく、AIから見えない情報・終わりを確かめる手段・破れない決まりのどれかが欠けていることです。公式の案内と私たちの運用から、頼み方の型をまとめます。

AIに開発を頼むときに効くのは、うまい言い回しより3つの準備です。AIから見えない情報を伝える、終わったかを確かめる手段を渡す、絶対に破れない決まりは指示でなく仕組みで縛る。

AIに頼んだのに使えないコードが返ってくると、もっとうまい言い回しがあるのではと考えがちです。けれど最近のモデルは、多少雑な頼み方でも意図を読み取ります。うまくいかない原因は、たいてい言い回しの外にあります。

私たちは、開発の多くをAI(Claude Code)に任せています。この記事では、Claude Code の公式の案内が挙げる「うまくいかないときの原因」に沿って、頼み方の型を整理し、私たちが実際に使っている例を添えます。ほかのAIの道具でも、考え方はそのまま使えます。

この記事の要点

  1. 1頼むときは、対象のファイル・症状・「直った」の状態を先に書く。AIがコードを読んでも分からないことだけを伝える
  2. 2「終わりました」を信じず、テストや検査のように機械で確かめられる手段を一緒に渡す
  3. 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の作業を見ていられないときは、どうすればよいですか?

終わりの条件と、止める条件(回数や金額の上限)を先に渡してから任せます。結果は申告でなく、検査の結果や変更の中身で確かめます。

参考・出典

AI 導入の支援

仕事の手間を、仕組みに任せませんか。

AI と業務システムの導入を支援しています。自分たちで回して確かめた仕組みだけを入れます。最初の相談は無料です。

相談する

最新記事をメールで受け取る