8月27日、Towards Data Scienceが「How to Work with AI Coding Agents」と題した記事を公開した。AIコーディングエージェントを実務で最大限に活かすための考え方と具体的な使い方について詳しく紹介されており、「思ったような結果が出ない」と感じている開発者にとって示唆の多い内容だ。
コーディングエージェントを使っても「思ったような結果が出ない」という声は多い。多くの場合、問題はモデルの性能ではなく、使い方にある。記事では、エージェントに「大量のコードを書かせること」より「正しい問題を正しく渡すこと」の方がはるかに重要だと主張している。
コーディングエージェントとは何が違うのか
AI支援プログラミングには段階がある。
- オートコンプリート: 次の1行を予測する
- AIアシスタント: 「このファイルをパースする関数を書いて」といった単発の依頼に応える
- コーディングエージェント: リポジトリを調査し、ファイルを作成・修正し、テストを実行し、エラーを読んで修正を繰り返す
決定的な違いは「ループ」だ。エージェントはテキストを生成するだけでなく、環境と相互作用できる。
2025年時点では、Claude Code（Anthropic）、Cursor、Devin、GitHub Copilot Workspaceなど、エージェント型のコーディング支援ツールが急速に普及している。これらはいずれも「複数ステップにわたるタスクを自律的にこなす」点で従来のコード補完ツールと一線を画すが、だからこそ使い方の巧拙が結果に直結する。
「指示が少なすぎる」が最大の失敗原因
典型的な失敗パターンがある。
Build authentication for my application.
このような曖昧な指示を与えると、エージェントは熱心に動き始める。新しいクラスを作り、依存関係を追加し、データベースまで書き換えることもある。結果として大量のコードが生成されるが、欲しかったコードではない。
改善した指示はこうなる：
Add email/password authentication.
First inspect the existing user and authentication code.
Do not modify the database yet.
Follow the existing error-handling pattern.
Add tests for:
valid login
invalid password
unknown user
Before making changes, explain your plan.
追加しているのは「言葉の量」ではなく制約だ。この違いが結果を大きく変える。
プロンプトよりもコンテキストが重要
プロンプトだけに気を取られがちだが、コンテキストがなければプロンプトの効果は限られる。リポジトリ自体がアーキテクチャ、命名規則、依存関係、テスト、設定、ドキュメントといった大量のコンテキストを持っている。
Fix the bug in the parser.
ではなく：
Fix the bug in src/parser.py.
Before changing anything, read:
README.md
src/parser.py
tests/test_parser.py
Follow the existing error-handling pattern.
Run the parser tests after making the change.
記事では「長いプロンプトが必ずしも良いわけではない。良いプロンプトとは、エージェントが何を見ればいいかを示すものだ」と述べている。
また、すぐにコードを変更させるのではなく、以下のループを意識することを推奨している：
Ask → Inspect → Plan → Implement → Test → Review
最初のステップとして、ファイルを変更せずにリポジトリを調査させる：
First inspect the repository.
Do not modify any files.
Identify:
Where this functionality currently lives.
Which files are likely to change.
Existing tests related to it.
Any architectural constraints.
Then propose an implementation plan.
エージェントが15個のファイルを書き換える前に、論理のズレを見つけられる。
タスクは小さく分割する
「アプリケーション全体をリライトして」のような巨大なタスクを渡すと、大量のコードが生成されてレビューが困難になる。代わりに小さく分割する：
Task 1: Add the parser class.
Task 2: Add unit tests.
Task 3: Integrate it with the existing pipeline.
Task 4: Refactor duplicated code.
問題が起きたときに、どこで起きたかが特定しやすくなる。これはAI利用に限らず、ソフトウェアエンジニアリング全般で有効な原則だ。
また、テストの重要性も増す。エージェントはすべてのテストをパスさせながら、設計として誤った実装を作ることができる。エージェントが生成したコードのレビューでは以下を確認する必要がある：
- 設計として正しいか
- 既存のアーキテクチャに合っているか
- 不要な変更が加えられていないか
- セキュリティ上の問題はないか
- 異常な入力に対してどう動くか
記事の言葉を借りれば、「AIはコードを書くコストを下げたが、コードを理解するコストは依然として高い」。
どんなタスクにエージェントを使うべきか
すべてのタスクにエージェントが必要なわけではない。記事では以下の判断基準を示している：
| タスク | 適切なAI支援の種類 |
|---|---|
| 「このエラーを説明して」 | AIアシスタント |
| 「この小さな関数を書いて」 | コーディングアシスタント |
| 「このファイルをリファクタリングして」 | コーディングアシスタント/エージェント |
| 「このバグを見つけて修正して」 | コーディングエージェント |
| 「リポジトリ全体にこの機能を追加して」 | コーディングエージェント |
| 「アプリ全体をリライトして」 | エージェント＋人間のチェックポイント |
| 「このコードをよくして」 | どちらでもない。まず問題を定義する |
探索・複数のアクション・フィードバックが絡むタスクほど、エージェントが力を発揮する。一方で、タスクの粒度が大きすぎるほど、エージェントの自律的な判断が増え、意図しない変更が紛れ込むリスクも高まる。Claude CodeやDevinのような高度なエージェントであっても、この原則は変わらない。
記事の最後は示唆に富む。「エージェント時代の優秀な開発者は、最もコードを書く人ではない。どの問題を機械に渡すべきか、どう渡すか、そしていつ答えを信頼しないかを知っている人だ」という結論は、コーディングエージェントとの付き合い方を端的に表している。
詳細はHow to Work with AI Coding Agentsを参照していただきたい。
