本番パターン
可観測性、モニタリング、本番利用のためのデプロイパターン。
学ぶこと
これまで Claude Code を個人ツールとして使ってきました --- ターミナルの前にいる1人の開発者です。しかし Claude Code は、CI/CDパイプラインでヘッドレスに実行したり、チーム全体にサービスを提供したり、自動化ワークフローの一部として動作することもできます。本番環境への移行には、あらゆる本番システムと同じ厳密さが求められます：モニタリング、テスト、エラーハンドリング、コスト管理です。
この最終セッションを終えると、以下を理解できるようになります：
- 非インタラクティブな自動化のためのヘッドレスモード
- GitHub Actions との CI/CD 統合
- 可観測性：ロギング、メトリクス、アラート
- コスト追跡と予算管理
- エージェントワークフローのテスト
- AIアシスト開発をスケーリングするための成熟度モデル
課題
ラップトップで動くツールと、本番環境で確実に動作するツールは同じではありません：
Development: Production:
One user Many users/triggers
Interactive terminal Headless, no UI
Errors → you see them Errors → silent failure
Cost → your API bill Cost → team/org budget
Testing → "it worked for me" Testing → automated validationすべてのギャップが潜在的な障害ポイントです。
仕組み
ヘッドレスモード
Claude Code は -p フラグと構造化出力を使用して、ターミナルUIなしで実行できます：
# One-shot mode with JSON output
claude -p "Summarize changes in the last 3 commits" --output-format json
# Pipe input for processing
cat requirements.txt | claude -p "Check for outdated dependencies"--output-format json フラグは自動化において重要です。ターミナル出力の代わりに、パース可能なJSONが得られます：
{
"result": "Found 2 issues: ...",
"cost_usd": 0.023,
"duration_ms": 4500,
"model": "claude-sonnet-4-20250514",
"session_id": "sess_abc123"
}CI/CD 統合
最も一般的な本番パターン：GitHub Actions での Claude Code。
# .github/workflows/ai-review.yml
name: AI Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run AI Review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
npm install -g @anthropic-ai/claude-code
DIFF=$(git diff origin/main...HEAD)
echo "$DIFF" | claude -p \
"Review this diff for bugs and security issues." \
--output-format json --max-turns 20 \
> review.json 2>&1 || true
- name: Post Review Comment
if: always()
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
let review;
try {
review = JSON.parse(fs.readFileSync('review.json', 'utf8'));
} catch (e) {
review = { result: 'Review failed: ' + e.message };
}
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body: `## AI Code Review\n\n${review.result || 'No output'}\n\n---\nCost: \`$${review.cost_usd || '?'}\``
});本番環境における重要な詳細：timeout-minutes は暴走セッションを防ぎ、--max-turns はエージェントの反復回数を制限し、|| true はステップの失敗を防ぎ、if: always() はエラー時でも結果を投稿します。
可観測性
┌──────────────────────────────────────────────────────┐
│ Layer 1: Logging │
│ What prompt, what tools called, what output, errors │
│ │
│ Layer 2: Metrics │
│ Tokens per session, cost per project, duration, │
│ tool call counts, error rates │
│ │
│ Layer 3: Alerting │
│ Cost exceeds threshold, error rate spikes, │
│ agent stuck in loop, unexpected tool calls │
└──────────────────────────────────────────────────────┘シンプルなコスト追跡ラッパー：
#!/bin/bash
# track-cost.sh - Log Claude Code costs per project
PROJECT="$1"; PROMPT="$2"
OUTPUT=$(claude -p "$PROMPT" --output-format json 2>/dev/null)
COST=$(echo "$OUTPUT" | jq -r '.cost_usd // 0')
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
echo "$TIMESTAMP,$PROJECT,$COST" >> ~/.claude/cost-log.csv
echo "$OUTPUT" | jq -r '.result'コストモニタリング
┌──────────────────────────────────────────────────────┐
│ Layer 1: Per-session limits │
│ claude --max-tokens 50000 │
│ │
│ Layer 2: Model selection │
│ Haiku ~$0.001/call │ Sonnet ~$0.01 │ Opus ~$0.05 │
│ │
│ Layer 3: Budget dashboards │
│ Track cost per project, per developer, over time │
│ │
│ Layer 4: Alerts │
│ "Project X spent $50 today (limit: $20)" │
└──────────────────────────────────────────────────────┘エージェントワークフローのテスト
エージェントワークフローには3つのレベルのテストが必要です：
ユニットテスト：スキルとエージェントファイルが存在し、正しい形式であることを検証。
for skill_dir in .claude/skills/*/; do
[ ! -f "$skill_dir/SKILL.md" ] && echo "FAIL: Missing $skill_dir/SKILL.md" && exit 1
done
echo "PASS: All skill files present"統合テスト：既知のプロンプトで Claude Code を実行し、期待される動作を検証。
OUTPUT=$(claude -p "/review" --output-format json 2>/dev/null)
echo "$OUTPUT" | jq -r '.result' | grep -q "Security" && echo "PASS" || echo "FAIL"エンドツーエンドテスト：テスト環境で完全なワークフローを実行し、結果を検証。
成熟度モデル
┌──────────────────────────────────────────────────────┐
│ Stage 1: Ad-hoc Usage │
│ Individual devs use Claude Code, no shared config │
│ → Personal productivity boost │
│ │
│ Stage 2: Personal Automation │
│ Custom CLAUDE.md, personal skills, allowlists │
│ → Consistent personal workflows │
│ │
│ Stage 3: Team Standardization │
│ Shared CLAUDE.md in repo, team skills, CI/CD │
│ → Team-wide consistency and quality │
│ │
│ Stage 4: Platform Integration │
│ All pipelines, custom MCP servers, dashboards │
│ → Organizational capability │
└──────────────────────────────────────────────────────┘ほとんどのチームはステージ1-2にいます。ステージ3が乗数効果が発揮される段階です --- 共有された知識により、すべてのチームメンバーが最良のワークフローの恩恵を受けます。
重要なポイント
本番 Claude Code は信頼性と予測可能性がすべてです。 ソフトウェアを本番対応にする原則と同じものが、AIエージェントシステムに直接適用されます。
95%の確率で動作するエージェントは本番対応ではありません。本番対応とは：失敗を検知でき（モニタリング）、原因を把握でき（ロギング）、コストを把握でき（予算管理）、一貫した動作を確認でき（テスト）、予期しない動作をしないこと（パーミッション）を意味します。
ツールは特別なものではありません --- ログ、メトリクス、アラート、テスト、CI/CD。唯一の違いは、「サービス」がWebサーバーではなくAIエージェントであることです。
ハンズオン
すべてを組み合わせて、最初のCI/CD統合のための本番チェックリストを作成します：
1. Create .claude/skills/review/SKILL.md (review workflow)
2. Create .claude/agents/security-reviewer.md (security checks)
3. Add .github/workflows/ai-review.yml (CI/CD above)
4. Set ANTHROPIC_API_KEY in repo secrets
5. Open a PR → AI review posts automatically
6. Track cost-log.csv weekly → set budget alerts
7. Review allowlists monthly → expand as trust builds1つのパイプラインから始めましょう。品質とコストを測定します。自信が付いたら、より多くのワークフローに拡大します。これは成熟度モデルのステージ2からステージ3への移行 --- 個人ツールからチームインフラへの変革です。
変更点まとめ
| 開発用途 | 本番用途 |
|---|---|
| インタラクティブターミナル | ヘッドレス、JSON出力 |
| 1人の開発者 | チーム全体、CI/CDトリガー |
| 手動モニタリング | ダッシュボードとアラート |
| コストは個人負担 | コストは追跡・予算管理 |
| 「自分の環境では動く」 | 自動化された検証 |
| アドホックなワークフロー | 標準化されたスキル、バージョン管理 |
コース完了
Claude Code Architecture Mastery コース全24セッション、4モジュールを修了しました。
モジュール1：コアエージェント（セッション1-6） — エージェントループ、ツールとパーミッション、TodoWriteによる計画、サブエージェントとコンテキスト分離、スキルとナレッジローディング、コンテキストコンパクション。Claude Code はチャットボットではなく、ツール、パーミッション、コンテキスト管理を備えたエージェントループであることを学びました。
モジュール2：マルチエージェント（セッション7-12） — タスクグラフ、バックグラウンドタスク、エージェントチーム、チームプロトコル、自律エージェント、ワークツリー分離。複雑な作業には、明確に定義されたプロトコルを通じて連携する複数のエージェントが必要であることを学びました。
モジュール3：実践アーキテクチャ（セッション13-18） — コントロールプロトコル、MCP統合、フック、セッションストレージ、CLAUDE.md設計、パーミッションモデル。Claude Code を設定、拡張、セキュリティ保護するための実践的な知識を習得しました。
モジュール4：マスタリー（セッション19-24） — マルチCLIワークフロー、エラーリカバリー、コスト最適化、Human-in-the-Loop、カスタムエージェントとスキル、本番パターン。本番対応の準備が整いました。
核心原則
24セッション全体を通じて5つのアイデアが繰り返し登場しました：
- エージェントループが基盤。 ツール、サブエージェント、スキル、チーム --- すべてが「APIを呼び出し、停止理由を確認し、ツールを実行し、繰り返す」の上に構築されています。
- コンテキストは最も貴重なリソース。 サブエージェント、コンパクション、スキル、ワークツリー --- すべての設計判断がコンテキストを管理しています。
- パーミッションはセーフティネット。 信頼は制限的な状態から自律的な状態へと段階的に構築されます。
- Markdownが拡張言語。 コンパイル不要、デプロイメント不要。ファイルを配置するだけで、機能が追加されます。
- 本番には本番の規律が必要。 モニタリング、テスト、エラーハンドリング、コスト管理 --- なじみのあるツールの、新しい応用です。
次のステップ
- スキルライブラリを構築する。 チームの最も一般的なワークフロー3つから始めましょう。
- CI/CD統合をセットアップする。 自動PRレビューから始めましょう。結果に基づいてチューニングしましょう。
- コミュニティに貢献する。 スキル、エージェント、パターンを共有しましょう。
- 限界を押し広げる。 マルチエージェントアーキテクチャ、カスタムMCPサーバー、新しい連携パターン。
これで Claude Code の上に構築するためのアーキテクチャ知識を持っています。単に使うだけではなく。それがユーザーとビルダーの違いです。何かを作りましょう。