AIコーディングエージェント（Claude Code、Cursor、GitHub Copilot など）を開発に組み込み、品質を保ちながら速度を上げるための実践ガイドです。
目次
- 基本原則
- プロジェクトの準備
- タスクの渡し方（プロンプト設計）
- 開発ワークフロー
- テストと品質保証
- コードレビュー
- コンテキスト管理
- セキュリティとガバナンス
- チーム運用
- アンチパターン
- チェックリスト
1. 基本原則
| 原則 | 内容 |
|---|---|
| 人間が責任を持つ | AIが書いたコードでも、マージした人が責任者。理解できないコードはマージしない。 |
| 検証可能性を最優先 | AIの出力は「テスト・型・lint・実行結果」で機械的に検証できる状態にする。 |
| 小さく回す | 大きな変更を一度に任せず、レビュー可能な単位に分割する。 |
| コンテキストが品質を決める | AIの出力品質は、与えた情報（仕様・規約・既存コード）の質にほぼ比例する。 |
| AIは加速装置であって設計者ではない | アーキテクチャや重要な設計判断は人間が行い、AIには選択肢の提示や実装を任せる。 |
2. プロジェクトの準備
2.1 エージェント向け指示ファイルを用意する
リポジトリのルートにAI向けの指示ファイルを置き、毎回同じ説明をしなくて済むようにします。
CLAUDE.md（Claude Code）AGENTS.md（複数ツール共通の慣例）.cursor/rules/（Cursor）.github/copilot-instructions.md（GitHub Copilot）
書くべき内容の例：
# プロジェクト概要
- Next.js 15 + TypeScript + Prisma の社内向け在庫管理アプリ
# よく使うコマンド
- 開発サーバー: `pnpm dev`
- テスト: `pnpm test`（単体）, `pnpm test:e2e`（E2E）
- 型チェック: `pnpm typecheck`
- lint: `pnpm lint --fix`
# コーディング規約
- 関数コンポーネントのみ使用。default export は禁止
- エラーは Result 型で返す（例外は境界層でのみ catch）
- 新規APIには必ず zod スキーマを定義
# やってはいけないこと
- `prisma/migrations/` を手で編集しない
- `.env` を読み書きしない
- 依存パッケージを勝手に追加しない（追加時は理由を説明）
# 作業完了の定義
- typecheck / lint / test がすべて通ることポイント：
- 短く具体的に。抽象的な「きれいに書く」より「
any禁止」のほうが効く - AIが間違えたことを都度追記して育てる
- ディレクトリ単位で補足ファイルを置けるツールなら、モジュール固有のルールはそちらへ
2.2 機械的なガードレールを整備する
AIは「指示」より「失敗するチェック」によく従います。
- 型チェック：TypeScript の
strict、Python の mypy / pyright - Linter / Formatter：ESLint、Ruff、Prettier など
- テスト：高速に実行できる単体テストを充実させる
- pre-commit フック：コミット前に自動検証
- CI：PR ごとに全チェックを実行
2.3 コードベースをAIフレンドリーにする
- 一貫した命名とディレクトリ構成（AIは既存パターンを模倣する）
- 1ファイルを巨大にしない（目安：数百行以内）
- 型・インターフェースを明示し、暗黙の前提を減らす
- READMEや設計ドキュメント（ADR）を最新に保つ
3. タスクの渡し方（プロンプト設計）
3.1 良い依頼の構成要素
- 目的（Why）：何のための変更か
- 要件（What）：満たすべき振る舞い、受け入れ条件
- 制約（How not）：触ってはいけない範囲、使うべき/使ってはいけないライブラリ
- 参照（Where）：関連ファイル、真似すべき既存実装
- 完了条件（Done）：どのコマンドが通れば完了か
3.2 悪い例 / 良い例
❌ 悪い例
ユーザー検索機能を作って
✅ 良い例
管理画面にユーザー検索機能を追加してください。
## 目的
サポート担当がメールアドレスや名前から素早くユーザーを特定できるようにする。
## 要件
- 名前・メールの部分一致検索（大文字小文字を区別しない）
- 結果は20件ずつページネーション
- 空文字での検索は全件ではなくエラーを返す
## 参照
- APIの書き方は src/api/orders/search.ts を踏襲
- UIは src/components/OrderSearch.tsx と同じ構成
## 制約
- 新しい依存パッケージは追加しない
- DBスキーマは変更しない（既存インデックスで足りなければ相談）
## 完了条件
- pnpm typecheck && pnpm lint && pnpm test が通る
- 新規APIの単体テストを追加
3.3 効果的なテクニック
- まず計画させる：「実装前に方針と変更ファイル一覧を出して。承認後に実装」
- 質問を促す：「不明点があれば実装前に質問して」
- 例を見せる：期待する入出力や既存コードを示す（Few-shot）
- 否定より肯定：「〜するな」だけでなく「代わりに〜する」を示す
- スクリーンショット・エラーログをそのまま渡す：要約より原文のほうが正確
4. 開発ワークフロー
4.1 推奨サイクル：探索 → 計画 → 実装 → 検証 → コミット
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ 探索 │ → │ 計画 │ → │ 実装 │ → │ 検証 │ → │ コミット │
│ 既存コード│ │ 方針合意 │ │ 小さく │ │ テスト │ │ 小さく │
│ を読ませる│ │ (人間承認)│ │ 進める │ │ 実行 │ │ 頻繁に │
└─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
- 探索：関連コードを読ませ、まだ書かせない
- 計画：設計方針・影響範囲・リスクを出させ、人間が承認
- 実装：計画に沿って小さなステップで実装
- 検証：テスト・型・lint を実行させ、失敗したら自分で直させる
- コミット：意味のある単位でコミット。差分は人間が確認
4.2 テスト駆動開発（TDD）との組み合わせ
AIと最も相性が良い手法の一つです。
- 仕様からテストを先に書かせる（この時点では実装させない）
- テストが失敗することを確認
- テストを人間がレビューし、仕様の過不足をチェック
- テストが通るまで実装させる（テストを書き換えて通すのは禁止と明示）
4.3 タスクの粒度
| 粒度 | 向いている任せ方 |
|---|---|
| 数行〜1関数 | 補完・インライン編集 |
| 1機能・数ファイル | エージェントに一括依頼 + 差分レビュー |
| 複数機能・横断的変更 | 人間が分割 → 各サブタスクをエージェントへ |
| 大規模リファクタ・移行 | 計画書を作らせて合意 → 段階的に実行、各段階でCIを通す |
4.4 並列化
- 独立したタスクは複数のエージェントセッションで並列実行できる
git worktreeなどで作業ディレクトリを分けて衝突を防ぐ- 並列にするほどレビュー負荷が上がる点に注意。レビュー能力がボトルネックになる
4.5 行き詰まったとき
- 同じ修正を2〜3回失敗したら、会話を続けずにリセットして情報を整理し直す
- エラーの原因仮説を複数出させてから、検証方法を指定する
- AIが「直した」と言っても、実際にテストを実行して確認する
5. テストと品質保証
- AIの「動きました」を信じない：必ずコマンドの実行結果で確認する
- テストの質をレビューする：AIはテストを通すために意味の薄いテスト（モックだらけ、assertなし）を書きがち
- 境界値・異常系を明示的に要求する：放っておくと正常系に偏る
- E2E / ビジュアル検証：UI変更はスクリーンショットやブラウザ操作で確認させる
- カバレッジは目安：数値より、重要なロジックが検証されているかを見る
6. コードレビュー
6.1 AI生成コードで特に見るべきポイント
- 仕様の取り違え：要件を勝手に拡大・縮小していないか
- 存在しないAPIの使用（ハルシネーション）：ライブラリのバージョンと照合
- 不要な変更：依頼範囲外のリファクタやフォーマット変更
- 重複実装：既存ユーティリティを使わず再実装していないか
- エラーハンドリング：例外の握りつぶし、過剰な try-catch
- テストの改ざん：テストを弱めて通していないか
- セキュリティ：入力検証、認可チェック、SQLインジェクション、秘密情報のハードコード
- パフォーマンス：N+1クエリ、不要なループ
- 過剰な抽象化 / コメント：冗長な説明コメントや不要なレイヤー
6.2 レビューの工夫
- 別のAIセッション（実装に関与していない）にレビューさせる
- 「この変更のリスクを3つ挙げて」と批判的視点を求める
- PR説明もAIに書かせ、意図と差分が一致しているか確認する
7. コンテキスト管理
AIのコンテキストウィンドウは有限です。長い会話ほど初期の指示が薄れ、精度が落ちます。
- タスクごとに新しいセッションを始める
- 長い作業では、進捗・決定事項をファイル（例：
PLAN.md、NOTES.md）に書き出させ、次のセッションで読ませる - 無関係なファイルを大量に読ませない
- 大きな調査はサブエージェントに任せ、結論だけを受け取る
- 重要な制約は指示ファイルに書き、会話に依存しない
8. セキュリティとガバナンス
8.1 権限の最小化
- エージェントに許可するコマンド・ディレクトリを限定する
- 本番環境・本番DBへの直接アクセスは与えない
- 破壊的操作（
rm -rf、git push --force、DBマイグレーション）は人間の承認を必須にする - 可能ならサンドボックスやコンテナ内で実行する
8.2 秘密情報の保護
.envや認証情報をAIに読ませない（ignore設定を活用）- ログやエラー出力に秘密情報が含まれていないか確認してから渡す
- 社内規定・利用ツールのデータ取り扱いポリシーを確認する
8.3 プロンプトインジェクション対策
- 外部から取得したコンテンツ（Webページ、Issue本文、依存パッケージのREADME）に埋め込まれた指示にAIが従う危険がある
- 信頼できない入力を扱うタスクでは、エージェントの権限をさらに絞る
8.4 依存関係とライセンス
- AIが提案したパッケージは実在・メンテ状況・ライセンスを確認する（実在しないパッケージ名を狙った攻撃もある）
- 依存追加は人間の承認制にする
9. チーム運用
- 指示ファイルをリポジトリで共有し、PRで改善していく
- よく使うプロンプトをテンプレート化（カスタムコマンド、スラッシュコマンド、スキルなど）
- AI利用ガイドラインを明文化：使ってよい範囲、レビュー基準、禁止事項
- 成功・失敗事例を共有：うまくいった依頼の仕方をナレッジ化
- ジュニアの学習機会を守る：AIの出力を説明できることをレビュー条件にする
- 効果測定：リードタイム、レビュー時間、バグ発生率などを導入前後で比較する
10. アンチパターン
| アンチパターン | 問題 | 対策 |
|---|---|---|
| 丸投げ | 曖昧な依頼 → 意図と違う大量のコード | 要件・制約・完了条件を明示 |
| 盲目的マージ | 理解していないコードが本番へ | 説明できないコードはマージしない |
| 巨大PR | レビュー不能、バグの温床 | タスク分割、小さなコミット |
| 無限リトライ | 同じ会話で修正を繰り返し品質劣化 | セッションをリセットして再整理 |
| テスト改ざんの見逃し | テストが仕様を守らなくなる | テスト変更は特に注意してレビュー |
| 指示ファイル放置 | 同じミスが繰り返される | ミスのたびに追記 |
| 過剰な権限 | 誤操作で本番破壊・情報漏洩 | 最小権限、承認フロー |
| 設計の外注 | 一貫性のないアーキテクチャ | 設計判断は人間が行う |
11. チェックリスト
導入時
- エージェント向け指示ファイル（
CLAUDE.md/AGENTS.md等）を作成した - 型チェック・lint・テストがコマンド一発で実行できる
- CIで全チェックが自動実行される
- エージェントの権限範囲を設定した
- 秘密情報をAIから除外する設定をした
- チームのAI利用ガイドラインを共有した
タスク依頼時
- 目的・要件・制約・参照・完了条件を伝えた
- 大きなタスクは計画を先に出させた
- タスクはレビュー可能なサイズか
マージ前
- すべての自動チェックが通っている
- 差分をすべて読み、説明できる
- 依頼範囲外の変更がない
- テストが弱められていない
- セキュリティ上の懸念を確認した
最終更新：2026年10月