Claude Code完全ガイド：サブエージェント、フック、Agent SDK — エージェンティックコーディングのすべて

# Claude Code 基本実行
claude

# 特定のプロンプトで実行
claude "このプロジェクトのアーキテクチャを分析してください"

# パイプラインモード
cat error.log | claude "このエラーの原因を分析して修正してください"

# Node.js 18以上が必要
npm install -g @anthropic-ai/claude-code

# または特定のディレクトリでnpxで実行
npx @anthropic-ai/claude-code

# 初回実行時に認証プロセスが開始
claude

# Anthropicアカウントまたは APIキーで認証
# ブラウザが開き認証完了

# VS Code拡張のインストール
code --install-extension anthropic.claude-code

# 設定の確認
claude config list

# モデル設定 (デフォルト: claude-sonnet-4-20250514)
claude config set model claude-sonnet-4-20250514

# 権限設定
claude config set permissions.allow-edit true
claude config set permissions.allow-exec true

# 自動承認パターンの設定
claude config set permissions.auto-approve-commands "npm test,npm run lint"

# tmuxセッションでClaude Codeを実行（長時間の作業に有用）
tmux new-session -s claude
claude

# 作業ログの保存
claude --output-dir ./claude-logs

# 非対話モード（スクリプトで使用）
claude -p "README.mdを更新してください" --yes

# プロジェクト概要

このプロジェクトはNext.js 14ベースのブログプラットフォームです。
TypeScriptを使用し、Tailwind CSSでスタイリングしています。

# 技術スタック

- Framework: Next.js 14 (App Router)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS
- Database: PostgreSQL + Prisma ORM
- Testing: Jest + React Testing Library

# コーディング規約

- コンポーネント: 関数コンポーネント + アロー関数を使用
- 命名規則: camelCase (変数/関数), PascalCase (コンポーネント/型)
- import順序: 外部ライブラリ > 内部モジュール > 相対パス
- エラーハンドリング: try-catchの代わりにResult型パターンを使用

# テストルール

- すべての新しい関数にユニットテスト必須
- テストコマンド: npm test
- リントコマンド: npm run lint
- PR前に必ず npm run build の成功を確認

# 禁止パターン

- any型の使用禁止
- console.logの使用禁止（loggerを使用）
- ハードコードされた文字列禁止（定数ファイルを使用）

# ディレクトリ構造

src/
app/ - Next.js App Router ページ
components/ - 再利用可能なコンポーネント
lib/ - ユーティリティ、ヘルパー関数
types/ - TypeScript型定義
hooks/ - カスタムReact フック

# ファイル別ルール

- /src/api/ 配下のファイル修正時: 必ずAPIドキュメントも更新
- /src/components/ 配下のファイル修正時: Storybookストーリーも更新
- データベーススキーマ変更時: マイグレーションファイルを自動生成

# 作業順序

1. まず関連コードを探索して理解する
2. 実装計画を説明する
3. 変更を実装する
4. テストを実行して確認する
5. 関連ドキュメントを更新する

# 会話中にCLAUDE.mdに追加
claude /add-memory "APIレスポンスは常にsnake_caseを使用します"

# 現在適用されているメモリの確認
claude /memory

# プロジェクト初期化時にCLAUDE.mdを自動生成
claude /init

> このプロジェクトの認証システム構造を分析してください

Claude Codeが行う作業:
- プロジェクトディレクトリ構造のスキャン
- auth関連ファイルの検索 (grep, glob)
- 依存関係の分析 (package.json, importの追跡)
- 設定ファイルの確認

> JWTトークン更新ロジックにリフレッシュトークンローテーションを追加したい

Claude Codeが行う作業:
- 現在のトークン更新ロジックの分析
- 変更が必要なファイル一覧の提示
- 実装計画の説明
- 予想される影響範囲の分析

> 変更を検証してください

Claude Codeが行う作業:
- npm test の実行
- リントチェック
- 型チェック
- ビルドの確認

# エラーログをパイプで渡す
cat error.log | claude "このエラーを分析して修正してください"

# Claude Codeのワークフロー:
# 1. エラーメッセージの分析
# 2. 関連ソースコードの検索
# 3. 原因の特定
# 4. 修正コードの作成
# 5. テスト実行で修正の確認

> ユーザープロフィールページにアクティビティ履歴タイムラインを追加してください。
> 過去30日間のアクティビティを時系列で表示し、
> 無限スクロールで以前のアクティビティをロードできるようにしてください。

Claude Codeの作業:
1. 既存のプロフィールページコードの分析
2. アクティビティデータAPIエンドポイントの確認/作成
3. タイムラインコンポーネントの実装
4. 無限スクロールロジックの実装
5. スタイリング
6. テストの作成と実行

# 現在の変更でコミットを作成
claude commit

# PRの作成
claude "現在のブランチの変更でPRを作成してください"

# コードレビュー
claude "PR #42の変更をレビューしてください"

# マージコンフリクトの解決
claude "現在のマージコンフリクトを解決してください"

メインエージェント（オーケストレーター）
├── サブエージェント 1: APIエンドポイント実装
├── サブエージェント 2: フロントエンドコンポーネント作成
├── サブエージェント 3: データベースマイグレーション
└── サブエージェント 4: テストコード作成

> プロジェクト全体でクラスコンポーネントを関数コンポーネントに変換してください

メインエージェントの作業:
1. クラスコンポーネントを使用する全ファイルの検索
2. ファイルをグループに分割
3. 各グループをサブエージェントに割り当て
4. サブエージェントが並列で変換を実行
5. 結果の統合とテスト

> このプロジェクトのセキュリティ脆弱性を分析してください

サブエージェント 1: 認証/認可コードの分析
サブエージェント 2: SQLインジェクションの可能性チェック
サブエージェント 3: XSS脆弱性のチェック
サブエージェント 4: 依存関係のセキュリティ監査

> ユーザー管理のCRUD APIを作成してください

サブエージェント 1: APIルートとコントローラーの生成
サブエージェント 2: データモデルとマイグレーションの生成
サブエージェント 3: 統合テストの作成
サブエージェント 4: APIドキュメントの生成

# バックグラウンドエージェントの開始
claude --background "テストカバレッジを80%以上に引き上げてください"

# バックグラウンドエージェントの状態確認
claude --list-backgrounds

# 結果の確認
claude --resume <session-id>

# ワークツリーを作成して独立した作業を実行
claude "ワークツリーを作成して、feature-authブランチで認証モジュールをリファクタリングしてください"

# メインブランチでは別の作業を継続
claude "バグ修正を続けてください"

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "command": "cp \"$CLAUDE_FILE_PATH\" \"$CLAUDE_FILE_PATH.bak\" 2>/dev/null || true"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      },
      {
        "matcher": "Write",
        "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\""
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "command": "terminal-notifier -message \"$CLAUDE_NOTIFICATION\" -title \"Claude Code\""
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "command": "npm test 2>&1 | tail -20"
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "if [[ \"$CLAUDE_FILE_PATH\" == *.ts ]]; then npx jest --findRelatedTests \"$CLAUDE_FILE_PATH\" --passWithNoTests; fi"
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" && npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "if echo \"$CLAUDE_COMMAND\" | grep -qE 'rm -rf|DROP TABLE|DELETE FROM'; then echo 'BLOCKED: 危険なコマンドが検出されました' && exit 1; fi"
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "echo \"$(date): $CLAUDE_FILE_PATH modified\" >> .claude/change.log"
      }
    ]
  }
}

# フック実行ログの確認
claude --verbose

# 特定フックの無効化
claude config set hooks.PostToolUse.enabled false

# フックをスキップ（一時的）
claude --no-hooks

import { AgentSDK } from '@anthropic-ai/claude-code-sdk'

const agent = new AgentSDK({
  model: 'claude-sonnet-4-20250514',
  permissions: {
    fileRead: true,
    fileWrite: true,
    commandExec: ['npm test', 'npm run lint'],
  },
})

import { AgentSDK } from '@anthropic-ai/claude-code-sdk'

async function createCodeReviewAgent() {
  const agent = new AgentSDK({
    model: 'claude-sonnet-4-20250514',
    systemPrompt: `あなたはシニアコードレビュアーです。
    以下の観点からコードをレビューします：
    1. セキュリティ脆弱性
    2. パフォーマンスの問題
    3. コーディング規約の遵守
    4. テストカバレッジ`,
    permissions: {
      fileRead: true,
      fileWrite: false,
      commandExec: ['git diff'],
    },
  })

  const session = await agent.createSession()
  const result = await session.send('現在のPRの変更をレビューしてください')

  console.log(result.response)
  console.log('検出された問題:', result.issues)
}

async function createDocAgent() {
  const agent = new AgentSDK({
    model: 'claude-sonnet-4-20250514',
    systemPrompt: `関数とモジュールのJSDoc/TSDocドキュメントを自動生成します。
    既存のドキュメントがあれば更新し、なければ新規作成します。`,
    permissions: {
      fileRead: true,
      fileWrite: true,
      commandExec: ['npm run build'],
    },
  })

  const session = await agent.createSession()
  await session.send('src/lib/ ディレクトリの全exportされた関数にドキュメントを追加してください')
}

async function createMigrationAgent() {
  const agent = new AgentSDK({
    model: 'claude-sonnet-4-20250514',
    systemPrompt: `Prismaマイグレーションを管理する専門エージェントです。
    スキーマ変更を分析し、安全なマイグレーションを生成します。`,
    permissions: {
      fileRead: true,
      fileWrite: true,
      commandExec: ['npx prisma migrate dev', 'npx prisma generate', 'npx prisma db push'],
    },
  })

  const session = await agent.createSession()
  await session.send(
    'UserモデルにprofileImageフィールドを追加するマイグレーションを作成してください'
  )
}

const session = await agent.createSession()

session.on('toolUse', (event) => {
  console.log(`ツール使用: ${event.tool} - ${event.description}`)
})

session.on('fileChange', (event) => {
  console.log(`ファイル変更: ${event.path} - ${event.type}`)
})

session.on('commandExec', (event) => {
  console.log(`コマンド実行: ${event.command}`)
  console.log(`結果: ${event.output}`)
})

session.on('error', (event) => {
  console.error(`エラー発生: ${event.message}`)
})

const agent = new AgentSDK({
  permissions: {
    // ファイルアクセス制御
    fileRead: true,
    fileWrite: true,
    fileGlob: ['src/**/*.ts', 'tests/**/*.ts'], // 許可パターン
    fileExclude: ['*.env', 'secrets/**'], // ブロックパターン

    // コマンド実行制御
    commandExec: ['npm test', 'npm run lint', 'npx prisma migrate dev'],

    // ネットワークアクセス制御
    networkAccess: false,

    // MCPサーバーアクセス
    mcpServers: ['filesystem', 'database'],
  },
})

Claude Code <--MCP--> データベースサーバー
Claude Code <--MCP--> GitHub API
Claude Code <--MCP--> Slack API
Claude Code <--MCP--> ファイルシステム
Claude Code <--MCP--> カスタムAPI

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_TOKEN": "xoxb-xxxxxxxxxxxx"
      }
    }
  }
}

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

const server = new McpServer({
  name: 'my-internal-api',
  version: '1.0.0',
})

// ツール定義
server.tool(
  'getDeployStatus',
  'デプロイステータスを取得',
  {
    environment: { type: 'string', enum: ['staging', 'production'] },
  },
  async (params) => {
    const status = await fetchDeployStatus(params.environment)
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(status, null, 2),
        },
      ],
    }
  }
)

server.tool(
  'triggerDeploy',
  'デプロイをトリガー',
  {
    environment: { type: 'string' },
    version: { type: 'string' },
  },
  async (params) => {
    const result = await triggerDeploy(params.environment, params.version)
    return {
      content: [
        {
          type: 'text',
          text: `デプロイがトリガーされました: ${result.id}`,
        },
      ],
    }
  }
)

// サーバー起動
const transport = new StdioServerTransport()
await server.connect(transport)

> usersテーブルのスキーマを確認して、新しいAPIエンドポイントを作成してください

Claude Codeの作業:
1. MCP postgresサーバーでスキーマを照会
2. 既存のAPIパターンを分析
3. 新しいエンドポイントのコードを生成
4. マイグレーションファイルを生成
5. テストを作成

> 最近オープンされたissueの中でbugラベルがあるものを確認し、
> 最も優先度の高いものを修正してください

Claude Codeの作業:
1. MCP githubサーバーでissue一覧を照会
2. 優先度を分析
3. 関連コードの探索と修正
4. PRの作成

# モノレポ環境で
claude "packages/shared ライブラリの変更が packages/web と packages/api に
与える影響を分析し、必要な更新をすべて実行してください"

# 複数の機能を同時に開発
claude "ワークツリーを作成して、以下のタスクを並列で実行してください:
1. feature/auth - 認証モジュールのリファクタリング
2. feature/dashboard - ダッシュボードのパフォーマンス最適化
3. fix/memory-leak - メモリリークの修正"

# 毎朝のコード品質レポート生成
claude schedule --cron "0 9 * * *" "コード品質レポートを生成してSlackで共有してください"

# 毎週月曜日の依存関係更新チェック
claude schedule --cron "0 10 * * 1" "npm outdatedを確認して安全なアップデートを適用してください"

# GitHub Actionsの例
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
        run: |
          npx @anthropic-ai/claude-code -p \
            "このPRの変更をレビューしてコメントを残してください" \
            --yes --output-format json
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

# .claudeignore の例
node_modules/
dist/
.next/
coverage/
*.lock
*.log

/help          # ヘルプ
/clear         # 会話のクリア
/compact       # 会話内容の圧縮
/memory        # メモリ（CLAUDE.md）の確認
/add-memory    # メモリにルールを追加
/model         # モデルの変更
/cost          # 現在のセッションコストの確認
/diff          # 現在の変更の確認
/undo          # 最後の変更を元に戻す
/review        # コードレビューのリクエスト
/init          # プロジェクトの初期化
/bug           # バグレポート
/config        # 設定の変更

# 会話中にメモリを追加
/add-memory "このプロジェクトでAPIレスポンスは常にcamelCaseを使用します"
/add-memory "テストファイルは__tests__ディレクトリに配置されています"
/add-memory "Prismaマイグレーション後は常にnpx prisma generateを実行します"

ログイン機能を作ってください

NextAuth.jsを使用してGoogle OAuthログイン機能を追加してください。
- /app/api/auth/[...nextauth]/route.ts に設定
- Google Providerを使用
- セッションにユーザーIDを含める
- ログイン/ログアウトボタンコンポーネントを作成
- 既存のNavbarコンポーネントに統合

# 詳細ログモード
claude --verbose

# ツール使用ログ
claude --debug-tools

# セッション履歴のエクスポート
claude --export-session ./session-log.json

# 特定のモデルに切り替えて比較
claude --model claude-opus-4-20250514

# 現在のセッションコストの確認
/cost

# エコノミーモード（Haikuを使用）
claude --model claude-haiku

# 自動コストアラートの設定
claude config set cost.alert-threshold 5.00