Claude Code 自動化（automation）実装ガイド｜Hooksのコード例と失敗しない自動化設計【2026】

Claude Codeは、ターミナルから複数ステップのタスクを自律的に完遂できるAIコーディングエージェントだ。公式ドキュメント（headless.md）が定義するAgent SDKを軸に、CLIフラグからCI/CDパイプラインまで一貫した自動化基盤を構築できる点が、コード補完系ツールとの本質的な違いである。本稿では、公式ドキュメントの一次情報に基づきながら、実装パターン・業務事例・コスト設計の観点から整理する（設計指針やセキュリティの体系は別記事にまとめている）。

設計指針・ベストプラクティスは ベストプラクティスにまとめています。本記事はAgent SDKによる自動化の実装に絞ります。

Claude Code 自動化とは何か――Agent SDKが変えるワークフローの構造

Claude Codeをプログラムから呼び出す仕組みは、Agent SDKとして公式に整備されている。Agent SDKは、インタラクティブなターミナルセッションを動かすのと同じツール群・エージェントループ・コンテキスト管理をそのまま提供し、CLI（claude -p）・Python・TypeScriptの3形態で利用できる。

エンジニアがClaude Code自動化を設計する際に把握すべき構造的特徴は、以下の3点に集約される。

• ツール呼び出し（Tool Use）：bash実行・ファイルI/O・外部ツール連携などを連鎖させてタスクを遂行する。単一のAPIコールではなく、複数ツールの動的な組み合わせが強みだ。
• リポジトリ全体のコンテキスト保持：会話セッションをまたいでコードベース全体を把握し、変更の一貫性を維持する。局所的なコード補完にとどまらない。
• 計画→実行→検証のフィードバックループ：タスクを自己分解し、各ステップの成否を評価しながら進む。失敗時の自律的なリカバリも設計に含まれる。

なお、公式ドキュメントによると、2026年6月15日以降、サブスクリプションプランでのAgent SDK・claude -p利用は、インタラクティブ利用とは別の月次Agent SDKクレジットから消費される。詳細はAnthropicサポート記事を参照されたい。

Claude Codeの導入手順についてはClaude Code インストールガイド、料金体系の全体像はClaude Code 料金・プランの解説を参照されたい。

Agent SDK CLIの基本的な使い方――-pフラグと主要オプション

公式ドキュメントによると、非インタラクティブモードで実行するには、claudeコマンドに-p（または--print）フラグとプロンプトを渡す。すべてのCLIオプションが-pと併用できる。

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

主なCLIオプションの組み合わせを以下に示す。

• --continue：直前の会話を引き継いで実行する。
• --allowedTools：指定したツールを自動承認し、パーミッションプロンプトなしに実行させる。
• --output-format：構造化出力（JSONなど）を取得する。

ベアモード（--bare）でCI起動を高速化する

公式ドキュメントが定義する--bareフラグを追加すると、フック・スキル・プラグイン・MCPサーバー・自動メモリ・CLAUDE.mdの自動探索をスキップして起動時間を短縮できる。ベアモードなしのclaude -pは、インタラクティブセッションと同様に作業ディレクトリや~/.claudeに設定されたコンテキストをすべて読み込む。

ベアモードはCIやスクリプトで「どのマシンでも同じ結果が得られる」ことが求められる場面に適している。チームメンバーの~/.claudeに置かれたフックや、プロジェクトの.mcp.jsonに記述されたMCPサーバーは実行されず、明示的に渡したフラグのみが有効になる。

claude --bare -p "Summarize this file" --allowedTools "Read"

このように--bareと--allowedToolsを組み合わせることで、パーミッションプロンプトなしにタスクを完了させられる（公式ドキュメント headless.md）。

構造化出力・Python・TypeScript SDKへの拡張

CLIの-pフラグはスクリプトやシェルベースのCI向けに最適化されている。構造化出力・ツール承認コールバック・ネイティブなメッセージオブジェクトが必要な場合は、Agent SDK全体のドキュメントに記載されたPythonパッケージおよびTypeScriptパッケージを使用する（Python SDK・TypeScript SDK）。

Claude Code 自動化の具体的な実装パターンと業務事例

自動化設計の核心は「どの業務をClaude Codeに委ねるか」の範囲設定だ。実装難易度と効果の観点から、4つのパターンに分類できる。

パターン1：コードレビュー・テスト生成の自動化

PRが作成されるたびにClaude CodeをGitHub Actionsから呼び出し、差分に対するレビューコメントの生成とユニットテストの追記を行う構成だ。Claude Code GitHub Actions公式ドキュメントによると、PRやIssueで@claudeとメンションするだけでClaude Codeが起動し、コードの分析・PR作成・機能実装・バグ修正を行える。

CLAUDE.mdに禁止パターン・命名規則・テストカバレッジ要件を記述しておくことで、プロジェクト固有のルールをエージェントに継承できる。差分のみをコンテキストに絞ることでトークンコストも抑制できる。

なお、PRごとに自動レビューを投稿するトリガー不要の仕組みについては、同公式ドキュメントが別途紹介するGitHub Code Review機能も参照されたい。

パターン2：ドキュメント・帳票の自動生成

会議録・週報・月次レポートのような定型ドキュメントを、構造化データ（CSV・JSON・DBクエリ結果）から生成するパターンだ。人間が行う場合のコピー＆ペーストミスや書式の揺れを排除できる。Claude Codeはデータの解釈・要約・判断を担い、最終的なフォーマット適用はテンプレートエンジン側で行う「テンプレートとロジックの分離」が出力の安定性を高める設計原則となる。

パターン3：CI/CDパイプラインへの組み込み

GitHub Actions公式ドキュメントによると、セットアップはターミナル上で/install-github-appコマンドを実行する方法が最も手軽だ。このコマンドがGitHubアプリの設定と必要なシークレットの登録を案内する。手動セットアップも提供されており、Amazon BedrockやGoogle Vertex AI経由での利用も対応している。

GitLab CI/CD向けの統合は現在ベータ版で提供されており、GitLabが管理するインテグレーションだ（サポート窓口はGitLabのIssueページ）。.gitlab-ci.ymlにジョブを1つ追加しマスクされたCI/CD変数を設定するだけで利用でき、Claude API・Amazon Bedrock・Google Vertex AIの3プロバイダーに対応している。イベント駆動のオーケストレーションにより、Issueコメントやレビュースレッドの@claudeメンションをトリガーにジョブが起動し、MR（マージリクエスト）として結果を返す。各インタラクションはコンテナ内でサンドボックス実行され、変更はすべてMRを経由するため、既存のレビュー・承認フローが維持される。

ビルド失敗時のエラーログをClaude Codeに渡して修正候補を自動生成し、プルリクエストとして提出する構成も典型的な実装だ。人間が承認するゲートを挟むことで、自動修正のリスクをコントロールしながら開発速度を向上させられる。

パターン4：データパイプラインのスクリプト生成・保守

スキーマ変更に追従するETLスクリプトの更新、Pythonデータ処理ロジックのリファクタリングなど、定期的に変更が発生するが構造は定型的なコードのメンテナンス自動化だ。スキーマ差分を検知してClaude Codeに渡し、更新スクリプトのドラフトを生成する構成が典型的な実装となる。

スラッシュコマンドを活用した操作効率化についてはClaude Code スラッシュコマンド活用ガイドに詳述している。また、Claude Code全体の概要把握にはClaude Codeとはも参照されたい。

実例：PreToolUse Hookで「ファイル編集前の自動バックアップ」と「危険コマンドの自動ブロック」を本番運用する

ここまでの実装パターンは公式ドキュメント（headless.md）ベースの一般的な整理でした。ここからは、当社が実際にClaude Code Hooksを使って2025年11月から本番で動かしている自動化の実コードを、読んだその場で流用できる形でそのまま公開します。抽象的な「パターン解説」ではなく、動くコードと設定ファイルです。

やっていること

Claude CodeにEdit / Writeツールでファイルを変更させる直前（PreToolUse）に、以下の2つを自動実行しています。

• 変更対象ファイルを .claude/backups/YYYY-MM-DD/ 配下にタイムスタンプ付きでコピーしてから編集を許可する（AIの誤編集を人力なしで復旧可能にする）
• git reset --hard ／ git clean -f ／ rm -rf / など、実行すると取り返しがつかないBashコマンドを正規表現で検出し、実行前にブロックする

設定ファイル（.claude/settings.json）

PreToolUse Hookはsettings.jsonで「どのツールの前に・何を実行するか」を宣言するだけで有効になります。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "node .claude/hooks/before-tool-hook.js" }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "node .claude/hooks/before-tool-hook.js" }
        ]
      }
    ]
  }
}

Hook本体（.claude/hooks/before-tool-hook.js）

可読性のために本番コードから内部システム連携部分を除いた最小構成です。バックアップの生成ロジック（保存先ディレクトリの命名規則・ファイル名のタイムスタンプ形式）と危険コマンドの検出ロジックは、実際に動いているものと同一です。

const fs = require('fs');
const path = require('path');

async function main() {
  const stdinData = await readStdin();               // Claude CodeがJSONで渡すツール実行情報
  const hookData = JSON.parse(stdinData || '{}');
  const toolName = hookData.tool_name || '';
  const params = hookData.tool_input || {};

  if ((toolName === 'Edit' || toolName === 'Write') && params.file_path) {
    backupIfExists(params.file_path);
  }
  if (toolName === 'Bash' && params.command) {
    blockDangerousCommand(params.command);
  }
}

function backupIfExists(filePath) {
  if (!fs.existsSync(filePath)) return;

  const now = new Date();
  const dateStr = now.toISOString().split('T')[0];                  // YYYY-MM-DD
  const timeStr = now.toTimeString().split(' ')[0].replace(/:/g, ''); // HHMMSS

  const backupDir = path.join(__dirname, '..', 'backups', dateStr);
  fs.mkdirSync(backupDir, { recursive: true });

  const { name, ext } = path.parse(filePath);
  const backupPath = path.join(backupDir, `${name}.backup-${timeStr}${ext}`);
  fs.copyFileSync(filePath, backupPath);

  console.log(`✅ auto backup: ${backupPath}`);
}

function blockDangerousCommand(command) {
  const rules = [
    { re: /git\s+reset\s+--hard/i, msg: 'git reset --hard is prohibited. use git revert instead' },
    { re: /git\s+clean\s+-f/i,     msg: 'git clean -f deletes untracked files' },
    { re: /rm\s+-rf\s+\//i,        msg: 'root directory deletion is absolutely prohibited' }
  ];
  for (const rule of rules) {
    if (rule.re.test(command)) {
      console.error(`BLOCKED: ${rule.msg}`);
      process.exit(1); // 終了コード1でツール実行そのものを止める
    }
  }
}

main().catch(() => process.exit(0)); // Hookのエラーで本来の作業まで止めない

ポイントはprocess.exit(1)です。PreToolUse Hookが0以外の終了コードを返すと、Claude Codeはそのツール呼び出し自体を実行せずに中断します。「警告を出す」で終わらせず「実行させない」まで踏み込めるのがHooksの実装上の要です。

CLAUDE.md：ルールは「失敗のたびに一つずつ追記する」運用ドキュメントにする

もう一つ、あまり紹介されない運用があります。自動化ルールを最初から完璧に設計するのではなく、実際に起きた事故・繰り返しミスを見つけるたびにCLAUDE.mdへ具体的なルールとして言語化して追記する、という運用です。当社の場合、最初は20項目程度だったプロジェクトルールが、実運用で発生した失敗（例：同じツール呼び出し構文の崩れを繰り返す、確認済みのはずのファイルを再び壊す）を一つずつ潰す過程で100項目以上まで積み上がっています。

Hooks側にも同種の仕組みがあります。上記のBashコマンドチェックとは別に、同じ危険操作を繰り返し試みた回数をカウントし、一定回数（当社の実装では5回）を超えると自動的に実行をブロックするロジックも組み込んでいます。「毎回AIに注意する」のではなく「繰り返したら機械的に止める」まで自動化するのが、Hooksを”実装ガイド通りに動かす”段階から一歩進めるポイントです。

主要AIコーディングツールとのポジショニング比較

Claude Code自動化の導入を検討する際、他のAIコーディング支援ツールとの役割分担を整理しておくことが設計の前提となる。以下の比較表は2026年6月時点の公開情報に基づく整理であり、各ツールの機能は急速に更新されているため、採用前に最新の公式ドキュメントを確認することを推奨する。

ツール	主な用途	自動化との親和性	エージェント機能	CI/CD統合	主な限界
Claude Code	自律エージェント・複雑タスク実行	高（ファイルI/O・bash実行・計画立案）	Agent SDKでネイティブ対応	GitHub Actions・GitLab CI/CD公式対応	長文コンテキストでトークンコスト増大
GitHub Copilot	IDE内コード補完・Chat	中（Workspace機能で拡張中）	限定的	一部対応	エディタ外の自律実行は不得意
Cursor	IDE統合・インライン編集	中（Composer Agentで拡張）	エディタ内に限定	非ネイティブ	CI/CDへの組み込みは自前実装が必要
OpenAI Codex（API）	コード生成API・カスタム統合	高（API経由のカスタム構築向け）	API経由で構築可能	自前実装が必要	エージェント基盤は自前設計が前提

※各ツールの仕様は2026年6月時点の公開情報に基づく。Claude CodeとCursorの詳細比較はClaude Code vs Cursor 比較記事を、Codexとの比較はClaude Code vs Codex 比較記事を参照。

Claude Codeが他ツールと明確に差別化されるのは、ターミナルからリポジトリ全体を対象に、マルチステップタスクを自律的に完遂できる点だ。公式ドキュメントが示す通り、GitHub ActionsとGitLab CI/CDへのネイティブ統合がすでに整備されており、CI/CDへの組み込み工数が他ツールと比較して小さい点が実務上の優位性となる。一方で、IDEとの深い統合が必要な場面ではCursorが優位であり、チームのワークフローに応じた使い分けが現実的な判断となる。

コスト設計と運用上のトレードオフ――定量的判断のための視点

Claude Code自動化の導入判断において、コストと効果のトレードオフを整理することは欠かせない。API料金の詳細についてはClaude Code API料金の解説を参照されたいが、自動化設計の観点から把握すべき論点を以下に整理する。

トークンコストの管理

エージェントが長いコンテキストを保持しながら複数のツール呼び出しを行う場合、単純なチャット利用と比較してトークン消費量が大きくなる。公式ドキュメントが示す--bareフラグの活用に加え、大規模リポジトリを対象とした自動化では必要なファイルのみを渡す設計がランニングコストを抑える実効的な手段だ。

サブスクリプションとAPI利用のクレジット分離

公式ドキュメントが明記する通り、2026年6月15日以降、サブスクリプションプランでのAgent SDK・claude -p利用はインタラクティブ利用とは別の月次クレジットから消費される。自動化の規模が大きくなる場合は、消費クレジットの計測と予算設計を別途検討する必要がある。

冪等性とエラーハンドリング

自動化パイプラインが失敗した際の再試行は追加のAPIコールを意味する。冪等性（同じ操作を複数回実行しても結果が変わらない性質）を担保した設計と、失敗時の早期終了条件の明示が、コストと安定性の両面で重要だ。特に外部APIを呼び出すタスクでは、部分的な成功状態からの安全な再開設計を事前に検討しておく必要がある。

モデル選択のトレードオフ

GitHub Actions公式ドキュメントによると、デフォルトモデルはSonnetだが、modelパラメータを設定することでClaude Opus 4.8等の別モデルを指定できる。高精度が要求されるタスクと比較的単純なタスクでモデルを使い分けることが、コスト最適化の選択肢として存在する。

自動化の限界と人間が担うべき領域

Claude Code自動化の範囲は着実に拡大しているが、設計意図が曖昧な要件定義・ビジネスロジックのドメイン固有の判断・セキュリティ責任の最終的な帰属・法的リスクを伴う意思決定は、依然として人間が担うべき領域だ。「AIに任せる範囲」と「人間が判断する範囲」の境界を明文化し、CLAUDE.mdやRunbookに記録することが安定した運用の基盤となる。

自動化を安全に育てるための勘所（一次情報）

監修者・河合継はClaude Codeを3.5の時代から1年以上、実務で運用してきた。自動化は強力だが、いきなり大きく組むと制御を失う。段階的に育てた経験を補足する。

• 小さく始めて、手動で確かめてから自動に回す。最初から無人で大きな処理を任せると、こけたときの被害も大きい。まず手元で一連の流れを確かめ、安定してから自動化に載せると安心だった。
• 止め時を機械的に決めておく。自走させる処理ほど、失敗が続いたら止める条件を先に入れておく。これがないと、解けない問題に延々とコストを溶かすことになる。
• 「何が起きたか」を後から追える形にする。自動で動くぶん、結果が見えにくい。ログや出力を残して、後から実際に何をしたか確認できるようにしておくと、安心して任せられた。

段階的導入ロードマップと継続的な設計見直し

Claude Code自動化を実務に導入する際の推奨アプローチは、リスクの低い領域から始めて段階的に範囲を広げることだ。ドキュメント生成・データ照合といった「失敗してもやり直せる」タスクを最初の対象とすることで、組織内の信頼と運用ノウハウを同時に蓄積できる。

• フェーズ1（導入・検証）：ドキュメント生成・テスト追記など、本番への影響が限定的なタスクで実装する。CLAUDE.mdとログ基盤を整備し、--bareと--allowedToolsによる権限制御を確立する。
• フェーズ2（統合）：GitHub ActionsまたはGitLab CI/CDパイプラインへの組み込みを行う。Human-in-the-loopの承認フロー（PR/MRレビュー）を確立し、コスト計測の仕組みを導入する。
• フェーズ3（拡張）：スキーマ追従・複数リポジトリ横断タスクなど、より複雑な自動化へ展開する。プラグイン依存のバージョン制約（plugin-dependencies.md参照）を整備し、定期的なリスク評価を組織プロセスに組み込む。

技術的な実装と組織的なガバナンス設計を並走させることが、長期的に安定した自動化運用の条件となる。Claude Codeの概要・入門的な活用法についてはClaude Code 使い方ガイドも参照されたい。

なお、弊社（クリスタルメソッド）が開発するDeepAIは、実在の人物の容姿・表情・声・振る舞いをデジタル空間で再現するバーチャルヒューマン／AIアバターソリューションであり、Claude Codeとは異なる領域の製品だ。リップシンク・表情生成・音声合成・対話AIなどを組み合わせ、自動化パイプラインの構築で得られる「スコープの厳密な定義」と「段階的な検証プロセス」の重要性はDeepAIの開発・運用においても共通する知見となっている。接客・研修・面接練習・広報等への活用を検討されている場合は、弊社DeepAIもぜひご覧いただきたい。

まとめ

Claude Code自動化の中核は、Agent SDKが提供するclaude -pフラグによる非インタラクティブ実行だ。--bareでCI起動を安定化し、--allowedToolsで権限を最小化し、CLAUDE.mdでプロジェクト固有のルールをエージェントに継承するという3点が、堅牢な自動化パイプラインの基本構成となる。GitHub ActionsとGitLab CI/CDへのネイティブ統合が整備されており、/install-github-appコマンドによる簡易セットアップから始められる点も実務導入のハードルを下げている。設計段階でHuman-in-the-loopの承認ゲートとシークレット管理の分離を織り込み、段階的に自動化の範囲を広げることが、リスクと効果のバランスをとる現実的なアプローチだ。

---

参考文献

• Anthropic「Run Claude Code programmatically（headless.md）」https://code.claude.com/docs/en/headless.md
• Anthropic「Claude Code GitHub Actions」https://code.claude.com/docs/en/github-actions.md
• Anthropic「Claude Code GitLab CI/CD」https://code.claude.com/docs/en/gitlab-ci-cd.md
• Anthropic「Constrain plugin dependency versions（plugin-dependencies.md）」https://code.claude.com/docs/en/plugin-dependencies.md
• Anthropic「Agent SDK overview」https://code.claude.com/docs/en/agent-sdk/overview
• Anthropic「Use the Claude Agent SDK with your Claude plan」https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan
• GitLab「Claude Code GitLab integration issue」https://gitlab.com/gitlab-org/gitlab/-/issues/573776

関連記事

• Claude Codeとは
• Claude Codeでできること・活用事例
• Claude CodeとGitHub/Gitの連携
• Claude Code Skillsとは？作り方と一覧
• Claude Codeのベストプラクティス