こんにちは、DIVX エンジニアのyasunaです。

ここ半年、OpenAI Codex などのAIコーディングエージェントを日常的に業務で使う中で、自分のプロンプトの癖が少しずつ見えてきました。うまくいく時もあるし、何度やっても同じところで詰まってしまうこともあります。

その違いはどこにあるのだろうと思いこの記事を書こうと思いました。

結論、自分がどの粒度でAIへ問題を渡しているか、どこまで前提を言語化できているか、その差がかなり大きいと感じています。

最近読んだ論文 The Observability Gap: Why Output-Level Human Feedback Fails for LLM Coding Agents は、その感覚をかなりはっきり言語化してくれました。

この記事では、自分のプロンプトの振り返りと、論文を読んでこれから試したいことを書きます。

AIとの対話を見返してみると、うまくいった依頼にはだいたい次のどれかが入っていました。

• 比較軸がある
• 制約が明確
• 出力の型が決まっている

例えば、単に「この不具合を直して」と投げた時よりも、「フォーム送信後に 500 が返るので、まずはリクエストとAPIレスポンスを確認して、原因を絞って」と制約を置いた時の方が、返ってくる内容は安定しました。

同じように、「修正して」よりも「この関数だけ見て、undefined が入る経路を特定してから最小で直して」と範囲を絞った方が、意図に近い修正が返ってきます。「調べて」よりも「README形式で再現手順、原因、対処の3項目に整理して」の方が、そのまま使える成果物になります。

逆に、うまくいかない時の自分のプロンプトはかなり雑でした。

• 「動かない」
• 「テストが落ちた」
• 「これ変」

このあたりは会話のテンポは速いのですが、後から見ると何を判断して、なぜその修正を選んだのかが残りません。個人のその場しのぎとしては機能しても、チームで再利用できるナレッジにはならない。

最近は、AIへの依頼のうまさというより、自分の考えていることをどれだけ観測可能な形で渡せるかの問題だと思うようになりました。

今回読んだ論文が扱っているのは、LLMマルチエージェントが人間のフィードバックを受けながらタスクを進める時、なぜ出力ベースのフィードバックだけでは収束しにくいのか、という問題です。

論文が提示する説明はシンプルです。バグは内部のコードロジックや実行状態で発生しているのに、人間が見ているのは外部の出力だけです。このあいだに「観測可能性ギャップ」がある。

しかも、出力と原因は一対一ではありません。同じ「表示がおかしい」という症状でも、原因候補はいくつもあります。

つまり「動かない」「崩れている」「期待通りじゃない」といった症状ベースのフィードバックだけでは、根本原因にたどり着けない。エージェントは修正を試みても、失敗モードを振動するだけになる。かなり納得感がありました。

この論文を読んで、自分がAIに渡していた情報もかなり「出力層」に偏っていたと分かりました。

例えば、

• 「エラーが出る」
• 「思ったUIと違う」
• 「テストが通らない」

このあたりは全部、症状の報告です。

もちろん初手としては必要です。ただ、それだけでは人間のエンジニアに相談する時と同じで、情報が足りません。本当に必要なのは、その症状に一段近い層の情報です。

今の自分なりには、AIに渡す情報を次の4層で考えると整理しやすいと感じています。

出力層しか渡せない時、AIは広く推測するしかありません。状態層やロジック層まで言えると、修正候補はかなり絞られます。設計層まで言えると、場当たり的な修正より再発防止に近づきます。

ここで重要なのは、上の層に行くほど、指示を出す人間側にも理解が求められることです。

自分はまだ「設計として何がまずいか」を言い切れない場面に遭遇します。ただ、それも含めて、どの層まで自分が見えているかを意識するだけで、AIとの会話の質は変わると感じています。

論文を読んで終わりにせず、実際の業務で次の4つを試したいです。

「動かない」と言いたくなった時に、そのまま送らず次のどれかを一つ足します。

• 直前にやった操作
• 再現手順
• 期待していた挙動
• 実際の入力やレスポンス

最低でも状態層に一歩寄せるだけで、AIの推測コストをかなり減らせるはずです。

go や はい は楽ですが、後から見返した時に何を承認したかが消えます。

なので今後は、

• その方針で README まで更新して
• UIはそのままで、文言だけ差し替えて
• デバッグ優先で原因切り分けを続けて

のように、対象と意図が残る承認に寄せたいです。

AIとの会話で地味に効くのが、最初に成果物の型を決めることです。

• README形式で
• レビューとして
• 比較表で

と最初に言うだけで、途中の手戻りが減ります。これは文章でもコードでも同じでした。

良い会話をそのまま共有しても、他の人が使い回せるとは限りません。

残すべきなのはログ全文ではなく、

• 何を依頼したか
• 何が効いたか
• 何が足りなかったか
• 次回どう書くか

の4点だと思っています。

将来的には、AIとのやり取りを個人のチャット履歴として済ませるのではなく、チームの依頼テンプレートやレビュー観点として蓄積できる形にしたいです。

AIを使いこなすと言うと、うまい言い回しやプロンプトを知っていることのように聞こえる時があります。でも実際には逆で、必要なのはプロンプトのセンスというより、問題の構造を観察して言語化する力だと思います。

どこが壊れているのか。
何を期待していたのか。
どの前提が崩れているのか。
どこまでが症状で、どこからが原因なのか。

この整理ができるほど、AIは使いやすくなる。逆にここが曖昧だと、どれだけ高性能なモデルでも会話は空回りしやすいと思います。

今回この記事を通して、自分の中で曖昧だったAIへの指示だしについて整理することができました。

AIに「うまく頼む」ことよりも、「どの層の情報を渡しているか」を意識することの方が大事です。出力だけ見て直してもらおうとする限り、同じ失敗を繰り返してしまいます。

とはいえ、自分もロジック層や設計層を十分に言語化できるわけではありません。その不足部分も含めてAIとの対話で可視化し、その対話自体が学習の入口になる気がしています。

AIを使うことと、エンジニアとして成長することを別の話にせずにこの問いに取り組んでいきたいと思います。

• The Observability Gap: Why Output-Level Human Feedback Fails for LLM Coding Agents