AI コーディングエージェントからより良い結果を得るための 10 のルール

AI コーディングエージェントはもはや単なる自動補完ツールではありません。リポジトリの読み込み、複数ファイルへの編集、コマンドの実行、プルリクエストの作成、そして多段階の開発タスクの処理までこなすことができます。Claude Code、Codex 、Cursor 、Copilot Agent 、Gemini CLI といったツールが、開発者のソフトウェア構築のあり方を変えつつあります。しかし、ツールが進化すれば自動的にコード品質も向上するわけではありません。

HackerRank の 2025 年開発者スキルレポートによると、開発者の 97% が少なくとも 1 つの AI アシスタントを利用しており、コードの約 3 割がすでに AI によって生成されています。また、AI の導入は納期プレッシャーを高める一方で、優れたエンジニアリング判断の必要性をなくすものではないと指摘しています。

AI を活用して成果を出せる開発者と、イライラするだけの開発者の差は、多くの場合ワークフローにあります。明確な目標、プロジェクトの文脈、検証ルール、そして安全に反復できる環境が整っていれば、AI コーディングエージェントは最高のパフォーマンスを発揮します。ここでは、より良い結果を得るための10 の実践的なルールをご紹介します。

# 1. 曖昧なプロンプトではなく、仕様から始める

悪いプロンプトの例:

Build the dashboard.

改善されたプロンプトの例:

Build a customer churn dashboard.

Goal:
Show churn rate, active customers, monthly revenue, and top churn risk factors.

Scope:
- Add a dashboard page at /dashboard.
- Use the existing API client.
- Reuse the current chart component.
- Do not change the database schema.

Acceptance criteria:
- Page loads without console errors.
- Metrics match the /analytics/churn endpoint.
- Add tests for the data transformation function.
- Run lint and tests before final response.

コーディングエージェントは実行には優れていますが、明確な目標が必要です。優れた仕様書には、ゴール、スコープ、制約条件、変更が予想されるファイル、受入基準、テストコマンドなどが含まれるべきです。これはプロの開発者がすでに実践しているワークフローと一致しています。つまりタスクは「コードを書くこと」ではなく、「明確な完了定義を満たす変更を行うこと」なのです。

最近発表された論文 コーディングエージェントのブートストラップ でも、研究の観点から同様の指摘がなされています。エージェントにとっては、仕様書が記録としての安定したアーティファクトとなり、実装は再生成や改訂の対象となる可能性があるのです。

# 2. AGENTS.md、CLAUDE.md、または Copilot 指示ファイルの活用

**

同じプロジェクトルールを毎回プロンプトで繰り返すのはやめましょう。永続的な指示は、リポジトリレベルのエージェント用ファイルに記述してください。

</article>

オープンソースの「AGENTS.md」形式は、エージェント向けの README として定義されています。コーディングエージェントに対して、セットアップコマンドやテストコマンド、コーディング規約、リポジトリ固有の指示などを一貫して提供するための予測可能な場所です。現在、この形式は 6 万プロジェクト以上のオープンソースプロジェクトで採用されています。

例えば以下の通りです。

# AGENTS.md

## Setup
- Install dependencies with `pnpm install`.
- Start the app with `pnpm dev`.
- Run tests with `pnpm test`.

## Code style
- Use TypeScript strict mode.
- Prefer functional components.
- Do not add new dependencies without approval.

## Before finishing
- Run lint.
- Run relevant tests.
- Summarize changed files and why they changed.

Codex は作業を開始する前に AGENTS.md を読み込み、グローバル、プロジェクト、ディレクトリ固有のファイルからなる多層的なガイダンスをサポートしています。また、GitHub Copilot も .github/copilot-instructions.md 内にリポジトリ固有のカスタム指示を設定でき、エージェントに対してビルドやテスト、検証の方法、プロジェクトの規約への準拠方法を指示することが可能です。

3. エージェントへの指示は短く、有用な内容に留める

エージェント用の指示ファイルに、社内のエンジニアリングハンドブック丸ごとを貼り付けるのは避けてください。

Anthropic のスキル作成ガイドライン では、優れたスキルは簡潔で構造化されており、実際の利用ケースでテスト済みであるべきだと説いています。また、一度指示を読み込むと、その後のすべてのトークンがタスクの文脈全体の中で競合し合うことになる点にも注意を促しています。

最近発表された `AGENTS.md` および `CLAUDE.md` ファイルに関する論文 では、よく見られる「設定の臭い」として、リントレーク（不要なコードが漏れる）、コンテキストの肥大化、スキルの漏洩、矛盾する指示などが指摘されています。調査対象とした 100 の人気リポジトリでは、62% でリンクレークが発生し、42% でコンテキストの肥大化が見られました。

良い指示ファイルには、以下のような要素が含まれます：

• インストール、ビルド、テスト、リンティングの方法
• プロジェクト固有のアーキテクチャに関する注記
• 命名規則とコーディングスタイルのルール
• セキュリティ上の制約
• 手をつけないでほしい箇所
• 完了報告の方法

一方、避けるべき指示ファイルには、以下のような要素が含まれます：

• モデルがすでに知っている一般的なコーディングアドバイス
• 一般的なフレームワークに関する冗長な説明
• 矛盾するルール
• 古くなったコマンド
• 「常に」「決して」といった指示が多すぎるもの

4. 編集前にエージェントに調査させるよう依頼する

複雑なタスクを行う際は、リポジトリを変更する前にまず理解させるよう指示を出してください。

例：

Before editing, inspect the relevant files and summarize:
1. which files control authentication,
2. where the bug likely lives,
3. what tests already cover this area,
4. the smallest safe change.
Do not modify files until after this summary.

これにより、エージェントが正しくない場所に一見もっともらしい修正を施してしまうという一般的な失敗を防げます。システムを変更する前に、まずそのシステムの場所を特定させるように指示してください。

# 5. 複雑なタスクには計画を立てるが、小さな編集では過剰に計画しない

大規模な変更には計画が役立ちますが、小さな変更に対しては過度な計画がループを遅らせてしまいます。

GitHub Copilot CLI のベストプラクティスドキュメント では、コードを書き始める前に構造化された実装計画が有用なタスクに対しては「プランモード」の使用を明確に推奨しています。

以下のようなケースでは計画を立てましょう：

• 移行作業
• 複数ファイルにわたるリファクタリング
• 認証関連の変更
• データベースの変更
• パフォーマンス最適化
• 本番環境のバグ修正
• セキュリティや決済に関わるあらゆる変更

一方、以下のようなケースでは重い計画は不要です：

• タイポの修正
• 小さなテストの追加
• シンプルな CSS の変更
• 単一関数のリファクタリング

# 6. テストを契約として活用する

**

AI が生成したコードは、完成する前には正しく見えることが多いものです。

HackerRank** は、AI 生成のコードにも信頼性、セキュリティ、統合のための作業が必要であるため、デバッグが AI エージにおける中心的なスキルになりつつあると論じています。そのガイダンスでは、失敗するテストや誤解を招くログ、統合時のエッジケースを含む実践的な複数ファイルのデバッグシナリオを推奨しています。

エージェントに対する契約としてテストを活用しましょう：

Write failing tests first for this bug.
Confirm they fail.
Then implement the smallest fix.
Do not modify the tests after implementation unless the test itself is wrong.
Run the relevant test suite before finishing.

このパターンは、特にエージェントにおいて強力な効果を発揮します。なぜなら、フィードバックループを提供できるからです。テストがない場合、エージェントは「それらしく見えるコード」を最適化してしまいますが、テストがあることで「実際に動作するコード」の生成に集中できるようになります。

# 7. 望ましいスタイルの例示

**

抽象的な taste（好み）よりも、具体的な例示の方がエージェントには効果的です。

以下のように伝えるのではなく：

Make it clean and production-ready.

こう伝えてください：

Follow the style of `src/features/billing/CreateInvoice.tsx`.
Use the same error-handling pattern as `src/lib/apiClient.ts`.
Use the existing `Result<T>` type instead of throwing raw errors.

GitHub の Copilot ベストプラクティスガイド** では、複雑なタスクを分解すること、具体的な指示を出すこと、入力と出力の例を示すこと、そしてプロンプト作成時に良質なコーディングプラクティスを遵循することが推奨されています。例示を行うことで曖昧さが減り、既存のコードベースと矛盾する独自のスタイルをエージェントが勝手に作り出すのを防ぐことができます。

# 8. 依存関係と権限の制御

**

エージェントは、パッケージのインストールや設定の変更、権限の拡大といった方法で問題を解決しようとする傾向があります。ローカル環境では機能しても、長期的なメンテナンスリスクを生む可能性があります。

以下のようなルールを追加してください：

## Dependency policy
- Do not add production dependencies without approval.
- Prefer existing utilities before adding new packages.
- If a new dependency is necessary, explain why and list alternatives.

これは特に重要です。現代のコーディングエージェントはコマンドを実行したり、開発ツールと対話したりできるからです。お使いのツールがフックや権限制御をサポートしている場合は、それらを活用しましょう。Claude Code のフック** を使えば、特定のライフサイクルポイントで決定論的なコマンドを実行できます。モデルが記憶を頼りにするのではなく、確実にチェックが行われる必要がある場合に非常に役立ちます。

# 9. AI の変更点レビュー

**

AI が生成したコードのレビューを行う際、「見た目は良いか？」と問うべきではありません。

レビューでは、以下の点を問いかけてください。

• 依頼された課題は解決できたか？
• 無関係な挙動に変更を加えていないか？
• 不要な抽象化を導入していないか？
• セキュリティが弱体化していないか？
• エラーを隠すだけで、根本的な修正を行っていないか？
• テストは更新されたか？
• プロジェクトの規約に従っているか？
• Diff（差分）をさらに小さくできる余地はないか？

経験豊富な開発者は、AI コーディングエージェントを生産性ツールとして高く評価しますが、品質属性へのこだわりから設計と実装の最終的なコントロールは自ら保持します。この考え方が最も適切です。エージェントには草案作成、探索、リファクタリング、テストの実行を任せ、アーキテクチャ、正しさ、保守性の責任は開発者が負うのです。

# 10. エージェントへの指示を反復して改善する

最初の AGENTS.md が完璧であるはずはありません。

エージェントがミスを犯した際、コードだけを修正するのではなく、そのミスを許容してしまった「指示」自体を見直す必要があります。

具体例：

エージェントのミス：

生成されたファイルを直接書き換えてしまった。

指示の更新：

## Generated files
- Do not edit files in `src/generated/`.
- Update the schema or generator source instead.
- If unsure, ask before changing generated files.

エージェントのミス：

毎回、非常に時間のかかるテストスイート全体を実行してしまった。

指示の更新：

## Test strategy
- For frontend component changes, run the affected component tests first.
- Run the full test suite only before final completion or when shared utilities change.

# まとめ

明確な仕様書を書き、効果的なフィードバックループを設計し、コードを慎重にレビューできる開発者こそが、AI コーディングエージェントから恩恵を受けることができます。目指すべきは、プロダクションシステムを「雰囲気」だけで作り上げるような安易なコーディングではありません。重要なのは、制御されたエンジニアリングワークフローの中で、エージェントをより迅速な実装パートナーとして機能させることです。

最高の結果を出すためには、エージェントに以下の要素を与えることが不可欠です。

• 明確なタスク
• 小さく正確なコンテキスト
• リポジトリ用の指示ファイル
• 既存のコードスタイルの例

テストは契約として扱う。

権限の境界を明確にする。

最終的な責任を負う人間がレビューを行うこと。

つまり、エージェントからの出力を改善するには、まずモデルそのものを良くするのではなく、エンジニアリングの規律を高めることが第一歩です。

カンワル・メヒーン氏は機械学習エンジニアであり技術ライターです。データサイエンスと医療における AI の融合に深い情熱を持っています。また、「ChatGPT で生産性を最大化する」という電子書籍の共著者でもあります。2022 年の APAC 地域向け Google ジェネレーション・スカラーとして、多様性と学術的卓越性の推進に尽力しています。さらに、Teradata の技術分野における多様性スカラーや、Mitacs Globalink リサーチ・スカラー、ハーバード大学 WeCode スカラーとしても認定されています。カンワル氏は変化の擁護者であり、STEM 分野での女性を支援する「FEMCodes」を設立しました。