この記事は、筆者が音声入力で話した内容を Claude Code で読みやすく整理したものです。
書いてある主張も検証結果も筆者自身のもので、公開前にすべて目を通しています。
Claude Code（AIに自然な文章で指示を出すとコードを書いてくれるツール）に「集計機能をつけて」のような一言で頼むと、たいていは何かしら動くものが返ってきます。
気になったのは、返ってくるものを決めているのが自分なのかどうかでした。
この記事は、指示の書き方だけを変えて同じ機能追加を二度ずつ頼み、返ってきたものを見比べて、頼み方の型に落とした記録です。
忙しい人のための要約
指示の書き方を見直すかどうかを決めるだけなら、この3点で足ります。
- 曖昧な指示だと、返ってくるものをこちらが決められない
- 曖昧なまま進めたときの直しの往復は平均2.5回だった
- 「何を・どこに・どう・制約は」の4観点で書き直した指示は、二度とも1往復で意図どおりのものに届いた
曖昧な指示が招く「運任せ」
決めているのは自分ではない
一言で頼んで困るのは、動かないものが返ってくることではありません。
返ってくるものを、こちらが決めていないことです。
同じ依頼を、同じコードに対して二度出したのに、返ってきた書き方は一度目と二度目で違いました。
どちらも動きはします。
それでも、どちらになるかを決めたのはこちらではありません。
二度で結果が割れることもあれば、二度とも同じ読み違いに転ぶこともあります。
共通しているのは、どちらもこちらが選んでいないという点です。
往復とコストの差
決まらないのは、返ってくる中身だけではありません。
往復の回数と、それに連れて動く時間やコンテキストの消費にも差が出ました。
曖昧な指示と、「何を・どこに・どう・制約は」の4つの観点をまとめて書いた指示（中身は記事の後半でまとめます）を比べると、こうなります。
コンテキストというのは、Claude Code が一度の会話で抱えていられる情報の量です。
読み込んだファイルの中身も、こちらが送った指示も、やり取りした分だけこの枠を使います。
埋まればどうなるか。
会話を切って、前提を最初から説明し直すことになります。
| 測ったもの | 曖昧な指示 | 4観点で書いた指示 |
|---|---|---|
| 直しの往復 | 平均2.5回 | 1回 |
| 所要時間 | 約240秒 | 約110秒 |
| コンテキストの消費 | 約2倍 | 基準 |
つまり直しの往復は、そのぶんだけ枠を削っていきます。
もちろん、うまくいくこともあります。
ただ、それは偶然うまくいっただけで、次に同じ指示を出したときに同じところへ届く保証はありません。
曖昧なまま投げた時点で、何が返ってくるかは運任せになります。
ズレ①：読み方が二通りある言葉
まず、こちらが書いた一文が二通りに読める場合です。
「〜ごと・〜ごと」で起きたこと
集計機能を足す場面で、こう頼みました。
カテゴリごと・月ごとの集計を出せるようにして
返ってきたのは、カテゴリ別の集計と月別の集計という独立した2本でした。
二度試して、二度ともこの読み方をしています。
こちらが欲しかったのは、カテゴリと月を掛け合わせた1つの集計です。
日本語として、この一文はどちらにも読めます。
並んだ2つの軸と読むか、掛け合わせた1つの表と読むかは、この文からは決まりません。
決まらないものを渡せば、どちらに転ぶかは受け取った側の解釈次第になります。
掛け合わせを言葉にする
書き直すときは、4つの観点（何を・どこに・どう・制約は）をまとめて1つの指示文にしました。
そのうち「何を」にあたる部分は、こう書いています。
カテゴリ × 年月の合計
年月の昇順
「ごと」を掛け算の記号に置き換えて、並び順まで書き添えた形です。
返ってきたのは意図どおりの掛け合わせの集計で、二度目も変わりませんでした。
ズレ②：プロジェクトごとの書き方の流儀
次は、書き方の流儀を指定しなかった場合です。
一度目と二度目で書き方が変わった
「運任せ」の節で触れた、一度目と二度目で書き方が変わった話は、ズレ①とまったく同じ1文の依頼から起きています。
1つの曖昧な依頼が、読み違いと書き方のぶれを同時に連れてきました。
プロジェクトごとの書き方の流儀とは、変数名の付け方やコードの書式のような、同じ機能でも人によって分かれる作法のことです。
対象にしたコードでは、これがそろっていませんでした。
実際にあった2つの関数はこうです。
def load_records(path: Path) -> list[Record]:
def calcTotal(recordList):
load_records は単語を下線でつなぎ、引数と戻り値の型も書き添えています。
calcTotal は2語目から頭文字を大文字にする書き方（キャメルケースと呼ばれます）で、型ヒントもありません。
そこへ流儀を指定せずに機能を足させると、一度目は古いほう（キャメルケース、型ヒントなし）に寄せました。
二度目は新しいほう（下線区切り、型ヒントつき）です。
どちらが正解かは、コードを読んだだけでは決まりません。
多い側に合わせることもあれば、新しい側に合わせることもあります。
どちらに寄せるかを、こちらが決めていないだけです。
基準にするファイルを名指しする
先ほどの4つの観点のうち「どこに」にあたる部分では、そろえる先を1つ名指ししました。
「loader.py の書き方にそろえる」と書いただけです。
「既存のコードに合わせて」では、どの既存に合わせるかがまた決まりません。
ファイル名まで書くと、見比べる相手が1つに固定されます。
この指示では、二度とも同じ書き方で返ってきました。
ズレ①と②で書き直した指示は、どちらも4つの観点をまとめた1つの指示文の一部です。
抜き出した一文だけを単独で試したわけではありません。
ズレ③：選択肢の設計を相手に委ねる
場面を変えても同じことが起きます。
一覧に並び替えを足すときは、こう頼みました。
一覧に並び替え機能をつけて
返ってきた選択肢は「新しい順 / 古い順 / 名前順」でした。
二度試しても、この3択のままでした。
一見よくできていますが、名前の降順が選べません。
並び替えには軸（名前か日時か）と向き（昇順か降順か、つまり小さい順か大きい順か）の2つがあります。
この指示では、3つの選択肢の中に軸と向きがセットで固定されていたためです。
選択肢をどう設計するかは、言われなければ作り手の裁量になります。
もっともらしい選択肢は用意されますが、それがこちらの想定と同じとは限りません。
そこで、軸と向きを分けたいことをそのまま書きました。
名前と追加日時のどちらでも並べ替えられる。昇順と降順も切り替えられる
今度は、2つの軸と昇降順が別々に選べる形で返ってきました。
これも二度とも同じです。
追加指示が届かない範囲
あとから直せばいい、という考え方もあります。
実際、書き方がそろっていないことに気づいた時点で「この書き方にそろえて」と追加で頼みました。
ところが、そろえられたのは新しく足した分だけでした。
既に書かれていた分は、古い書き方のまま残っています。
そこを直すために、もう1往復かかりました。
先に書いておけば1往復で済んだ内容が、あとから頼むと2往復になったわけです。
あとから直せばいい、とは限りません。
あとから頼むときは、直す範囲まで書き添えてください。
「新しく足す分」と受け取られると、既にある分が古いまま残ります。
指示を出す前に見る4つの観点
書籍『Claude Codeで作って学ぶ AI駆動アプリ開発入門』の5.1では、指示を出す前に見る観点を「何を・どこに・どう・制約は」の4つに整理しています。
ここまでの3つのズレが、それぞれどの観点にあたるかを並べます。
| 観点 | この記事のどのズレか | 書く側でやること |
|---|---|---|
| 何を | ズレ① 読み方が二通りある言葉 | 「カテゴリ × 年月の合計」のように、掛け合わせや並び順まで書く |
| どこに | ズレ② 書き方の流儀 | そろえる先を loader.py のようにファイル名で名指しする |
| どう | ズレ③ 選択肢の設計 | 使う側から見た振る舞いを、軸と向きに分けて渡す |
| 制約は | 今回のズレには出てこない | 外してほしくない条件を書く |
今回のズレには出てこないが、4観点で書いた指示には「新しいライブラリを使わない」「既存の関数の形を変えない」という制約も実際に加えている。
この4つをまとめて書いた指示では、直しの往復が一度も要りませんでした。
一言の依頼に比べれば、書く手間はかかります。
ただ、返ってくるものがぶれない分、直しに取られる時間はむしろ短くなりました。
まとめ
曖昧な指示でも、動くものは返ってきます。
ただ、それを選んだのはこちらではありません。
二度回して結果が割れるのを見た身としては、送信ボタンを押す前に4つの観点をなぞるほうが早いと思っています。
4つの観点は、実際に手を動かして頼んでみると早く身につきます。
書籍『Claude Codeで作って学ぶ AI駆動アプリ開発入門』では、タスク管理アプリの制作を通してこの感覚を養います。
手元で回して判断するというやり方は、別の記事でも使っています。
Xをフォローいただけると嬉しいです！
AI駆動開発（特に Claude Code）のノウハウや Tips をよく発信しています！