AIエージェントへの指示、実際どうしてる？

概要

お疲れ様です。だいせんせーです。
AIエージェントを業務に取り入れるのはもはや当たり前になりつつあるけれど、
「どう頼めば成果が出るのか？」「どのくらい丸投げしてOKなのか？」
と言われると、意外と現場には暗黙知が多いです。

この記事では、架空の実務シナリオ（住所表示の不具合調査）を題材に、AIエージェントとのやりとりをどう設計すべきか、どこに注意すべきかを、現場のエンジニア目線で深掘りしてまとめています。
AI活用に興味ある人にも、すでに触っている方にも刺さる内容にしてみました！

仮想事例を用いた不具合調査プロセス

「ユーザー詳細画面での住所表示が欠ける問題を修正したい」

今回扱うのは、ユーザー詳細画面の表示不具合を調査・修正したいという実務タスク。

• ※今回のケースは一部事実を改変して執筆しています。

とある Web システムの「ユーザー詳細画面」で、表示される住所に不具合が発生していました。
住所はデータベースに “都道府県〜号” まで全て格納されているにもかかわらず、画面側では “区” までしか出ないというものです。

想定される原因（まだ不明）

• データベースにはフルの住所情報が入っている
• ただし画面側では一部しか表示されていない
• 中間処理がどこかで住所を分割している可能性あり
• どのレイヤーで欠けているか、まだ誰も確信がない

ここから先は推測の域を出ず、
調査の方向性をどう設計するかが重要なフェーズです。

技術スタック(例)

• 使用AIエージェント：Claude Code
• バックエンド：Java
• フロントエンド：VB.NET
• DB：MySQL

この3層構造のどこかに原因が潜んでいるという状況です。

AIエージェントが真価を発揮するのは「曖昧なタスク」

原因がまだ判明していないタスクは、人間がやると探索コストが大きく、手をつけづらい。ここで AI が得意なのは、
「何が起きているか」を整理するための仮説生成 や
可能性のある箇所の洗い出し といった、調査プロセスの型作り。
AI に以下を依頼するところから始めます。

• フロントエンド → バックエンド → DB のどこで整形されていそうか候補を出す
• 住所に関わる処理の可能性を洗い出す
• 正常に動いている会社情報画面の処理との比較

こうした調査フェーズこそ、AI の真価が発揮される場面です。

AIに丸投げするのではなく、

• どんな背景？
• どこまでわかってる？
• どんな例が既に動いてる？

みたいな 「手がかり」 をセットで渡すと、AIの解像度が一気に上がります。

指示を「md でまとめる」ことの本当の価値

AIエージェントに依頼を送るとき、チャットに直接書き込むのではなく、
あらかじめmd（Markdown）で整理された文書を渡す方法には大きなメリットがあります。これは、多くの現場で実際に効くと感じられているポイントです。

情報の粒度を揃えられる

タスクが曖昧なほど、指示内容は抜け漏れが発生しがち。
md形式なら、

• 箇条書き
• 見出し
• テーブル
• 前提／目的／条件の整理

といった構造化がしやすく、必要な情報を均一な粒度で並べられる。
その結果、AIはタスク全体の意図を理解しやすくなります。

AIが“情報のまとまり”として読み取れる

チャット形式だと、

• 文脈が流れやすい
• 会話が積み上がって前提が薄まる
• 途中で前提を見失う

といった現象が起きがちです。
結果として、「部分的な誤読」や「文脈の取り違え」が減り、
出てくる提案の精度が安定します。
一方、mdは「1枚の資料」としてまとまるため、AIが全体像を一度に読み取れるという大きな強みがあります。
といった構造化がしやすく、必要な情報を均一な粒度で並べられる。
その結果、AIはタスク全体の意図を理解しやすくなります。

後から振り返って使い回せる

md はそのまま成果物として残せるため、

• 同じ種類のタスクをやるときのテンプレになる
• チーム内共有もしやすい
• 経緯が文書化されるため、判断の根拠が曖昧にならない

といった副次的メリットも大きいです。
AIに送るためだけのドキュメントではなく、
「ナレッジ資産として蓄積できる」ツールとしても機能します。

画像添付が効く理由

住所の欠損はテキストの問題ですが、
それでも 画面のキャプチャは必須級の情報 です。

これをセットで渡すことで、

• 現在の UI
• 正しく動いている別画面（会社情報）
• 理想の表示イメージ

「どういうフォーム構成？」「何が欠けてる？」
→ AI が一瞬で理解できる。

UI を扱うタスクでは特に効果が大きいですが、
それ以外のタスクでも、スクリーンショットは「意図を圧縮して伝える」最強のツールです。

起きたつまずき

AI の初回提案は、フロントエンド側の住所表示ロジックを修正する案。
結果はこれが部分的には正しくても、改善は限定的でした。なぜなら原因は別にあったからです。
調査を進めていくと、バックエンド側で住所を「区」で区切る処理 が存在することが判明。
どうやら別機能の名残で、「区の後ろを一旦削る」仕様が残っていたらしいです。
フロントエンドを変えても改善しなかったのはそのためでした。

実務で応用できる「AI運用の型」

今回のケースを通して実務で使えるヒントをさらに広げると、こんな型が見えてきます。
1. 依頼の粒度を分ける

• 調査（原因探索）
• 設計案
• 実装案
• コード生成

これらを一度に投げない。
目的を分離すると、AI が誤解しにくく精度が上がる。

2. 正常系の例は「最良の教材」

今回でいう「会社情報画面」。
AIの理解は例があるだけで何倍にも加速する。

3. 出力形式を固定する

• 箇条書き
• 実装手順
• diff 形式
• 修正箇所リスト

形式を固定するだけでレビューが圧倒的に楽になる。

4. スクショは積極的に使う

思っている以上に「画面情報」は AI の理解を補強する。

5. 振り返りを仕組みにする

• 指示
• AI回答
• 実装
• 結果
• 反省

これが残っていると次回の精度が跳ね上がる。

仮想ケースをもとにした「実際に使えるプロンプト例」

今回の記事では、住所表示が途中で欠ける「仮想ケース」を題材に、Claude Codeに
どんな指示を送ると結果が安定しやすいかを具体例としてまとめています。
調査フェーズ／設計フェーズ／実装フェーズの3段階で、実際の業務で再利用できるプロンプトを紹介します。

◆ プロンプト例：調査タスクとして依頼する場合

# タスク概要
ユーザー詳細画面で住所が「東京都〇〇区」までしか表示されていません。
データベースには丁目・番地・号まで正しく格納されていることを確認しています。

# 調査してほしいこと
- 住所を加工・整形している処理が存在するか
- フロントエンド / バックエンド / DB のどこで値が欠けている可能性が高いか
- 正常に住所が表示されている「会社情報画面」との処理の違い

# 前提情報
- バックエンド：Java
- フロントエンド：VB.NET
- DB：MySQL

# 出力形式
- 想定される原因の候補
- 調査すべきファイルや処理名
- その理由

このプロンプトで大事なポイント

• 目的（調査であって修正ではない）が明確
• 前提情報をセットで渡しているので AI がレイヤーを跨いで探しやすい
• 比較対象（会社情報画面）**を明示しているので精度が上がる
• 出力形式を指定することで回答の質が安定する

◆ プロンプト例：実装案を依頼する場合

# タスク
ユーザー詳細画面で住所が途中までしか表示されない問題を修正したいです。

# やってほしいこと
- 原因特定後の修正方針を提示してください
- フロントエンド修正案とバックエンド修正案を分けて説明してください
- 修正の影響範囲があれば箇条書きでまとめてください

# 参考情報
- フロントエンド：VB.NET
- バックエンド：Java
- DB：MySQL
- 正常に表示されている画面：「会社情報画面」

# 出力形式
- 修正方針（フロントエンド/ バックエンド）
- 理由
- 影響範囲

このプロンプトで大事なポイント

• 「修正方針を提示して」と依頼するだけに留め、実装コード生成を求めていない

→ タスクを細かく分割することで AI の混乱を防げる

• フロントエンドとバックエンドを分けて出力させることでレイヤーの誤認を防止
• 影響範囲の提示を求めることで後のレビューや設計が楽になる

プロンプト例：実装コードの生成まで依頼する場合

# 依頼内容
住所が途中で欠けて表示される問題について、原因がバックエンドの住所文字列整形処理にあると判明しました。

# やってほしいこと
- 該当箇所の修正コードを提示してください
- 変更前と変更後の差分がわかる形で出力してください
- 必要な場合は、他に修正が必要な箇所の候補も示してください

# 注意点
- 既存仕様を壊さないように、現在の処理フローを尊重してください
- 外部の機能追加は行わないでください

# 出力形式
- diff 形式のコード
- 追加で確認すべきポイント

このプロンプトで大事なポイント

• 「原因がすでに特定されていること」をはっきり伝えている

→ 調査と実装を混ぜない

• 差分形式での出力を求めることで、無駄なコード生成を抑制
• 注意点を列挙して、AI の暴走（仕様変更や余計な提案）を抑える

まとめ

AIエージェントとの共同作業は、
「どんな情報を、どう構造化して渡せるか」が勝負。
今回の住所表示の例でも、

• 背景を丁寧に渡す
• 例を提示する
• スクリーンショットを添える
• 調査フェーズと実装フェーズを分ける
• 出力形式をはっきりさせる

といった小さな工夫が、
AI の精度を押し上げ、無駄な回り道を減らしてくれます。
AIは“魔法の箱”ではなく、
情報を整理し、やりとりをデザインすることで性能が最大化する相棒。
この記事が、AIエージェントをもっと気持ちよく使いこなすためのヒントになればうれしいです！