Claude Code応用 プロダクション開発

ダウンロードテンプレート

各セクションで使用するテンプレートです。事前にダウンロードしておくとスムーズに進められます。

コンテキストエンジニアリング -- CLAUDE.md設計論

コンテキストエンジニアリングとは

プロンプトエンジニアリングが「1回の指示をどう書くか」に注目するのに対し、コンテキストエンジニアリングはAIに渡す文脈全体を設計する技術です。CLAUDE.md、メモリファイル、MCP接続、会話履歴――AIが参照できる情報のすべてが設計対象になります。

Claude Codeの出力品質は、モデルの能力よりもコンテキストの質に依存します。同じモデルでも、適切なCLAUDE.mdがあるプロジェクトと何もないプロジェクトでは、出力精度に歴然たる差が出ます。

3層コンテキストモデル

%%{init:{'theme':'dark','themeVariables':{'primaryColor':'#00A5BF','primaryBorderColor':'#007A8F','primaryTextColor':'#e8e8e8','lineColor':'#00A5BF','secondaryColor':'#1a1a1a','background':'#141414','mainBkg':'#1a1a1a','nodeBorder':'#00A5BF'}}}%%
graph TB
  subgraph L1["Layer 1: グローバル設定"]
    G["~/.claude/CLAUDE.md"]
    GM["~/.claude/memory/"]
  end
  subgraph L2["Layer 2: プロジェクト設定"]
    P[".claude/CLAUDE.md"]
    PM[".claude/memory/"]
    PS[".claude/settings.json"]
  end
  subgraph L3["Layer 3: タスク設定"]
    T["会話中の指示"]
    F["添付ファイル"]
  end
  L3 -->|上書き| L2
  L2 -->|上書き| L1
  style L1 fill:#1a1a1a,stroke:#007A8F
  style L2 fill:#1a1a1a,stroke:#00A5BF
  style L3 fill:#1a1a1a,stroke:#33C4DA

Layer 1: グローバル設定(~/.claude/CLAUDE.md)

全プロジェクト共通のルール。コーディングスタイル、言語設定、セキュリティポリシーなど、自分のすべての開発に適用したい項目を記述します。

Layer 2: プロジェクト設定(.claude/CLAUDE.md)

プロジェクト固有のルール。使用する技術スタック、ディレクトリ構成、命名規則、テスト方針。Gitリポジトリにコミットしてチームで共有できます。

Layer 3: タスク設定(会話中の指示)

その場限りの詳細指示。具体的なファイルパス、実装方針の変更、一時的な例外ルール。最も優先度が高く、Layer 1/2のルールを上書きします。

メモリシステム

Claude Codeは会話をまたいで情報を記憶するメモリシステムを持っています。~/.claude/memory/にMarkdownファイルとして保存され、MEMORY.mdがインデックスの役割を果たします。

メモリの種類

良いCLAUDE.mdの設計パターン

• 具体的に書く -- 「きれいなコードを書いて」ではなく「関数は50行以内、ネストは3段まで」
• 禁止事項には理由を添える -- 「.envファイルを読み取らないこと(APIキー漏洩防止のため)」
• 優先順位を明示する -- 「可読性 > パフォーマンス > 簡潔さ」
• サンプルコードを含める -- 抽象的な説明より、期待するコードの具体例が効く

カスタムスキル開発 -- 再利用可能な指示セット

スキルとは

.claude/skills/ディレクトリに置くMarkdownファイルです。特定のタスクに対する詳細な指示をまとめておくことで、毎回同じ説明を繰り返す必要がなくなります。Claude Codeは関連するスキルを自動で検出し、タスクに適用します。

スキルファイルの構造

フロントマター

• name -- スキルの識別名。/skill-nameで呼び出せる
• description -- スキルの説明。Claude Codeがスキルを自動選択する際の判断材料
• triggers -- このスキルを発動させるキーワード。ユーザーの入力にこれらが含まれると自動適用

フロントマター全フィールド仕様

スキルファイルのフロントマターには以下のフィールドが使えます。すべて任意ですが、name/description/triggersの3つは実質必須と考えてください。

プログレッシブ開示

スキルファイルのすべてを常に読み込むとトークンを消費します。プログレッシブ開示の考え方で構成すると効率的です。

• 冒頭 -- 基本ルール(常に適用。5-10行)
• 中盤 -- 詳細ルール(必要時に参照。20-30行)
• 末尾 -- サンプルコード、エッジケース(まれに参照)

スキルの活用パターン

フック開発 -- イベント駆動の自動化

フックとは

Claude Codeのイベントに反応して自動実行されるシェルスクリプトやプログラムです。ファイル編集時にlintを走らせる、機密ファイルへの書き込みをブロックする、セッション終了時にコストを集計する――手動で忘れがちな作業を自動化できます。

イベント種類

settings.jsonでのフック定義

matcherの仕組み

matcherはツール名に対する正規表現です。"Edit|Write"はEditツールまたはWriteツールにマッチします。省略するとすべてのツールにマッチします(Stopイベントではmatcherは不要)。

フックの入出力

• $TOOL_INPUT -- ツールに渡された入力(JSON文字列)。ファイルパスや編集内容が含まれる
• stdout -- フックの標準出力はClaude Codeにフィードバックされる
• exit code -- PreToolUseでexit 2を返すとツール実行がブロックされる

実用的なフック例

例1: .envファイルへの書き込みをブロック(PreToolUse)

例2: ファイル変更時にESLint自動実行(PostToolUse)

例3: セッション終了時にサマリ出力(Stop)

hooks設定の完全な記述例

settings.jsonのhooksセクションには、PreToolUse / PostToolUse / Stopの3イベントを組み合わせて記述します。以下は実用的な設定の全体像です。

フックのEvent Object構造

フックスクリプトが受け取る$TOOL_INPUTはJSON文字列で、以下の構造を持ちます。

フックスクリプトの中でjqやgrep等を使ってフィールドを抽出し、条件判定に使います。exit 0で通過、exit 2でブロック、stdoutのメッセージがClaude Codeに返ります。

フックのデバッグ

• フックスクリプトにset -xを先頭に追加すると実行トレースが見える
• echoでデバッグ情報を出力し、Claude Codeのフィードバックで確認
• フックスクリプト単体でbash .claude/hooks/block-env.sh '{"file_path":".env"}'のようにテスト可能

エージェント/サブエージェント -- 並列実行と委譲

Agentツール

Claude Code内から別のClaude Codeインスタンス(サブエージェント)を起動する仕組みです。複雑なタスクを分割し、それぞれのサブタスクを独立したエージェントに委譲できます。

%%{init:{'theme':'dark','themeVariables':{'primaryColor':'#00A5BF','primaryBorderColor':'#007A8F','primaryTextColor':'#e8e8e8','lineColor':'#00A5BF','secondaryColor':'#1a1a1a','background':'#141414','mainBkg':'#1a1a1a','nodeBorder':'#00A5BF'}}}%%
graph TB
  Main["メインエージェント
(ユーザーと対話)"] --> |"タスク委譲"| Sub1["サブエージェント1
コードベース調査"]
  Main --> |"タスク委譲"| Sub2["サブエージェント2
テスト生成"]
  Main --> |"タスク委譲"| Sub3["サブエージェント3
ドキュメント更新"]
  Sub1 --> |"結果返却"| Main
  Sub2 --> |"結果返却"| Main
  Sub3 --> |"結果返却"| Main
  Main --> Result["統合結果をユーザーに報告"]

Agent toolのパラメータ一覧

Claude Codeが内部的にサブエージェントを起動する際に使うパラメータです。カスタムエージェントやプロンプトから間接的に制御できます。

subagent_typeの種類一覧

並列実行

複数のサブエージェントを同時に起動することで、独立したタスクを並列処理できます。テスト生成とドキュメント更新のように依存関係がないタスクを同時に走らせると、トータルの待ち時間が大幅に短縮されます。

worktree分離

gitのworktreeを使って安全にブランチ作業を委譲する手法です。サブエージェントがメインブランチとは別のworktreeで作業するため、メインの作業ツリーを汚さずに済みます。

カスタムエージェント

.claude/agents/ディレクトリにMarkdownファイルを置くことで、特定の役割に特化したカスタムエージェントを定義できます。

カスタムエージェントの設定項目

• tools -- エージェントが使用できるツールを制限。Read/Grep/Globだけにすれば読み取り専用
• model -- 使用するモデル。コスト削減のためSonnetを指定するケースが多い
• description -- エージェントの役割。メインエージェントがタスク委譲時に参照

MCP統合 -- 高度な外部ツール連携

MCPサーバーの自作

C04ではMCPクライアントとしてのClaude Code(既存のMCPサーバーに接続する側)を学びました。このセクションでは、自分でMCPサーバーを作る側に回ります。TypeScript SDKを使って、独自のツール、リソース、プロンプトをClaude Codeに提供します。

%%{init:{'theme':'dark','themeVariables':{'primaryColor':'#00A5BF','primaryBorderColor':'#007A8F','primaryTextColor':'#e8e8e8','lineColor':'#00A5BF','secondaryColor':'#1a1a1a','background':'#141414','mainBkg':'#1a1a1a','nodeBorder':'#00A5BF'}}}%%
graph LR
  CC["Claude Code
(MCPクライアント)"] -->|"ツール呼び出し"| S1["自作MCPサーバー
(TypeScript)"]
  S1 -->|"結果返却"| CC
  CC -->|"リソース取得"| S1
  S1 -->|"DB/API"| DB["外部データソース"]

ツール定義の構造

リソース公開

リソースはread-onlyのデータ提供です。ツールと異なり、Claude Codeが能動的に呼び出すのではなく、コンテキストとして参照できるデータを公開します。

プロンプト公開

再利用可能なプロンプトテンプレートをMCPサーバーから提供します。

セキュリティ

• 最小権限 -- MCPサーバーには必要最小限のファイルアクセス権だけ与える
• 入力バリデーション -- Zodスキーマで入力を厳密に検証する
• 環境変数でAPIキー管理 -- ハードコードしない
• ログ出力 -- ツール呼び出しのログを残して監査可能にする

仕様駆動開発 -- メモから実装まで

仕様駆動開発とは

「メモ → 仕様書 → CLAUDE.md更新 → 実装 → テスト」の流れを型として定着させる開発手法です。AIの出力品質は入力の仕様書品質に比例します。雑なメモをそのままClaude Codeに渡すのと、構造化された仕様書を渡すのとでは、出力に明確な差が出ます。

%%{init:{'theme':'dark','themeVariables':{'primaryColor':'#00A5BF','primaryBorderColor':'#007A8F','primaryTextColor':'#e8e8e8','lineColor':'#00A5BF','secondaryColor':'#1a1a1a','background':'#141414','mainBkg':'#1a1a1a','nodeBorder':'#00A5BF'}}}%%
graph LR
  A["業務メモ
(走り書き)"] --> B["構造化仕様書
(Markdown)"]
  B --> C["CLAUDE.md更新
(仕様書パス追加)"]
  C --> D["Claude Codeで実装"]
  D --> E["テスト生成・実行"]
  E --> F["レビュー・修正"]
  F -.->|フィードバック| B

なぜ仕様を先に書くか

• 出力の一貫性 -- 同じ仕様書から何度実行しても同等の結果が得られる
• レビュー可能性 -- 実装前に仕様書をレビューできる。実装後の手戻りが減る
• テスト容易性 -- 仕様書からテストケースを自動導出できる
• 引き継ぎ -- 仕様書があれば別の人(別のAI)でも同じ機能を再実装できる

仕様書の品質がAI出力品質を決める

同じ「ログイン機能を作って」という要求でも、渡す仕様の粒度で出力に明確な差が出ます。

同じAIモデルを使っても、具体的な数値・制約・セキュリティ要件を書き出すだけで出力品質が跳ね上がります。仕様書に投じた時間は、デバッグ時間の削減として確実に回収できます。

仕様書のフォーマット

コメントドリブン開発との組み合わせ

仕様書とは別に、実装ファイル内にコメントで意図を先に書く手法です。関数のシグネチャとコメントを先に書き、実装をClaude Codeに委ねます。

チーム開発 -- 設定共有とレビュー自動化

.claude/ディレクトリのチーム共有設計

個人で使うなら自由に設定できるClaude Codeも、チームで使うとなると「何をGitで共有し、何をローカルに留めるか」の線引きが必要です。

settings.jsonのGitリポジトリ管理

CLAUDE.mdのチームレビュープロセス

CLAUDE.mdはコードの品質を左右する設定ファイルです。変更時はPRレビューを通すべきです。

• 変更提案 -- CLAUDE.mdを変更するPRを作成
• チームレビュー -- 最低1人のApproveを必須に
• 影響範囲の確認 -- 変更がどのタスクに影響するかを記載
• テスト -- 変更後の設定でClaude Codeが期待通りに動作するか確認

レビュー自動化

PRレビュー用のカスタムコマンドを定義し、Claude Codeで自動レビューを実行できます。

CI/CD統合 -- GitHub Actions連携

GitHub Actionsとの連携

Claude Codeは非対話モード(claude -p)で実行できます。これによりCIパイプラインに組み込み、PRの自動レビュー、テスト生成、ドキュメント更新を自動化できます。

%%{init:{'theme':'dark','themeVariables':{'primaryColor':'#00A5BF','primaryBorderColor':'#007A8F','primaryTextColor':'#e8e8e8','lineColor':'#00A5BF','secondaryColor':'#1a1a1a','background':'#141414','mainBkg':'#1a1a1a','nodeBorder':'#00A5BF'}}}%%
graph LR
  PR["PR作成"] --> GH["GitHub Actions
ワークフロー"]
  GH --> CC["claude -p
(非対話モード)"]
  CC --> Review["レビューコメント
をPRに投稿"]
  CC --> Tests["テスト生成
→ 実行"]
  CC --> Docs["ドキュメント
自動更新"]

claude -p(非対話モード)

標準入力からプロンプトを受け取り、結果を標準出力に返すモードです。シェルスクリプトやCIパイプラインから呼び出せます。

CIパイプラインでの活用パターン

GitHub Actionsワークフロー例

セキュリティ: CIでのAPIキー管理

• GitHub SecretsでAPIキーを管理する。ワークフローファイルにハードコードしない
• 最小権限の原則 -- CIで使うAPIキーは必要最小限のスコープにする
• コスト制限 -- CI実行ごとのトークン上限を設定して予想外のコスト発生を防ぐ
• ログ -- APIキーがログに出力されないことを確認する

パフォーマンスとコスト最適化

/costコマンドでトークン消費監視

Claude Codeのセッション中に/costと入力すると、現在のセッションで消費したトークン数と概算コストが表示されます。コスト意識を持つ第一歩です。

モデル使い分け

/compactでコンテキスト圧縮

会話が長くなるとコンテキストウィンドウが埋まり、応答が遅くなり、コストも増大します。/compactコマンドで会話履歴を要約・圧縮できます。

• いつ使うか -- 「コンテキストの80%以上を消費」と表示されたとき
• 注意点 -- 圧縮すると細部が失われる可能性がある。重要な情報はCLAUDE.mdやメモリに記録しておく

キャッシュ戦略

Anthropic APIにはプロンプトキャッシュ機能があります。同じ前提条件(CLAUDE.md、スキルファイル等)を繰り返し送信する場合、キャッシュが効いて応答速度とコストの両方が改善されます。

• CLAUDE.mdの先頭部分は変更頻度を低く保つ(キャッシュヒット率向上)
• スキルファイルを頻繁に書き換えるとキャッシュが無効化される
• 大きなコンテキスト(長いファイル)は必要な部分だけ渡す

タスク種類別の推奨設定

総合ハンズオン: Claude Codeプラグインを完成させる

ゴール

このコースで学んだすべてを統合し、Claude Codeプラグイン一式(スキル3つ + フック2つ + カスタムエージェント1つ + MCP接続)を完成させます。自分のプロジェクト、または新規プロジェクトに対して、production-readyな.claude/ディレクトリを構築します。

%%{init:{'theme':'dark','themeVariables':{'primaryColor':'#00A5BF','primaryBorderColor':'#007A8F','primaryTextColor':'#e8e8e8','lineColor':'#00A5BF','secondaryColor':'#1a1a1a','background':'#141414','mainBkg':'#1a1a1a','nodeBorder':'#00A5BF'}}}%%
graph TB
  subgraph Plugin["Claude Code プラグイン"]
    CLAUDE["CLAUDE.md
(3層設計)"]
    S1["Skill: review"]
    S2["Skill: test"]
    S3["Skill: docs"]
    H1["Hook: security"]
    H2["Hook: quality"]
    A1["Agent: auditor"]
    MCP["MCP接続"]
  end
  CLAUDE --> S1
  CLAUDE --> S2
  CLAUDE --> S3
  CLAUDE --> H1
  CLAUDE --> H2
  CLAUDE --> A1
  CLAUDE --> MCP