先日、社内のエンジニアとの雑談で「hosoyさんはClaude Codeを使うときにどんなプロンプト書いてますか？DDLとか渡してますか？」と聞かれました。AIエージェントを活用するための記事はたくさんありますが、やはり気になるのは、「実際みんなどんな感じでAIエージェントに指示を出してタスクを進めてるんだろう？？コンテキストとかプロンプトが大事なのは分かってるけど、具体例を見せてほしい！」っていうところです。
なので、私自身はAIエージェントの基本中の基本の機能しか利用していないですが、実際のタスクに対してどのようにAIエージェントに指示を出して作業を進めているかを恥ずかしながら公開してみようと思います（実際のタスク内容そのものではなく、多少のフェイクは混ぜています）。
タスク内容
情報選択画面の選択内容に解除、発表と表示されているが、大雨警報解除、大雨注意報発表と表示したい。
前提
- 使用するAIエージェント：Claude Code
- 使用技術
- バックエンド:Java
- フロントエンド:VB.NET
- データベース:MySQL
- 私が抱える問題
- 私自身はこれまでJavaやVB.NETを使用したアプリケーションを開発したことがない
- チームを移動してきたばかりで、修正対象のファイルやコードの見当がついていない
- したがって、今回の修正対象がバックエンド or フロントエンド or データベースのいずれにあるか（もしくは複数）分かっていない
- タスクを進めるにあたってのヒント
鉄道カテゴリを選択した場合は選択内容に新幹線障害情報解除、在来線運行情報発表と表示される。この処理を真似すれば良さそう。
Claude Codeへの指示の仕方
指示内容はマークダウンファイルに記載し、Claude Codeにはファイルのパスを渡すだけのことが多いです。指示内容をマークダウンファイルに起こす理由は以下2点です。
- 指示内容を書いている途中で誤送信するとめんどくさい
- 自分がどんな指示を出し、Claude Codeがどんな反応をしたか後で振り返られるようにしておきたい
## 指示内容
- 最初に実装計画を立て、このドキュメントを更新してください。
- 情報選択画面で、「対象カテゴリ」で「気象」「警報・注意報」を選択し、「条件」で「大雨警報」の「解除」と「大雨注意報」の「発表」を選択した場合、「選択内容」に「大雨警報解除、大雨注意報発表」と表示されるように実装してください。
- 情報選択画面で「交通」「鉄道」を選択した場合の処理を参考にしてください。
- コードは手動で変更するので、修正箇所と修正コードを提示してください。
## 参考画像
- 「対象カテゴリ」で「気象」「警報・注意報」を選択したときの画面：{画像のパス}
- 「対象カテゴリ」で「交通」「鉄道」を選択したときの画面：{画像のパス}
## 参考ドキュメント
information_select_flow.md
指示内容について
-
最初に実装計画を立て〜の指示
私自身、どのファイル・どのコードを修正したらいいか全く見当がついていないので、修正箇所の調査結果と修正の方針を確認するためにこの指示を入れています。 -
情報選択画面で、「対象カテゴリ」で「気象」「警報・注意報」を〜の指示
今回のタスクの核となる指示です。 -
情報選択画面で「交通」「鉄道」を〜の指示
修正意図や修正範囲を明確にするためと、ロジックを揃えるために参考にしてほしい情報を渡しています。 -
コードは手動で変更するので〜の指示
このプロジェクトはShift-JISでエンコーディングされているのですが、Claude Codeにコードを編集させるとUTF-8にエンコーディングされてしまうため、この指示をいれています。claude.mdにShift-JISで保存するように記載していますが、どうもうまくいかないので手動でコードを修正する方針にしてます。
参考画像について
修正内容を文字だけで簡潔に伝えるのが難しいなと感じた場合はスクショを撮ってClaude Codeに渡すことにしています。今回は「対象カテゴリ」の「交通」「鉄道」と同じように「条件」を表示したいという内容なので、現状の修正対象の画面のスクショと、期待通りの挙動をとっている画面のスクショを渡しています。場合によっては、期待する画面のイメージ図を作成してClaude Codeに渡すこともあります。
参考ドキュメントについて
information_select_flow.mdは情報選択画面の開発ガイドのようなものです。以前も情報選択画面の修正を行ったことがあり、その時に作成しました。使用技術や処理フロー、前回のタスクで得た知見などがまとめられています。
今回は渡していませんが、参照されているテーブルが事前にわかっていればDDLを渡すこともあります。
Claude Codeへの指示
Claude Codeへの指示はマークダウンファイルへのパスを渡すだけです。
20251101_task.mdを読み込んでください
Claude Codeの修正内容は一部正しかったが、不十分だった
「情報選択画面.vb」(仮にこう呼びます)のコードを修正すればよいとClaude Codeが提案しました。
Claude Codeの提案通りコードを修正し、動作確認したところ以下の問題点が発覚しました。
- 「条件」のチェックボックスの選択状態を変更すると、「選択内容」には期待通り「大雨警報解除、大雨注意報発表」と表示されるようになった。（期待通りの挙動なので問題なし）
- 1を保存し、再度情報選択画面を開くと修正前と同じく「選択内容」には「解除、発表」としか表示されていない。
1と2のスクショを撮り、20251101_task.mdに動作確認結果とスクショ画像のパスを追記してClaude Codeに渡します。
期待した挙動とならない原因の調査で負のループに陥る
問題調査として情報選択画面.vbへのデバッグコードの仕込み、テーブルへのカラム追加の提案（この提案が誤っていることは明らかでした）、コード修正後のリビルド忘れを疑われるなど、Claude Codeの提案が的外れになってきたと感じました。
この状態を打破できた指示内容は選択内容を表示する処理はどのファイルに記載されているか調査してくださいでした。処理の実装箇所さえわかれば後は自力で解決しようと思っていましたが、期待した挙動にならない原因はフロントエンドではなくバックエンドにあることが判明し、無事修正できました。
ちなみに今のところGit操作は自分で行っていますが、プルリクエストの概要案はClaude Codeに作ってもらっています。
Claude Codeに反省させる
最初にClaude Codeに提示させた修正案のうち、情報選択画面.vbの修正内容は正しいものでしたが、動作確認の結果は期待した挙動とならなかった原因を調査させると、Claude Codeはフロントエンド or データベースに原因があると仮説を立てていましたが、実際にはバックエンドに原因があることが判明しました。なぜバックエンドが仮説に上がってこなかったのかClaude Codeに分析させ、反省内容をinformation_select_flow.mdに反映させます。次回情報選択画面の修正タスクに取り掛かるときは、Claude Codeがより的確に修正範囲を特定し、短いやりとりでコード修正が完了することを期待しています。
補足：なぜバックエンドのコードに触れなかったのか、Claude Codeの分析結果
- 最初にClaude Codeが提案した内容（情報選択画面.vbの修正）は不十分だが正しかったため、動作確認後に発覚した問題もVB側に原因があると思い込んだ。
- 「編集した内容を保存し、再度情報選択画面を開く」という問題を「保存処理が間違っている」と解釈した。実際にはデータベースから読み込む処理（バックエンド）に問題があったが、VBの保存処理やテーブル定義を疑ってしまった。
- 鉄道カテゴリの場合は期待通りの挙動をしているという事実の重要性を見逃した。
AIエージェントへの指示で私が気をつけていること
- 〇〇を□□に修正したい、という指示を文章のみで簡潔に指示できない場合は画像を活用する。
- 画像は現状のスクショと修正後のイメージ画像を渡すと、AIエージェントへの指示精度が上がる。
- 〇〇を△△と同じように処理してほしい、という場合はそのままAIエージェントに伝えると提案の精度が上がる。
- 指示は具体的であるほど良い。「フロントエンドで〇〇が表示されないから修正して」という指示だとフロントエンドのコードばかり調査する。「〇〇を表示する処理の実装箇所を調査し、●●と表示されるように修正してください」という指示であれば、調査範囲が明確となりAIエージェントの提案の精度があがる。
- Claude Codeが的外れな提案をし始めたら、「なぜそう考えたか」ではなく「事実ベースの調査」を依頼すると効果的かもしれない。
- マークダウンファイルに作業内容や進捗をこまめにまとめさせ、
/compactコマンドで会話を圧縮する。作業内容をマークダウンファイルに追記するだけだと、冗長な記述や内容の重複等でファイルサイズが大きくなってしまうので、適宜内容を整理させる。
最後に
正直なところ、コンテキストとかトークン使用量とかの理解はかなり浅いので、そのへんは全く気にせずにAIエージェントに指示を出しています。この記事が「自分もこんな感じで使ってる！」「もっとこうすると良いよ」といった情報交換のきっかけになれば嬉しいです。
Discussion