Blog

CI/CDワークフローのためのClaude Code活用ガイド

Ashley Goolam

Ashley Goolam

21 1月 2026

CI/CDワークフローのためのClaude Code活用ガイド

すべてのデプロイメントパイプラインには、チェンジログの検証、APIの破壊的変更の確認、リリースノートの生成、複数のサービスにわたるロールバックの調整など、反復的なタスクが含まれています。Claude Codeは、これらの手動のチェックポイントを、CI/CD環境で直接実行される自動化されたインテリジェントなガードレールに変換します。脆弱なbashスクリプトを書く代わりに、コードベース、APIコントラクト、デプロイメント履歴を理解する推論エージェントが得られます。

なぜClaude CodeはCI/CDパイプラインに不可欠なのか？

従来のCI/CDスクリプトは決定的ですが、賢くありません。バージョンアップのためにgrepを実行し、変更検出のためにgit diffを実行し、API検証のために静的な正規表現を使用します。チームがモノレポをリファクタリングしたり、新しいマイクロサービスを導入したりすると、これらのスクリプトはサイレントに破損します。Claude Codeはセマンティックな理解をもたらします。破壊的変更が何であるかを知っており、インポートパスからサービス依存関係を推測し、状況に応じたデプロイメント計画を生成できます。

統合パターンは簡単です。Claude Codeをパイプラインのコンテナ化されたステップとして実行し、環境変数を通じてコンテキストを与え、検証、生成、または調整するスキルを実行させます。エージェントは、後続のCIステップが操作できる構造化されたJSONを返します。これにより、ビルドを失敗させたり、カナリアデプロイメントをトリガーしたり、Slackに警告を投稿したりできます。

💡
美しいAPIドキュメントを生成する優れたAPIテストツールをお探しですか？

開発チームが最大限の生産性で協業できる、統合されたオールインワンのプラットフォームをお探しですか？

Apidogは、お客様のすべての要求に応え、Postmanをはるかに手頃な価格で置き換えます！
button

CI/CD環境でのClaude Codeのセットアップ

コンテナ構成

最小限のオーバーヘッドでClaude CodeをDockerコンテナで実行します。

# Dockerfile.claude-cicd
FROM node:20-alpine

# Claude Code CLIをインストール
RUN npm install -g @anthropic-ai/claude-code

# 作業ディレクトリを設定
WORKDIR /workspace

# プロジェクトファイルをコピー
COPY . .

# 非インタラクティブモード用の環境変数を設定
ENV ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY}"
ENV CLAUDE_CODE_CI_MODE=true
ENV CLAUDE_CODE_QUIET=true

# デフォルトコマンドでスキルを実行
ENTRYPOINT ["claude"]

ローカルでビルドしてテストします。

docker build -f Dockerfile.claude-cicd -t claude-cicd .
docker run -e ANTHROPIC_API_KEY=sk-ant-... claude-cicd --help
docker desktop

GitHub Actions統合

特定の検証タスクのためにClaude Codeを呼び出す再利用可能なワークフローを作成します。

# .github/workflows/claude-validation.yml
name: Claude Code Validation

on:
  workflow_call:
    inputs:
      skill_name:
        required: true
        type: string
      parameters:
        required: false
        type: string
        default: '{}'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 変更分析のための全履歴

      - name: Run Claude Code Skill
        uses: docker://claude-cicd:latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          args: |
            --skill "${{ inputs.skill_name }}" \
            --params '${{ inputs.parameters }}' \
            --output /workspace/claude-output.json

      - name: Parse Claude Output
        id: parse
        run: |
          echo "claude_result=$(cat /workspace/claude-output.json)" >> $GITHUB_OUTPUT

      - name: Fail on Breaking Changes
        if: fromJson(steps.parse.outputs.claude_result).hasBreakingChanges
        run: |
          echo "破壊的変更が検出されました: ${{ fromJson(steps.parse.outputs.claude_result).details }}"
          exit 1

このワークフローをメインのCIパイプラインから呼び出します。

# .github/workflows/ci.yml
jobs:
  check-breaking-changes:
    uses: ./.github/workflows/claude-validation.yml
    with:
      skill_name: "api-breaking-change-detector"
      parameters: '{"baseBranch": "main", "changedFiles": "${{ needs.changes.outputs.changed_files }}"}'

GitLab CI統合

GitLabの scriptブロックにより、Claude Codeの呼び出しが簡単になります。

# .gitlab-ci.yml
stages:
  - validate
  - test
  - deploy

claude:validate:api:
  stage: validate
  image: claude-cicd:latest
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
  script:
    - claude --skill api-breaking-change-detector 
      --params "{\"baseBranch\": \"$CI_DEFAULT_BRANCH\", \"changedFiles\": \"$CI_COMMIT_CHANGED_FILES\"}"
      --output claude-output.json
    - |
      if jq -e '.hasBreakingChanges' claude-output.json > /dev/null; then
        echo "APIの破壊的変更が検出されました: $(jq -r '.details' claude-output.json)"
        exit 1
      fi
  artifacts:
    reports:
      dotenv: claude-output.env
    paths:
      - claude-output.json

artifactsセクションは、後続のジョブのためにClaudeの出力をキャプチャし、条件付きデプロイメントロジックを可能にします。

gitlab

CI/CD固有のClaude Codeスキルの構築

パイプラインタスクのスキル構造

CI/CDスキルには、3つのコンポーネントが必要です。

  1. 変更検出: git diff、コミットメッセージ、またはマージリクエストの差分を分析します。
  2. 検証ロジック: ビジネスルール（APIバージョン管理、テストカバレッジ、セキュリティスキャン）を適用します。
  3. アクション生成: パイプラインコマンドまたは失敗理由を生成します。

スキル定義を作成します。

mkdir -p ~/claude-skills/api-breaking-change-detector
cd ~/claude-skills/api-breaking-change-detector

SKILL.md定義

---
name: api-breaking-change-detector
description: OpenAPIスペックとTypeScript型における破壊的API変更を検出します
version: 1.0.0
author: CI/CD Team
mcp:
  transport: stdio
tools:
  detect-openapi-changes:
    description: 2つのOpenAPIスペックを比較し、破壊的変更を特定します
    parameters:
      baseSpec:
        type: string
        description: ベースとなるOpenAPI YAML/JSONファイルへのパス
        required: true
      headSpec:
        type: string
        description: ヘッダーとなるOpenAPI YAML/JSONファイルへのパス
        required: true
      strictMode:
        type: boolean
        description: オプションから必須への変更を破壊的として扱います
        default: true
  detect-typescript-changes:
    description: TypeScriptインターフェースの破壊的変更を比較します
    parameters:
      baseFiles:
        type: array
        items: { type: string }
        description: ベースとなるTypeScriptファイルのグロブパターン
        required: true
      headFiles:
        type: array
        items: { type: string }
        description: ヘッダーとなるTypeScriptファイルのグロブパターン
        required: true
---

# API破壊的変更検出スキル

このスキルは、APIコントラクトと型定義を分析し、コンシューマを破壊する可能性のある変更を特定します。

## 使用例

### OpenAPI比較
```bash
# CIパイプラインで
claude --skill api-breaking-change-detector 
  --tool detect-openapi-changes 
  --params '{"baseSpec": "openapi/base.yaml", "headSpec": "openapi/head.yaml"}'

TypeScript比較

claude --skill api-breaking-change-detector 
  --tool detect-typescript-changes 
  --params '{"baseFiles": ["src/types/v1/*.ts"], "headFiles": ["src/types/v2/*.ts"]}'

戻り値のフォーマット

{
  "hasBreakingChanges": true,
  "details": [
    {
      "type": "field_removed",
      "location": "User.email",
      "severity": "breaking"
    }
  ],
  "recommendations": [
    "フィールドの削除を元に戻すか、@deprecatedマーカーを追加する"
  ]
}

実装ロジック

index.tsを作成します。

import { z } from 'zod';
import { parseOpenAPI } from './openapi-parser';
import { parseTypeScript } from './typescript-parser';
import { diffSchemas } from './diff-engine';

const OpenAPIParams = z.object({
  baseSpec: z.string(),
  headSpec: z.string(),
  strictMode: z.boolean().default(true)
});

const TypeScriptParams = z.object({
  baseFiles: z.array(z.string()),
  headFiles: z.array(z.string())
});

export const tools = {
  'detect-openapi-changes': async (params: unknown) => {
    const { baseSpec, headSpec, strictMode } = OpenAPIParams.parse(params);
    
    const base = await parseOpenAPI(baseSpec);
    const head = await parseOpenAPI(headSpec);
    const changes = diffSchemas(base, head, { strict: strictMode });
    
    return {
      hasBreakingChanges: changes.breaking.length > 0,
      details: changes.breaking,
      recommendations: generateRecommendations(changes)
    };
  },
  
  'detect-typescript-changes': async (params: unknown) => {
    const { baseFiles, headFiles } = TypeScriptParams.parse(params);
    
    const base = await parseTypeScript(baseFiles);
    const head = await parseTypeScript(headFiles);
    const changes = diffSchemas(base, head);
    
    return {
      hasBreakingChanges: changes.breaking.length > 0,
      details: changes.breaking,
      recommendations: generateRecommendations(changes)
    };
  }
};

function generateRecommendations(changes: any) {
  return changes.breaking.map((change: any) => {
    switch (change.type) {
      case 'field_removed':
        return `フィールド ${change.location} が削除されました。まず@deprecatedマーカーを追加し、次のメジャーバージョンで削除してください。`;
      case 'type_changed':
        return `フィールド ${change.location} の型が変更されました。新しい型で新しいフィールドを追加することを検討してください。`;
      default:
        return `変更を確認してください: ${JSON.stringify(change)}`;
    }
  });
}

重要な洞察：Claude Codeはテキストを返すだけでなく、CIシステムが解析して操作できる構造化されたデータを返します。

Claude Codeによる実用的なCI/CDワークフロー

ワークフロー1：インテリジェントなテストランナー

すべてのコミットですべてのテストを実行する代わりに、変更されたファイルによって影響を受けるテストのみを実行します。

# .github/workflows/intelligent-tests.yml
jobs:
  determine-tests:
    runs-on: ubuntu-latest
    outputs:
      test-matrix: ${{ steps.claude.outputs.matrix }}
    steps:
      - uses: actions/checkout@v4
      - id: claude
        run: |
          CHANGED_FILES=$(git diff --name-only HEAD~1)
          echo "changed_files=$CHANGED_FILES" >> $GITHUB_OUTPUT
          
          MATRIX=$(claude --skill test-selector \
            --params "{\"changedFiles\": \"$CHANGED_FILES\", \"testPattern\": \"**/*.test.ts\"}" \
            --output - | jq -c '.testMatrix')
          
          echo "matrix=$MATRIX" >> $GITHUB_OUTPUT

  run-tests:
    needs: determine-tests
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJson(needs.determine-tests.outputs.test-matrix) }}
    steps:
      - uses: actions/checkout@v4
      - run: npm test ${{ matrix.testFile }}

test-selectorスキルは、静的分析を使用してインポートをマッピングし、変更されたコードをカバーするテストを決定します。

ワークフロー2：自動化されたリリースノート生成

標準のコミットメッセージベースのチェンジログではコンテキストが不足します。Claude CodeはPRの説明、コード変更、問題参照を分析します。

# .github/workflows/release.yml
jobs:
  generate-notes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: リリースノートを生成
        run: |
          claude --skill release-notes-generator \
            --params "{\"fromTag\": \"${{ github.event.inputs.fromTag }}\", \"toTag\": \"${{ github.event.inputs.toTag }}\"}" \
            --output release-notes.md
      
      - name: GitHubリリースを作成
        uses: softprops/action-gh-release@v1
        with:
          body_path: release-notes.md
          tag_name: ${{ github.event.inputs.toTag }}

このスキルは、コミットメッセージ、差分、リンクされた問題を読み取り、移行ガイドを含む記述的なリリースノートを生成します。

ワークフロー3：セキュリティスキャンオーケストレーション

複数のセキュリティツールを実行し、Claude Codeに検出結果をトリアージさせます。

# .gitlab-ci.yml
security-scan:
  stage: validate
  script:
    - trivy image --format json $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA > trivy.json
    - sonar-scanner -Dsonar.analysis.mode=preview > sonar.json
    - claude --skill security-triage \
        --params "{\"trivyReport\": \"trivy.json\", \"sonarReport\": \"sonar.json\"}" \
        --output triage-result.json
    - |
      if jq -e '.criticalIssues > 0' triage-result.json; then
        echo "重大なセキュリティ問題が検出されました"
        exit 1
      fi
  artifacts:
    reports:
      security: triage-result.json

Claude Codeは、検出結果を関連付け、重複を排除し、悪用可能性によって優先順位を付け、ノイズを80%削減します。

ワークフロー4：カナリアデプロイメント調整

複数のサービスにわたるカナリアリリースを調整します。

// skills/canary-deployment/index.ts
export const tools = {
  'plan-canary': async (params: unknown) => {
    const { services, trafficSplit } = params;
    
    // 現在の状況についてサービスメッシュに問い合わせる
    const meshState = await $fetch('http://mesh-api.internal/state');
    
    // デプロイメントシーケンスを生成
    const plan = services.map(service => ({
      service,
      traffic: meshState[service].traffic * trafficSplit,
      healthChecks: [
        `/health/${service}`,
        `/metrics/${service}/error-rate`
      ],
      rollbackThreshold: 0.05 // 5%のエラー率でロールバックをトリガー
    }));
    
    return { plan, estimatedDuration: `${services.length * 5} minutes` };
  },
  
  'execute-canary': async (params: unknown) => {
    const { plan } = params;
    
    for (const step of plan) {
      await $fetch(`http://mesh-api.internal/traffic/${step.service}`, {
        method: 'POST',
        body: { traffic: step.traffic }
      });
      
      // ヘルスチェックを待機
      const healthy = await waitForHealth(step.healthChecks, 30);
      if (!healthy) {
        throw new Error(`サービス ${step.service} がヘルスチェックに失敗しました`);
      }
    }
    
    return { success: true, servicesUpdated: plan.length };
  }
};

CIパイプラインはplan-canaryを呼び出し、計画を確認した後、手動承認ゲートとともにexecute-canaryを呼び出します。

シークレットと権限の管理

シークレット管理

APIキーをスキルコードにハードコードしないでください。CIシステムのシークレットを使用します。

# GitHub Actions
- name: シークレットを使用してClaudeを実行
  run: claude --skill deploy-skill
  env:
    DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
    DATABASE_URL: ${{ secrets.DATABASE_URL }}

# スキル内
const deployToken = process.env.DEPLOY_TOKEN;
if (!deployToken) throw new Error('DEPLOY_TOKENが設定されていません');

最小権限

最小限の権限でClaude Codeを実行します。GitLabの場合：

# .gitlab-ci.yml
claude-job:
  script: ...
  before_script:
    - export ANTHROPIC_API_KEY=${CI_JOB_TOKEN_LIMITED}
  variables:
    GIT_STRATEGY: fetch  # プッシュアクセスなし
    CLAUDE_CODE_READONLY: true

これにより、Claudeが誤ってコミットをプッシュしたり、ブランチを削除したりするのを防ぎます。

モニタリングと可観測性

Claude Codeの決定をログに記録する

監査証跡のために推論をキャプチャします。

// スキル実装内
export const tools = {
  'deploy-service': async (params) => {
    const reasoning = [];
    
    reasoning.push(`コミット ${params.commitHash} を分析中`);
    const risk = await assessRisk(params.commitHash);
    reasoning.push(`リスクレベル: ${risk.level}`);
    
    if (risk.level === 'high') {
      reasoning.push('デプロイメントがブロックされました: 高リスクが検出されました');
      return { approved: false, reasoning };
    }
    
    reasoning.push('デプロイメントが承認されました: すべてのチェックが合格しました');
    return { approved: true, reasoning };
  }
};

ログを可観測性プラットフォームに保存します。

# Loki/Elasticsearchにログを記録
- run: |
    claude --skill deploy-service ... | \
    jq -c '{level: "info", message: "Claude decision", data: .}' | \
    promtail --client.url=http://loki:3100/loki/api/v1/push

追跡するメトリック

CI/CD統合のトラブルシューティング

問題：Claude Codeがハングする

原因: 対話型プロンプトを待機している。
修正: --quietと--non-interactiveフラグを使用する。

claude --quiet --non-interactive --skill your-skill --params '{}'

問題：MCPサーバーがコンテナで起動に失敗する

原因: 依存関係の欠如または間違ったNodeバージョン。
修正: 専用のイメージをビルドする。

FROM node:20-alpine
WORKDIR /skill
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
CMD ["node", "dist/server.js"]

問題：Anthropicによるレート制限

原因: 並行ジョブでAPI呼び出しが多すぎる。
修正: リクエストキューを実装する。

import PQueue from 'p-queue';
const queue = new PQueue({ concurrency: 1 });

export const tools = {
  'safe-api-call': async (params) => {
    return queue.add(async () => {
      return await callAnthropicAPI(params);
    });
  }
};

問題：スキルが見つからない

原因: MCP設定内の相対パス。
修正: 絶対パスを使用し、CIでスキルリポジトリをチェックアウトする。

- uses: actions/checkout@v4
  with:
    repository: your-org/claude-skills
    path: .claude-skills

- run: |
    echo "{
      \"mcpServers\": {
        \"api-validator\": {
          \"command\": \"node\",
          \"args\": [\"$PWD/.claude-skills/api-validator/dist/index.js\"]
        }
      }
    }" > ~/.config/claude-code/config.json

結論

CI/CDパイプラインにおけるClaude Codeは、自動化を厳格なスクリプトから、コードベース、アーキテクチャ、ビジネスルールを理解するインテリジェントエージェントへと移行させます。Claudeをコンテナ化し、専門的なスキルを定義し、GitHub ActionsまたはGitLab CIと統合することで、リファクタリングに適応し、微妙な破壊的変更を検出し、実用的な洞察を生成するパイプラインを作成できます。まず1つのスキル（API破壊的変更検出など）から始め、チームが自動化を信頼するにつれて拡張してください。スキル開発への初期投資は、手動レビュー時間の短縮と本番環境でのインシデントの減少という形で報われます。

スキルが内部APIと対話する場合、Apidogでそれらのコントラクトを検証し、AI駆動のパイプラインが不安定さの原因にならないようにしてください。

button

ApidogでAPIデザイン中心のアプローチを取る

APIの開発と利用をよりシンプルなことにする方法を発見できる

無料会員登録ダウンロード