Claude Code エージェント自動化ガイド — Agent SDK・カスタムエージェント・実務パターンまで【2026年版】

Claude Code のエージェント機能とは — AIが自律的にタスクを実行する仕組み

「コードを書くだけでなく、テスト実行・リファクタリング・PR作成まで自動でやってくれるAIがあったら？」 Claude Code のエージェント機能は、まさにそれを実現するツールです。

Claude Code は Anthropic が提供するターミナルベースの AI コーディングアシスタントですが（基本的な使い方は「Claude Code完全ガイド」を参照）、単なるコード補完ツールではありません。エージェントとして動作するとき、Claude Code はタスクの計画→ファイルの読み書き→コマンド実行→結果の検証というサイクルを自律的に回します。

エージェント機能でできること

• マルチステップのタスク実行: 1つの指示から複数ファイルの編集、テスト実行、修正までを一貫して行う
• コンテキスト理解: プロジェクト全体のコードベースを読み取り、既存のパターンに合わせたコードを生成する
• ツール連携: git、npm、pytest など開発ツールをターミナル経由で直接操作する
• 自己修正: エラーが発生した場合、原因を分析して修正を試みる

従来のAIコーディングツールとの違い

特徴	従来のAI補完	Claude Code エージェント
操作範囲	単一ファイル内の補完	プロジェクト全体の読み書き
タスク実行	1ステップずつ手動	マルチステップを自律実行
コマンド実行	不可	ターミナルコマンドを直接実行
エラー対応	ユーザーが修正	自動で原因分析・修正
コンテキスト	開いているファイルのみ	リポジトリ全体

---

Agent SDK の概要 — プログラムから Claude Code を制御する

Claude Code の Agent SDK は、Claude Code のエージェント機能をプログラムから制御するためのインターフェースです。これにより、独自のワークフローに Claude Code を組み込むことが可能になります。

Agent SDK の基本構成

Agent SDK は主に以下のコンポーネントで構成されています。

// Agent SDK の基本的な使い方
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

// メッセージを送信してエージェントを実行
const response = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 16384,
  tools: [
    {
      type: "computer_20250124",
      name: "computer",
      display_width_px: 1024,
      display_height_px: 768,
    },
    {
      type: "bash_20250124",
      name: "bash",
    },
    {
      type: "text_editor_20250124",
      name: "text_editor",
    },
  ],
  messages: [
    {
      role: "user",
      content: "プロジェクトのテストを実行して、失敗しているテストを修正してください",
    },
  ],
});

SDK が提供するツール

Agent SDK では、エージェントが使用できるツールが定義されています。

ツール名	機能	用途
bash	シェルコマンドの実行	ビルド、テスト、git操作
text_editor	ファイルの読み書き	コード編集、設定変更
computer	GUI操作	ブラウザテスト等

エージェントループの仕組み

Agent SDK を使ったエージェントは、以下のループで動作します。

// エージェントループの実装例
async function agentLoop(initialPrompt: string) {
  let messages = [{ role: "user", content: initialPrompt }];

  while (true) {
    const response = await client.messages.create({
      model: "claude-sonnet-4-20250514",
      max_tokens: 16384,
      tools: tools,
      messages: messages,
    });

    // レスポンスをメッセージ履歴に追加
    messages.push({ role: "assistant", content: response.content });

    // stop_reason が "end_turn" なら終了
    if (response.stop_reason === "end_turn") {
      break;
    }

    // ツール使用の結果を収集して返す
    if (response.stop_reason === "tool_use") {
      const toolResults = await executeTools(response.content);
      messages.push({ role: "user", content: toolResults });
    }
  }

  return messages;
}

💡 Tips: エージェントループは「指示→計画→実行→確認→修正」のサイクルを自動で回す仕組みです。人間が介在しなくても、エラーが出たら自己修正を試みます。

---

カスタムエージェントの作成 — 独自のワークフローを構築する

Claude Code では、特定のタスクに特化したカスタムエージェントを作成できます。プロジェクトの .claude/agents/ ディレクトリにエージェント定義を配置することで、チーム全体で再利用可能な自動化ワークフローを構築できます。

エージェント定義ファイルの作成

カスタムエージェントは Markdown ファイルで定義します。

<!-- .claude/agents/test-runner.md -->
# テスト自動実行エージェント

## 役割
プロジェクトのテストを実行し、失敗したテストを修正するエージェントです。

## 手順
1. `npm test` を実行してテスト結果を確認する
2. 失敗したテストがあれば、エラーメッセージを分析する
3. 該当するソースコードとテストコードを読み込む
4. 修正を実施する
5. 再度テストを実行して成功を確認する

## ルール
- テストコードの修正よりソースコードの修正を優先する
- 既存のテストパターンに合わせてコードを書く
- 修正後は必ず全テストを再実行する

よく使うカスタムエージェントの例

以下は、実務で役立つカスタムエージェントのテンプレートです。

コードレビューエージェント

<!-- .claude/agents/code-reviewer.md -->
# コードレビューエージェント

## 役割
変更されたコードを読み取り、品質・セキュリティの観点からレビューする。

## チェック項目
- [ ] 型安全性が保たれているか
- [ ] エラーハンドリングが適切か
- [ ] セキュリティ上の問題がないか
- [ ] パフォーマンス上の懸念がないか
- [ ] テストカバレッジは十分か

## 出力フォーマット
| 重要度 | ファイル | 行 | 指摘内容 |
|--------|---------|-----|---------|

ドキュメント生成エージェント

<!-- .claude/agents/doc-generator.md -->
# ドキュメント生成エージェント

## 役割
コードから自動的にドキュメントを生成する。

## 手順
1. 変更されたファイルを特定する
2. 公開APIの関数・クラスを抽出する
3. JSDoc/TSDoc形式でドキュメントを生成する
4. READMEに変更があれば更新する

---

実務での自動化パターン — テスト・リファクタ・PR作成

ここからは、Claude Code エージェントを使った具体的な自動化パターンを紹介します。

パターン1: テスト自動実行と修正

テストの実行から修正までを一括で行う最も基本的なパターンです。

# Claude Code にテスト自動実行を依頼
claude "テストを実行して、失敗しているテストをすべて修正してください"

このとき Claude Code は以下の手順を自律的に実行します。

1. npm test や pytest などのテストコマンドを実行
2. 失敗したテストのエラーメッセージを分析
3. 関連するソースコードを読み込み
4. 修正コードを生成・適用
5. テストを再実行して成功を確認

# より具体的な指示の例
claude "src/utils/ 以下のユーティリティ関数に対して、
カバレッジ80%以上のユニットテストを作成して実行してください。
テストフレームワークは Vitest を使ってください。"

パターン2: コードリファクタリングの自動化

大規模なリファクタリングもエージェントに任せることができます。

# リファクタリングの指示例
claude "src/components/ 以下のReactコンポーネントを以下の方針でリファクタリングしてください:
1. クラスコンポーネントを関数コンポーネントに変換
2. useStateとuseEffectを適切に使用
3. PropTypesをTypeScriptの型定義に変換
4. 変更後にテストが通ることを確認"

エージェントは各コンポーネントを順番に変換し、テストを実行しながら進めます。途中でエラーが発生しても自動で修正を試みるため、人間が介入する必要がありません。

パターン3: PR の自動作成

Issue から PR を作成するワークフローは、Claude Code の得意分野です。

# Issue番号を指定してPRを自動作成
claude "GitHub Issue #42 の内容を読み取り、
必要なコード変更を実装してPRを作成してください。
コミットメッセージはConventional Commitsに従ってください。"

PR自動作成の流れ

Issue読み取り → 変更計画の立案 → ブランチ作成
    → コード実装 → テスト実行 → コミット → PR作成

パターン4: ヘッドレスモードでの自動化

Claude Code はヘッドレスモード（非対話型）で実行することも可能です。CI/CDパイプラインに組み込む場合に便利です。

# ヘッドレスモードでの実行
claude --print "このリポジトリのREADMEを最新の状態に更新してください"

# パイプで入力を渡す
echo "テストを実行して結果を報告してください" | claude --print

パターン5: GitHub Actions との連携

GitHub Actions から Claude Code を呼び出すことで、PR作成時の自動レビューやIssue起点の自動実装が可能です。GitHub Actionsの基本を押さえたい方は「GitHub Actions入門ガイド」も参考にしてください。

# .github/workflows/claude-review.yml
name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Claude Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npm install -g @anthropic-ai/claude-code
          claude --print "このPRの変更内容をレビューして、
          問題があればコメントとして指摘してください"

---

CLAUDE.md との連携 — エージェントの品質を最大化する

エージェント機能を最大限に活かすには、CLAUDE.md（プロジェクトの設定ファイル）との連携が重要です。

エージェント用の CLAUDE.md 設定例

# プロジェクト設定

## 技術スタック
- フレームワーク: Next.js 15 (App Router)
- 言語: TypeScript 5.x
- テスト: Vitest + Testing Library
- リンター: ESLint + Prettier
- パッケージマネージャー: pnpm

## コーディング規約
- 関数コンポーネントのみ使用
- named export を優先
- エラーは Result型 パターンで処理
- magic number 禁止

## テストルール
- テストファイルは __tests__/ ディレクトリに配置
- テスト名は日本語で記述可
- モックは最小限に留める

## エージェント向け設定
- 変更前に必ず既存テストを実行する
- コミットメッセージは Conventional Commits に従う
- 本番ブランチへの直接pushは禁止

CLAUDE.md がエージェントに与える効果

項目	CLAUDE.md なし	CLAUDE.md あり
コード品質	プロジェクトの慣習と異なるコードが生成される	既存のパターンに一致したコードが生成される
テスト配置	不明な場所にテストファイルが作られる	規定のディレクトリに正しく配置される
コミット	メッセージがバラバラ	Conventional Commits に統一される
エラー処理	try-catch が乱立する	プロジェクトの方針に合った処理になる

---

エージェント活用のベストプラクティス

1. 指示は具体的に書く

曖昧な指示はエージェントの判断を迷わせます。

# ❌ 曖昧な指示
claude "コードをきれいにして"

# ✅ 具体的な指示
claude "src/utils/date.ts の関数をリファクタリングして。
具体的には:
1. any型をすべて適切な型に置き換える
2. 重複ロジックをヘルパー関数に抽出する
3. JSDocコメントを追加する
4. 既存テストが通ることを確認する"

2. 段階的に実行する

大きなタスクは一度に依頼せず、段階的に進めるのが安全です。

# フェーズ1: 調査
claude "src/legacy/ ディレクトリのコードを分析して、
リファクタリングが必要な箇所をリストアップしてください"

# フェーズ2: 実装（調査結果を踏まえて）
claude "先ほどの分析結果に基づいて、
優先度の高い3ファイルのリファクタリングを実施してください"

# フェーズ3: 検証
claude "リファクタリング後のコードに対してテストを実行し、
カバレッジレポートを生成してください"

3. ガードレールを設定する

エージェントが意図しない操作を行わないよう、CLAUDE.md でガードレールを設定しましょう。

## 禁止事項
- node_modules/ や dist/ の内容を変更しない
- .env ファイルをコミットしない
- main ブランチに直接pushしない
- パッケージのメジャーバージョンアップを勝手に行わない

4. 実行結果を必ず確認する

エージェントは強力ですが完璧ではありません。特に以下の点は人間が確認すべきです。

• セキュリティに関わる変更
• データベーススキーマの変更
• 公開APIの破壊的変更
• 本番環境へのデプロイ操作

---

まとめ — Claude Code エージェントで開発ワークフローを自動化する

Claude Code のエージェント機能は、AIコーディングアシスタントを「指示待ちツール」から「自律的なチームメンバー」に進化させるものです。

本記事のポイント

• エージェント機能は、マルチステップのタスクを自律的に計画・実行する
• Agent SDK を使えば、プログラムからエージェントを制御して独自ワークフローを構築できる
• カスタムエージェントを .claude/agents/ に定義することで、チームで再利用可能な自動化が実現する
• 実務パターンとして、テスト自動修正・リファクタリング・PR自動作成・CI連携が有効
• CLAUDE.md との連携でエージェントの出力品質が大幅に向上する

まずは簡単なタスク（テスト実行と修正）からエージェントを試してみてください。筆者のお気に入りのパターンは、朝一番に claude "テストを実行して、失敗があれば修正して" と投げておいて、コーヒーを淹れている間に修正が終わっている——という使い方です。エージェントモードの詳細は「Claude Code エージェントモード完全ガイド」も参照してください。AIエージェントの概念をもっと深く理解したい方には「AIエージェント開発入門」もおすすめです。