Claude Code エージェント活用術｜自律的なAI開発のベストプラクティス
Claude Code は対話的なコーディングアシスタントとしてだけでなく、自律的に動くエージェントとして活用できます。ヘッドレス実行や CI/CD パイプラインへの統合により、人間の介入なしにコードレビュー、テスト生成、ドキュメント更新といったタスクを自動化できるのが大きな強みです。
本記事では、Claude Code をエージェントとして運用するためのベストプラクティスを解説します。自律モードの設定、ヘッドレス実行の方法、GitHub Actions との連携、自動コードレビューや自動テスト生成の実例、そしてセキュリティ上の注意点まで、実践的な内容を網羅的に紹介します。
エージェントとしての Claude Code
AIエージェントとは何か
AIエージェントとは、与えられたゴールに対して自律的に計画を立て、ツールを使い、タスクを完了まで推進するシステムのことです。従来の「質問に答えるだけ」のAIチャットボットとは異なり、AIエージェントは以下の能力を持ちます。
- 計画の立案: タスクをステップに分解し、実行順序を決定する
- ツールの使用: ファイル操作、コマンド実行、API 呼び出しなどを自律的に行う
- フィードバックループ: 実行結果を確認し、必要に応じて方針を修正する
- 最終ゴールへの到達: 中間的なエラーを自己修復しながら完了まで進む
Claude Code はまさにこの定義に合致するエージェント型ツールです。コードベースを読み、ファイルを編集し、テストを実行し、その結果に基づいて修正を行う。この一連のプロセスを人間の指示なしに遂行できます。
対話モードとエージェントモードの違い
Claude Code の通常の使い方（対話モード）では、開発者がプロンプトに指示を入力し、結果を確認し、必要に応じて追加の指示を出します。毎回のステップで人間が判断を下す「人間主導」のワークフローです。
一方、エージェントモードでは、Claude Code に大きなゴールを与えて、達成までの過程を自律的に任せます。例えば「このプルリクエストの全ファイルをレビューして、問題があれば指摘して」という指示を与えれば、Claude Code はファイルを順に読み、コードの問題点を分析し、レポートを生成するまでを一気に実行します。
この「自律的な実行」を安全かつ効率的に行うための仕組みが、以下で解説する自律モードやヘッドレス実行です。
自律モード（--allowedTools フラグ）
パーミッション制御の基本
Claude Code はデフォルトで、ファイルの書き込みやコマンドの実行のたびにユーザーの承認を求めます。対話的に使う場合はこれで問題ありませんが、エージェントとして自律的に動かす場合は承認の要求が実行を中断してしまいます。
この問題を解決するのが --allowedTools フラグです。使用を許可するツールを明示的に指定することで、指定された範囲内の操作は承認なしに自動実行されます。
# ファイルの読み書きとBash実行を許可
claude -p "src/ のテストカバレッジが低い関数を特定して、テストを追加して" \
--allowedTools "Read,Write,Edit,Bash"
--allowedTools の使い方
--allowedTools フラグには、許可するツール名をカンマ区切りで指定します。主なツール名は以下の通りです。
| ツール名 | 機能 |
|---|---|
Read | ファイルの読み取り |
Write | 新規ファイルの作成 |
Edit | 既存ファイルの編集 |
Bash | シェルコマンドの実行 |
Glob | ファイルパターン検索 |
Grep | コンテンツ検索 |
WebFetch | Web コンテンツの取得 |
用途に応じて許可するツールを絞り込むことで、安全性と自律性のバランスを取れます。
# 読み取りのみ許可（分析タスクに適している）
claude -p "このプロジェクトのアーキテクチャを分析して" \
--allowedTools "Read,Glob,Grep"
# 読み書き + テスト実行を許可
claude -p "バグを修正してテストが通ることを確認して" \
--allowedTools "Read,Write,Edit,Bash"
--disallowedTools との使い分け
逆に、特定のツールだけを禁止したい場合は --disallowedTools フラグが便利です。「基本的には全ツールを使ってよいが、Web アクセスだけは禁止する」といった制御ができます。
# Web アクセス以外はすべて許可
claude -p "リファクタリングを実施して" \
--disallowedTools "WebFetch,WebSearch"
permission-mode の活用
より包括的なパーミッション制御には --permission-mode フラグを使います。
# plan モード: 読み取りのみ許可（書き込み・実行は承認が必要）
claude -p "改善点をリストアップして" --permission-mode plan
# bypasstool モード: すべてのツール実行を承認なしで許可
claude -p "テストを修正して全部通るようにして" --permission-mode bypasstool
plan モードは読み取りのみの分析タスクに、bypasstool モードは信頼できる環境での完全自律実行に適しています。ただし、bypasstool は強力なモードであるため、使用する環境には十分注意してください。
ヘッドレス実行（-p フラグ + パイプ）
非対話モードでの自律実行
-p（--print）フラグを使うと、Claude Code を非対話（ヘッドレス）モードで実行できます。対話セッションを開始せず、指示を処理して結果を出力し、即座に終了します。
# 基本的なヘッドレス実行
claude -p "src/utils.ts のデッドコードを削除して"
# JSON 形式で結果を取得
claude -p "このプロジェクトの依存関係を分析して" --output-format json
# ターン数を制限して実行
claude -p "簡単なバグ修正をして" --max-turns 5
ヘッドレス実行は、スクリプトや CI/CD パイプラインに Claude Code を組み込む際の基本形です。
パイプとの組み合わせ
Unix のパイプを活用すると、他のコマンドの出力を Claude Code に渡して分析させることができます。
# テスト結果を分析して修正
npm test 2>&1 | claude -p "失敗しているテストを修正して" \
--allowedTools "Read,Write,Edit,Bash"
# 型チェックのエラーを自動修正
npx tsc --noEmit 2>&1 | claude -p "これらの型エラーをすべて修正して" \
--allowedTools "Read,Edit"
# lint エラーを自動修正
npx eslint src/ 2>&1 | claude -p "これらの ESLint エラーを修正して" \
--allowedTools "Read,Edit"
--max-turns による制御
エージェントとして自律的に動かす場合、無限にターンを消費しないよう --max-turns フラグで上限を設定することが重要です。
# 最大10ターンで完了するよう制限
claude -p "このバグを修正してテストを通して" \
--max-turns 10 \
--allowedTools "Read,Write,Edit,Bash"
ターン数が上限に達すると Claude Code は実行を停止します。タスクが完了していない場合は --continue で再開できます。
CI/CD への統合パターン
CI/CD 統合の基本アーキテクチャ
Claude Code を CI/CD パイプラインに統合する際の基本的な考え方は「コードの変更をトリガーに、AI による分析や修正を自動実行する」というものです。
典型的な統合パターンは以下の通りです。
- プルリクエスト時の自動レビュー: PR の作成・更新をトリガーに、コード差分を分析してレビューコメントを投稿する
- プッシュ時の自動修正: コミットのプッシュをトリガーに、lint エラーや型エラーを自動修正して新しいコミットを作成する
- スケジュール実行: 定期的にコード品質の分析やセキュリティチェックを実行する
- Issue 駆動の自動実装: Issue の作成をトリガーに、Claude Code が実装を行い PR を作成する
環境変数の設定
CI/CD 環境で Claude Code を使うには、API キーの設定が必要です。
# 環境変数として設定（CI の secrets に登録）
export ANTHROPIC_API_KEY=${{ secrets.ANTHROPIC_API_KEY }}
API キーは絶対にコードにハードコードしないでください。CI/CD プラットフォームの secrets 機能を使って安全に管理しましょう。
GitHub Actions での活用例
claude-code-action の導入
Anthropic が提供する公式 GitHub Action anthropics/claude-code-action を使えば、最小限の設定で Claude Code を GitHub Actions に統合できます。
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
この設定だけで、プルリクエストが作成・更新されるたびに Claude Code がコード差分をレビューし、レビューコメントを自動投稿してくれます。
Issue からの自動実装
Issue の作成をトリガーにして、Claude Code に自動で実装を行わせるワークフローも構築できます。
name: Claude Code Auto-Implement
on:
issues:
types: [labeled]
jobs:
implement:
if: github.event.label.name == 'claude-code'
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
issues: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
direct_prompt: |
Issue の内容に基づいて実装を行い、
プルリクエストを作成してください。
テストも追加してください。
use_bedrock: false
claude-code ラベルを Issue に付けるだけで、Claude Code が自動的に実装を開始し、PR を作成します。
CLI を直接使う方法
公式 Action を使わずに、CLI を直接インストールして使う方法もあります。より細かい制御が必要な場合に有効です。
name: Claude Code Analysis
on:
pull_request:
types: [opened, synchronize]
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Claude Code
run: npm install -g @anthropic-ai/claude-code
- name: Run Analysis
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
git diff origin/main...HEAD | claude -p \
"この差分をレビューしてください。
以下の観点でチェックしてください:
1. セキュリティ上の問題
2. パフォーマンスの懸念
3. コーディング規約への準拠
4. テストの網羅性" \
--allowedTools "Read,Glob,Grep" \
--output-format json \
--max-turns 15 > review-result.json
- name: Post Review Comment
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const result = JSON.parse(fs.readFileSync('review-result.json', 'utf8'));
await github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: `## AI Code Review\n\n${result.result}`
});
Claude Code を使った自動コードレビュー
レビューの自動化が解決する課題
コードレビューは開発プロセスにおいて不可欠ですが、いくつかの課題を抱えています。
- レビュー待ち時間: レビュアーが忙しいと PR がマージされるまでに時間がかかる
- レビューの一貫性: レビュアーによってチェック基準が異なる
- 見落とし: 人間のレビューではセキュリティリスクや微細なバグを見逃すことがある
- 大きな差分の負担: 変更行数が多い PR のレビューは精神的な負担が大きい
Claude Code による自動レビューは、これらの課題を補完する形で機能します。人間のレビューを置き換えるものではなく、事前に機械的なチェックを行うことで、人間のレビュアーがより重要な設計判断に集中できるようにするのが目的です。
プロジェクト固有のレビュー基準
CLAUDE.md にレビュー基準を記述しておけば、プロジェクト固有のルールに基づいたレビューが可能です。
# CLAUDE.md（レビュー用の設定例）
## コードレビュー基準
- 生の HTML タグ（button, input, table）を使っていないか確認する
- API レスポンスに適切なエラーハンドリングがあるか確認する
- 新しい API エンドポイントに認可チェックがあるか確認する
- SQL クエリに organization_id フィルタがあるか確認する
- 機密情報（API キー、パスワード）がハードコードされていないか確認する
これにより、レビューの質がプロジェクトの成長とともに向上していきます。
差分レビューの実装パターン
プルリクエストの差分に絞ったレビューを行うスクリプトの例です。
#!/bin/bash
# scripts/ai-review.sh
BASE_BRANCH=${1:-main}
echo "=== AI Code Review ==="
echo "Base branch: $BASE_BRANCH"
# 変更されたファイル一覧を取得
CHANGED_FILES=$(git diff --name-only "$BASE_BRANCH"...HEAD)
echo "Changed files: $CHANGED_FILES"
# 差分を取得してレビュー
git diff "$BASE_BRANCH"...HEAD | claude -p \
"以下のコード差分をレビューしてください。
変更ファイル:
$CHANGED_FILES
レビュー観点:
1. バグの可能性がある箇所
2. セキュリティ上のリスク
3. パフォーマンスへの影響
4. 改善提案
各指摘は「ファイル名:行番号」の形式で場所を示してください。
問題がなければ『LGTM』と回答してください。" \
--allowedTools "Read,Glob,Grep" \
--max-turns 15
自動テスト生成・実行
テスト生成の自動化
Claude Code をエージェントとして活用する最も実用的なユースケースの一つが、テストの自動生成です。
# 変更されたファイルに対してテストを自動生成
git diff --name-only main...HEAD | while read file; do
if [[ "$file" == *.ts && "$file" != *.test.ts && "$file" != *.spec.ts ]]; then
echo "Generating tests for: $file"
claude -p "以下のファイルのユニットテストを作成してください: $file
- 正常系と異常系の両方をカバー
- 既存のテストファイルがあればそれに追加
- プロジェクトのテストフレームワーク（Vitest）に準拠" \
--allowedTools "Read,Write,Edit,Glob,Grep" \
--max-turns 10
fi
done
テスト実行と自動修正
テストの実行結果を Claude Code にフィードバックして、失敗したテストを自動修正するループも構築できます。
#!/bin/bash
# scripts/auto-fix-tests.sh
MAX_ATTEMPTS=3
ATTEMPT=1
while [ $ATTEMPT -le $MAX_ATTEMPTS ]; do
echo "=== Attempt $ATTEMPT / $MAX_ATTEMPTS ==="
# テストを実行
TEST_OUTPUT=$(npm test 2>&1)
EXIT_CODE=$?
if [ $EXIT_CODE -eq 0 ]; then
echo "All tests passed!"
exit 0
fi
echo "Tests failed. Asking Claude Code to fix..."
# 失敗したテストを Claude Code に修正させる
echo "$TEST_OUTPUT" | claude -p \
"テストが失敗しています。エラーメッセージを分析して、
テストコードまたはソースコードを修正してください。
テストの期待値が間違っている場合はテストを修正し、
ソースコードにバグがある場合はソースコードを修正してください。" \
--allowedTools "Read,Write,Edit,Bash,Glob,Grep" \
--max-turns 10
ATTEMPT=$((ATTEMPT + 1))
done
echo "Failed to fix tests after $MAX_ATTEMPTS attempts."
exit 1
CI での自動テストパイプライン
GitHub Actions でテスト生成と実行を自動化するワークフローの例です。
name: Auto Test Generation
on:
pull_request:
types: [opened, synchronize]
paths:
- 'src/**/*.ts'
- '!src/**/*.test.ts'
jobs:
generate-tests:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: '22'
- run: npm ci
- name: Install Claude Code
run: npm install -g @anthropic-ai/claude-code
- name: Generate and Run Tests
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
CHANGED=$(git diff --name-only origin/main...HEAD \
| grep '\.ts$' \
| grep -v '\.test\.ts$' \
| grep -v '\.spec\.ts$')
for file in $CHANGED; do
claude -p "このファイルのテストを生成してください: $file" \
--allowedTools "Read,Write,Edit,Glob,Grep" \
--max-turns 8
done
npm test
- name: Commit Generated Tests
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add -A '*.test.ts' '*.spec.ts'
git diff --cached --quiet || \
git commit -m "test: auto-generate tests for changed files"
git push
セキュリティ考慮事項
CI/CD 環境でのリスク
Claude Code をエージェントとして自律実行する場合、特に CI/CD 環境ではセキュリティに関する慎重な判断が必要です。主なリスクには以下のものがあります。
- API キーの漏洩: 環境変数やログに API キーが露出する可能性
- 意図しないコード変更: エージェントが予期しないファイルを変更する可能性
- 機密ファイルへのアクセス:
.envファイルや認証情報を含むファイルの読み取り - 悪意ある入力の注入: プルリクエストのタイトルや Issue の本文にプロンプトインジェクションが含まれる可能性
安全な運用のためのガイドライン
以下のガイドラインに従うことで、エージェントモードでも安全に Claude Code を運用できます。
最小権限の原則を適用する:
# 読み取りだけで十分なタスクには書き込み権限を与えない
claude -p "コードを分析して" --allowedTools "Read,Glob,Grep"
# 書き込みが必要でも Bash 実行は許可しない
claude -p "型エラーを修正して" --allowedTools "Read,Edit"
実行環境を隔離する:
# Docker コンテナ内で実行して影響範囲を限定する
jobs:
review:
runs-on: ubuntu-latest
container:
image: node:22-slim
出力を検証する:
# Claude Code の変更後に既存のテストを実行して検証
claude -p "リファクタリングして" --allowedTools "Read,Write,Edit"
npm test # 変更が既存の動作を壊していないか確認
npx tsc --noEmit # 型チェック
機密ファイルを保護する:
.claude/settings.json で機密ファイルへのアクセスを制限できます。
{
"deny": [
"Read:.env*",
"Read:**/credentials*",
"Read:**/*.pem",
"Write:.env*",
"Edit:.env*"
]
}
セキュリティ設定の詳細については、以下の記事で詳しく解説しています。
ベストプラクティスまとめ
Claude Code をエージェントとして効果的に活用するためのベストプラクティスを整理します。
1. 段階的に自律性を高める
最初から完全自律モードで運用するのではなく、段階的に自律性を高めていくアプローチが推奨されます。
- ステップ1: 読み取り専用の分析タスク（コードレビュー、品質分析）から始める
- ステップ2: 限定的な書き込みを許可する（テスト生成、ドキュメント更新）
- ステップ3: CI/CD パイプラインに統合して自動実行する
- ステップ4: Issue 駆動の自動実装など、より高度な自律タスクに拡張する
2. CLAUDE.md でコンテキストを与える
エージェントモードでは対話的な補足ができないため、CLAUDE.md に十分なコンテキストを記述しておくことが特に重要です。コーディング規約、アーキテクチャの方針、禁止事項などを明記しましょう。
3. --max-turns で暴走を防ぐ
自律実行時は必ず --max-turns を設定してターン数の上限を決めてください。無制限に実行させると、意図しないトークン消費やファイル変更が発生するリスクがあります。
4. 結果を必ず検証する
エージェントによる変更は、既存のテストスイートや CI パイプラインで必ず検証してください。「AIが変更したから大丈夫」と思い込まず、人間のレビューも組み合わせるのが安全です。
5. ログと監査証跡を残す
CI/CD でのエージェント実行は、--output-format json を使って結果をログとして保存しておきましょう。問題が起きたときのトラブルシューティングや、エージェントの精度改善に役立ちます。
claude -p "タスクを実行して" \
--output-format json \
--max-turns 10 \
--allowedTools "Read,Edit,Bash" \
> "logs/agent-$(date +%Y%m%d-%H%M%S).json"
6. 人間のレビューと組み合わせる
Claude Code のエージェント機能は、開発者を置き換えるものではありません。機械的に処理できる定型タスクを自動化し、人間はより創造的で判断が必要な作業に集中するための仕組みです。最終的な品質の責任は常に人間にあることを忘れないでください。
まとめ
Claude Code をエージェントとして活用することで、開発ワークフローの多くの部分を自動化できます。本記事で紹介した内容を振り返ります。
- エージェントとしての Claude Code: 自律的にコードを読み、分析し、修正するAIエージェントとして機能する
- 自律モード:
--allowedToolsや--permission-modeで安全に自律実行を制御できる - ヘッドレス実行:
-pフラグとパイプを組み合わせてスクリプトや CI/CD に組み込める - GitHub Actions 連携:
claude-code-actionで最小限の設定でPRレビューを自動化できる - 自動コードレビュー: プロジェクト固有の基準に基づいた一貫性のあるレビューを実現できる
- 自動テスト生成: 変更されたファイルに対して自動でテストを生成・実行できる
- セキュリティ: 最小権限の原則、環境の隔離、機密ファイルの保護が重要
まずは読み取り専用の分析タスクから始めて、プロジェクトの成熟度に合わせて段階的に自律性を高めていくのがおすすめです。Claude Code の Skills 機能と組み合わせれば、チーム全体の開発効率をさらに向上させることができます。