Claude Code上級実践ガイド【2026年版】——CLAUDE.md設計・大規模プロジェクト管理・MCPサーバー連携・チーム開発への展開

Claude Code上級実践ガイド【2026年版】——CLAUDE.md設計・大規模プロジェクト管理・MCPサーバー連携・チーム開発への展開

  1. はじめに——「動かす」から「使いこなす」へ
  2. Claude Codeの上級機能マップ
  3. 【第1章】CLAUDE.md設計の技法
    1. CLAUDE.mdとは何か——「プロジェクトの記憶」
    2. 階層型CLAUDE.md構成——グローバル・プロジェクト・サブディレクトリ
    3. 書くべきこと・書くべきでないこと
    4. コピペで使えるCLAUDE.mdテンプレート
    5. CLAUDE.mdが肥大化したときの対処法
  4. 【第2章】大規模プロジェクト管理
    1. コンテキストウィンドウとの戦い
    2. サブエージェントで文脈を分割する
    3. Hooksで「必ず実行する」ルールを設ける
    4. Git Worktreesで並列開発する
    5. カスタムスラッシュコマンドで繰り返し作業を自動化する
  5. 【第3章】MCPサーバー連携の実践
    1. MCPサーバーの3つのトランスポートタイプ
    2. 用途別おすすめMCPサーバー一覧
    3. MCPサーバーの追加手順と設定ファイル
    4. MCPサーバー連携の実践例：JIRAチケット→コード→PRの自動フロー
    5. MCPセキュリティの基本原則
  6. 【第4章】チーム開発への展開
    1. チーム共有の設定ファイル構成
    2. GitHub ActionsでCI/CDにClaude Codeを組み込む
    3. 新メンバーオンボーディングへの活用
    4. チーム導入時の権限設計
  7. CursorとClaude Codeの使い分け
  8. よくある質問（Q&A）
  9. まとめ——Claude Codeを「チームメンバー」として扱う
  10. 参考リンク
  1. はじめに——「動かす」から「使いこなす」へ
  2. Claude Codeの上級機能マップ
  3. 【第1章】CLAUDE.md設計の技法
    1. CLAUDE.mdとは何か——「プロジェクトの記憶」
    2. 階層型CLAUDE.md構成——グローバル・プロジェクト・サブディレクトリ
    3. 書くべきこと・書くべきでないこと
    4. コピペで使えるCLAUDE.mdテンプレート
    5. CLAUDE.mdが肥大化したときの対処法
  4. 【第2章】大規模プロジェクト管理
    1. コンテキストウィンドウとの戦い
    2. サブエージェントで文脈を分割する
    3. Hooksで「必ず実行する」ルールを設ける
    4. Git Worktreesで並列開発する
    5. カスタムスラッシュコマンドで繰り返し作業を自動化する
  5. 【第3章】MCPサーバー連携の実践
    1. MCPサーバーの3つのトランスポートタイプ
    2. 用途別おすすめMCPサーバー一覧
    3. MCPサーバーの追加手順と設定ファイル
    4. MCPサーバー連携の実践例：JIRAチケット→コード→PRの自動フロー
    5. MCPセキュリティの基本原則
  6. 【第4章】チーム開発への展開
    1. チーム共有の設定ファイル構成
    2. GitHub ActionsでCI/CDにClaude Codeを組み込む
    3. 新メンバーオンボーディングへの活用
    4. チーム導入時の権限設計
  7. CursorとClaude Codeの使い分け
  8. よくある質問（Q&A）
    1. Q1. CLAUDE.mdに書いたことをClaudeが守ってくれないことがあります。どうすればいいですか？
    2. Q2. MCPサーバーを追加したら接続エラーが出ます。
    3. Q3. サブエージェントを使うとコストが2倍になりますか？
    4. Q4. チームでClaude Codeを使うとき、全員がAnthropicのAPIキーを持つ必要がありますか？
    5. Q5. Claude Codeは日本語のコードベースやコメントに対応していますか？
  9. まとめ——Claude Codeを「チームメンバー」として扱う
  10. 参考リンク

はじめに——「動かす」から「使いこなす」へ

Claude Codeの入門記事では、インストール・基本的なコード生成・ファイル操作といった「動かし方」を解説しました。しかし、Claude Codeを日常的に使い込んでいくうちに、こんな壁にぶつかります。

「毎回プロジェクトの説明をしなければならない」
「大きなコードベースで指示がずれていく」
「チームメンバーとClaude Codeの使い方を統一できない」
「GitHubやJIRAと連携させたいが、どう設定すればいいかわからない」

これらは入門段階では気にならないが、本格的に活用しようとしたときに初めて直面する「上級者の課題」です。

本記事では、CLAUDE.mdの設計・大規模プロジェクト管理・MCPサーバー連携・チーム開発への展開という4つのテーマを体系的に解説します。入門記事（ID 142）の続編として、Claude Codeを個人ツールからチームの生産性基盤へと進化させる実践手順をまとめました。

Claude Codeの上級機能マップ

まず、Claude Codeの機能全体を俯瞰します。入門編でカバーした領域と、本記事でカバーする上級領域を整理します。

機能カテゴリ具体的な機能難易度本記事での扱い
基本操作コード生成・ファイル読み書き・Git操作・@ファイル参照入門入門記事参照
プロジェクト設定CLAUDE.md・settings.json・パーミッション管理中級〜上級第1・4章で解説
コンテキスト管理サブエージェント・/compact・/clear・セッション再開上級第2章で解説
自動化・拡張Hooks・カスタムスラッシュコマンド・Skills・Plugins上級第2章で解説
外部ツール連携MCPサーバー（GitHub・JIRA・DB・ブラウザ等）上級第3章で解説
チーム・CI/CDGitHub Actions・共有設定・オンボーディング自動化上級第4章で解説

【第1章】CLAUDE.md設計の技法

CLAUDE.mdとは何か——「プロジェクトの記憶」

CLAUDE.mdは、Claude Codeが新しいセッションを開始するたびに自動的に読み込むプロジェクト専用の指示書です。「Claudeへの社員ハンドブック」「AIのための設計書」とも表現されます。

このファイルがない状態では、Claudeは毎回「どんなプロジェクトか」「どんなコーディング規約があるか」「何のコマンドでビルドするか」を推測しなければなりません。CLAUDE.mdを整備することで、毎回の説明コストをゼロにし、コードの一貫性を維持できます。

CLAUDE.mdはMarkdown形式で記述し、プロジェクトのルートに置きます。Claudeはセッション開始時に自動でこのファイルを読み込み、会話全体を通じてその内容を参照します。

階層型CLAUDE.md構成——グローバル・プロジェクト・サブディレクトリ

Claude Codeは複数のCLAUDE.mdを階層的に読み込む仕組みを持っています。大規模プロジェクトやモノレポ（複数サービスを1リポジトリで管理する構成）で特に強力です。

配置場所パススコープ用途
グローバル~/.claude/CLAUDE.md全プロジェクト共通個人の作業スタイル・よく使うコマンド・デフォルトの振る舞い
プロジェクトルート./CLAUDE.mdプロジェクト全体技術スタック・コーディング規約・ビルド・テストコマンド・ディレクトリ構造
サブディレクトリ./frontend/CLAUDE.md など特定サービス・モジュールフロントエンド固有の規約・バックエンド固有の設定・マイクロサービス別の手順

Claudeがファイルを処理する際、そのファイルのパスに対応する全階層のCLAUDE.mdが読み込まれます。./frontend/src/Button.tsxを処理する場合、グローバル→ルート→frontend/のCLAUDE.mdが順に適用されます。

書くべきこと・書くべきでないこと

公式ベストプラクティスでも指摘されている通り、CLAUDE.mdの過剰な記述は逆効果です。ファイルが長くなりすぎると重要なルールが「ノイズ」に埋もれ、Claudeが無視するようになります。

書くべきこと（Claudeが自力で知ることができない情報）：

  • ビルド・テスト・リントのコマンド（npm run dev、pytest tests/など）
  • ディレクトリ構造の概要と各ディレクトリの役割
  • コーディング規約（命名規則・TypeScriptの厳格モード・禁止パターンなど）
  • Git運用ルール（ブランチ命名・コミットメッセージ形式）
  • 環境変数のスキームと管理方針
  • よく使うMCPツールの使い方メモ
  • 「やってはいけないこと」の明示（mainブランチへの直接プッシュ禁止など）

書くべきでないこと（削除・Hooksへの移管を推奨）：

  • Claudeが既にデフォルトで行うこと（「日本語で答えてください」は不要な場合が多い）
  • 「必ず〇〇すること」という強制ルール→ HooksのPreToolUseで強制する方が確実
  • プロジェクトの歴史や背景説明（コンテキストを消費するだけ）
  • 外部ドキュメントのコピーペースト（URLを記載してClaude自身に参照させる）

コピペで使えるCLAUDE.mdテンプレート

以下は、TypeScript + React + Node.jsの一般的なWebアプリを想定したプロジェクトルート用のCLAUDE.mdテンプレートです。

# [プロジェクト名] — Claude Code向け設計書

## プロジェクト概要
- **用途**: [一行説明]
- **技術スタック**: TypeScript 5.x / React 19 / Node.js 22 / PostgreSQL
- **パッケージマネージャー**: pnpm

## 必須コマンド
```bash
pnpm dev          # 開発サーバー起動（ポート3000）
pnpm build        # 本番ビルド
pnpm test         # ユニットテスト（Vitest）
pnpm test:e2e     # E2Eテスト（Playwright）
pnpm lint         # ESLintチェック
pnpm typecheck    # TypeScript型チェック
```

## ディレクトリ構造
- `src/app/` — Next.js App Router ページ・レイアウト
- `src/components/` — 再利用可能なUIコンポーネント
- `src/lib/` — ユーティリティ・ヘルパー
- `src/server/` — バックエンドロジック・API
- `prisma/` — データベーススキーマ・マイグレーション
- `tests/` — テストファイル（ユニット・E2E）

## コーディング規約
- TypeScriptは `strict: true`。`any`型は使用禁止（`unknown`を使う）
- インターフェースは`type`より`interface`を優先
- コンポーネントはデフォルトエクスポート禁止（名前付きエクスポートのみ）
- ファイル名はkebab-case。コンポーネント名はPascalCase
- テストファイルは対象ファイルと同ディレクトリに `*.test.ts` として配置

## Git規約
- ブランチ命名: `feature/TICKET-123-短い説明` / `fix/TICKET-456-バグ内容`
- コミットメッセージ: Conventional Commits形式（`feat:` / `fix:` / `docs:` / `refactor:` / `test:`）
- `main`ブランチへの直接コミット禁止。必ずPR経由

## 注意事項
- `.env` および `.env.local` は絶対に読み取り・編集しないこと
- `prisma/migrations/` は手動編集禁止。必ず `pnpm prisma migrate dev` で生成
- `node_modules/` および `dist/` は触らないこと

CLAUDE.mdが肥大化したときの対処法

プロジェクトが成熟するにつれてCLAUDE.mdが膨らむのは自然なことですが、50行を超えたら精査のサインです。対処法は3つあります。

① サブディレクトリのCLAUDE.mdに分散させる：フロントエンド固有の規約はsrc/frontend/CLAUDE.mdへ、バックエンド固有の手順はsrc/server/CLAUDE.mdへ移します。

② 「すべき」ルールをHooksに移す：「コミット前に必ずテストを実行すること」は指示文として書くより、PreToolUseフックで機械的に強制する方が確実です。CLAUDE.mdの行数を減らしながら、規則の遵守率が上がります。

③ Skillsファイルに切り出す：「このAPIの使い方」「テストの書き方パターン」といった知識は、.claude/skills/配下のSKILL.mdファイルに切り出します。Claudeが必要なタイミングで自動的に参照します。

【第2章】大規模プロジェクト管理

コンテキストウィンドウとの戦い

Claude Codeは最大200Kトークンのコンテキストウィンドウを持ちます。一見広大ですが、大きなコードベースで「ファイルを調査して→設計を検討して→実装して→テストして」という作業を1セッションでやろうとすると、驚くほど早く枯渇します。

コンテキストが枯渇すると何が起きるか。Claudeは古い会話を「圧縮（compact）」し始め、前半で決めたアーキテクチャの細部や、エラー解決の経緯が失われます。これが「後半でClaude Codeの品質が落ちる」という体験の正体です。

コンテキスト管理の基本コマンドを押さえておきましょう。

コマンド動作使いどころ
/clear会話履歴を完全リセット別のタスクに切り替えるとき。完全に新鮮な状態が欲しいとき
/compact会話履歴を要約して圧縮コンテキストが80%を超えたとき。作業の続きを保ちつつ圧縮したいとき
claude --continue直前のセッションを再開ターミナルを閉じてしまったが、前の作業を続けたいとき
claude --resume過去のセッション一覧から選択して再開数日前の作業コンテキストを復元したいとき

重要なのは、/compactを使う前にCLAUDE.mdに「compactするときはXXXを保持すること」という指示を書いておくことです。例えば「コンパクション時は、変更済みファイルのリストとテストコマンドを必ず保持すること」と書いておけば、圧縮後も重要な文脈が維持されます。

サブエージェントで文脈を分割する

サブエージェントは、Claude Codeの最も強力な機能の1つです。「別のコンテキストウィンドウでタスクを実行し、結果だけを返す」という仕組みで、メインの会話を汚さずに調査・探索・分析を行えます。

活用シナリオを具体的に見てみましょう。

シナリオ：認証システムの改修

「Todoアプリの認証周りをJWT→セッションベースに変えたい」というタスクで、まず現状調査が必要です。直接調査すると大量のファイルを読み込みメインコンテキストが消費されます。

以下の調査をサブエージェントに依頼してください：
「現在のJWT認証の実装がどのファイルに、どのように書かれているか
をまとめてください。ファイル名・関数名・主要な処理フローを
200行以内で報告してください。」

サブエージェントが調査結果のサマリーだけを返すため、メインコンテキストには「調査結果の要点」しか残りません。その結果を見てから実装に取りかかることで、コンテキストを効率的に使えます。

注意点：サブエージェントに文脈を「隔離」しすぎると、メインエージェントが全体像を把握できなくなります。「調査・探索」はサブエージェント向き、「実装・意思決定」はメインエージェントで行うのが基本です。

Hooksで「必ず実行する」ルールを設ける

HooksはCLAUDE.mdの「すべき」指示を、確定的なコード実行に変える仕組みです。「Claude Code、またフォーマットするの忘れてる…」という問題がHooksで完全に解消されます。

フックには4種類あります。

フック種類発火タイミング代表的な用途
PreToolUseツール実行の直前mainブランチへの直接コミットをブロック・危険な操作の事前チェック
PostToolUseツール実行の直後ファイル保存後にPrettierを実行・テストファイル変更後にテスト自動実行
NotificationClaude Code が通知を送るとき長時間タスクの完了をSlack・デスクトップ通知に転送
StopClaude Code がレスポンスを完了するときセッション終了時に作業ログを自動記録

設定は.claude/settings.jsonに記述します。以下は実用的なフック設定の例です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write(*.ts)|Write(*.tsx)",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $file"
          }
        ]
      },
      {
        "matcher": "Write(*.test.ts)|Write(*.test.tsx)",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm test $file --run"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          {
            "type": "command",
            "command": "[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"block\": true, \"message\": \"mainブランチへの直接コミットは禁止です。ブランチを作成してください。\"}' >&2; exit 2; }",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

フック設計の重要なコツ：「書き込み中にブロックするより、コミット時点でブロックする」方が効果的です。作業途中でブロックするとClaudeが混乱します。最終チェックはPreToolUseのgit commitタイミングで行うのが実践的です。

Git Worktreesで並列開発する

Git Worktreesは、1つのリポジトリを複数のディレクトリにチェックアウトする仕組みです。Claude Codeと組み合わせることで、複数の機能を別々のClaude Codeセッションで同時に開発できます。

# feature/login-redesignとfeature/payment-updateを並列開発する例
git worktree add ../myapp-login feature/login-redesign
git worktree add ../myapp-payment feature/payment-update

# ターミナル1：ログイン機能の開発
cd ../myapp-login && claude

# ターミナル2：支払い機能の開発（別ターミナルで）
cd ../myapp-payment && claude

各WorKtreeは独立したファイルシステムを持つため、Claudeがファイルを変更しても他のセッションに影響しません。長時間の実装タスクを複数並列で走らせるときに特に有効です。

カスタムスラッシュコマンドで繰り返し作業を自動化する

プロジェクト内の繰り返し作業（コードレビュー・PR作成・テスト生成など）は、カスタムスラッシュコマンドとして登録することで再利用可能なワークフローになります。

.claude/commands/ディレクトリにMarkdownファイルを作成するだけです。

例：PRレビューコマンド（.claude/commands/pr-review.md）

現在のブランチの変更点について、以下の観点でコードレビューを行ってください：

1. `git diff main...HEAD` で変更内容を確認する
2. 以下の観点でレビューを実施する：
   - TypeScriptの型安全性（anyの使用・型推論の活用）
   - エラーハンドリングの適切さ
   - パフォーマンス上の懸念点
   - セキュリティ上のリスク
   - テストカバレッジの適切さ
3. 問題点は深刻度（🔴 Critical / 🟡 Medium / 🟢 Low）付きで列挙する
4. 全体的な評価と改善提案をまとめる

参照するコーディング規約はCLAUDE.mdを確認すること。

セッション内で /pr-review と入力するだけでこのワークフローが実行されます。$ARGUMENTSプレースホルダーを使えば引数を渡すことも可能です（例：/fix-issue PROJ-123）。

【第3章】MCPサーバー連携の実践

MCPサーバーの3つのトランスポートタイプ

MCPサーバーとの接続方式は3種類あります。用途に合わせて使い分けます。

トランスポート特徴向いている用途設定例
stdio（標準入出力）ローカルプロセスとして起動。最も一般的でシンプルGitHub・ファイルシステム・DBなどローカル連携claude mcp add github -- npx @anthropic/mcp-github
SSE（Server-Sent Events）リモートサーバーにHTTPで接続クラウドホスト型サービス・チーム共有サーバーclaude mcp add remote --transport sse https://mcp.example.com/sse
HTTP（Streamable HTTP）MCP v2025-03以降の新方式。OAuth対応クラウドAPIとのOAuth認証を伴う連携claude mcp add api --transport http https://api.example.com/mcp

日常的な開発ではstdioが80%以上のケースをカバーします。チームで共有したい場合やリモート環境との連携が必要な場合にSSE/HTTPを検討します。

用途別おすすめMCPサーバー一覧

カテゴリMCPサーバー名できることインストールコマンド
バージョン管理GitHub MCP（公式）リポジトリ・PR・Issue・CI/CDの操作claude mcp add github -- npx -y @anthropic/mcp-github
プロジェクト管理Linear MCP（公式）チケット作成・ステータス更新・担当者変更claude mcp add linear -- npx -y @anthropic/mcp-linear
データベースPostgreSQL MCP自然言語でSQLクエリ・スキーマ確認・データ集計claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres
データベースSQLite MCPローカルSQLiteDBの管理・クエリclaude mcp add sqlite -- npx -y @modelcontextprotocol/server-sqlite
ブラウザ操作Playwright MCPブラウザ自動操作・スクレイピング・E2Eテスト支援claude mcp add playwright -- npx -y @playwright/mcp
ファイル操作Filesystem MCP（公式）プロジェクト外のファイルシステム操作claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem /path
ナレッジ管理Memory MCPナレッジグラフベースの永続メモリclaude mcp add memory -- npx -y @modelcontextprotocol/server-memory
モニタリングSentry MCPエラートレース確認・Issue管理公式ドキュメント参照

MCPサーバーの追加手順と設定ファイル

MCPサーバーの追加はコマンド1行です。ただし、APIキーなどの認証情報の扱いに注意が必要です。

# ① GitHub MCPサーバーの追加
claude mcp add github -- npx -y @anthropic/mcp-github

# ② 追加後、環境変数でトークンを渡す設定を行う
# .claude/settings.jsonに以下を追記（手動編集）

環境変数を使ってAPIキーを渡す.claude/settings.jsonの設定例：

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    }
  }
}

重要：${GITHUB_TOKEN}のように環境変数参照形式で記述します。APIキーをsettings.jsonに直接書くと、Gitにコミットした際に漏洩するリスクがあります。settings.local.json（.gitignore対象）に直接値を書く方法もありますが、環境変数が最も安全です。

MCPサーバー連携の実践例：JIRAチケット→コード→PRの自動フロー

GitHub MCPとJIRA MCPを組み合わせると、「チケット番号を渡すだけで実装からPR作成まで自動化」という強力なワークフローが実現します。

カスタムスラッシュコマンド/ticket $ARGUMENTSとして設定するイメージ：

# .claude/commands/ticket.md

JIRAチケット $ARGUMENTS を実装してください。以下の手順で進めること：

1. `jira`ツールでチケット $ARGUMENTS の詳細・受け入れ条件を取得する
2. 現在のコードベースで関連ファイルを調査する
3. チケットの内容から `feature/TICKET-$ARGUMENTS-短い説明` というブランチを作成する
4. 受け入れ条件を満たす実装を行う
5. 実装したコードに対応するユニットテストを作成する
6. `pnpm typecheck && pnpm test` が通ることを確認する
7. `github`ツールでPRを作成し、チケット番号をPRの説明にリンクする
8. `jira`ツールでチケットのステータスを「In Review」に更新する

このワークフローにより、`/ticket PROJ-123`と入力するだけで一連の開発サイクルが自動化されます。

MCPセキュリティの基本原則

MCPサーバーはClaude Codeに強力な権限を与えるため、セキュリティ設計は慎重に行う必要があります。

  • 最小権限の原則：GitHub MCPには必要最低限のスコープ（Read-only か特定リポジトリのみ）のトークンを使用する
  • 本番DB接続を避ける：PostgreSQL MCPは原則として読み取り専用ユーザーで接続し、本番DBへの直接接続は避ける
  • 破壊的操作には確認ステップ：DeleteやDropを伴う操作はClaude Codeが実行前に必ず確認を求めるよう、CLAUDE.mdに明示しておく
  • ログを残す：MCPツールの呼び出し履歴はClaude Codeのセッションログに残るため、定期的にレビューする

MCPセキュリティの詳細については、MCPサーバーセキュリティ完全ガイド【2026年版】を参照してください。

【第4章】チーム開発への展開

チーム共有の設定ファイル構成

Claude Codeをチームで活用するためには、設定ファイルを「共有するもの」と「個人にゆだねるもの」に明確に分けることが重要です。

ファイルGitへのコミット内容
CLAUDE.md✅ コミットするプロジェクト規約・コマンド・ディレクトリ構造（チーム全員が従うべきもの）
.claude/settings.json✅ コミットするチーム共通のHooks・パーミッション設定・MCP構成（環境変数参照形式で）
.claude/commands/✅ コミットするチーム共有のカスタムスラッシュコマンド（/ticket, /pr-review など）
.claude/skills/✅ コミットするプロジェクト固有のスキル（UIコンポーネントの使い方・テストパターンなど）
.claude/settings.local.json❌ .gitignoreに追加個人のAPIキー・個人的な設定上書き
~/.claude/CLAUDE.md❌ 個人管理個人のワークスタイル・グローバルな好み

このルールを徹底することで、チームメンバーが`git clone`した瞬間からClaude Codeが「プロジェクトを知っている状態」になります。

GitHub ActionsでCI/CDにClaude Codeを組み込む

Claude Codeは--printフラグを使うとインタラクティブなセッションを開かず、ヘッドレス（自動実行）モードで動作します。これをGitHub Actionsと組み合わせることで、CI/CDパイプラインにAIを組み込めます。

代表的な活用パターンは3つです。

パターン1：PRへの自動コードレビューコメント

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Claude Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npm install -g @anthropic-ai/claude-code
          claude -p "このPRの変更点をレビューしてください。
          git diff origin/main...HEAD の内容を確認し、
          コードの品質・セキュリティ・パフォーマンス上の問題点を
          マークダウン形式で報告してください。" \
          --output-format text > review.md

      - name: Comment PR
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs')
            const review = fs.readFileSync('review.md', 'utf8')
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## 🤖 Claude Code Review\n\n${review}`
            })

パターン2：テスト失敗時の自動デバッグ提案

テストが失敗したCIジョブに対して、Claude Codeがエラーログを分析して原因と修正案をIssueとしてコメントするフロー。テストの失敗を放置しがちなチームに効果的です。

パターン3：ドキュメントの自動更新

APIの変更（OpenAPI仕様の更新・型定義の変更）をトリガーに、Readmeやドキュメントサイトのコンテンツを自動更新するフロー。

新メンバーオンボーディングへの活用

Claude Codeはコードベースの「生きた説明書」として機能します。新メンバーのオンボーディングに使える活用法を紹介します。

コードベース探索モード：新メンバーが最初にやること

# このプロジェクトのアーキテクチャを説明してください。
# 特に以下を教えてください：
# - データの流れ（フロントエンド→バックエンド→DB）
# - 認証・認可の仕組み
# - テストの書き方とディレクトリ構造
# - 新機能を追加するときの典型的な手順

既存コードの文脈理解：特定のファイルや関数について

@src/lib/auth/session-manager.ts

このファイルの役割と、どのような状況でこの実装パターンを
選択したのかを推測して説明してください。
また、このファイルを修正するときに注意すべき点を挙げてください。

CLAUDE.mdに「オンボーディング時に確認すべき重要ファイルリスト」を記載しておくと、新メンバーが何を読めばよいかを迷わなくなります。

チーム導入時の権限設計

チームメンバーごとにClaude Codeへのアクセス権限を設計する際の考え方を整理します。

ロール推奨パーミッションモード主な制限
シニアエンジニア / リードAcceptEdits（自動承認）本番環境への直接操作・mainへの直接コミットのみHooksでブロック
ジュニアエンジニアPlan Mode → レビュー後にAcceptEditsファイル削除・DB操作は手動確認を必須に
QA / テスターRead-only + テスト実行のみソースコードの変更権限なし
CI/CD（自動実行）ヘッドレスモード + 最小権限許可リストに明示したコマンドのみ実行可

.claude/settings.jsonのpermissions.allow・permissions.denyで操作レベルの制御が可能です。また、settings.local.json（個人管理・Gitignore対象）で個人ごとの上書きが可能なため、共通設定は厳しめに、個人がゆるめる形が安全です。

CursorとClaude Codeの使い分け

Claude Codeの上級機能を紹介してきましたが、多くの方が「Cursorとどう使い分けるか」を気にしているはずです。両者は競合ではなく、補完関係にあります。

観点Claude CodeCursor
最も得意なこと大規模なコードベース横断的な実装・リファクタリング・エージェント的なタスク実行インラインでの高速な補完・⌘Kでの即興修正・IDEと一体化した体験
UI/UXターミナルベース（テキスト操作が中心）GUIベース（直感的・見た目重視）
コンテキスト管理明示的（ユーザーが管理する）自動的（IDEが自動収集）
拡張性MCP・Hooks・カスタムコマンドで高度に自動化可能プラグイン・ルールファイル（.cursorrules）
チーム設定の共有CLAUDE.md・settings.jsonをGitで共有可能（強力）.cursorrulesをGitで共有可能
向いているタスク「認証システム全体を移行して」「このAPIを全ページに適用して」「この関数を修正して」「バグをその場で直して」

実務での推奨使い分け：「考えながら書く」場面はCursor、「やることが決まっていて広範囲に実行する」場面はClaude Code。多くのシニアエンジニアがCursorでの素早い編集とClaude Codeでのエージェント的なタスク実行を組み合わせるハイブリッドワークフローを採用しています。

よくある質問（Q&A）

Q1. CLAUDE.mdに書いたことをClaudeが守ってくれないことがあります。どうすればいいですか？

「書いても守られない」場合、原因は2つに絞られます。①CLAUDE.mdが長すぎて重要な指示が埋もれている（精査・分散を推奨）、②「すべき」指示をHooksに移す必要がある（特に「必ず〇〇すること」は確定的なコードで強制）。Hooksで強制できるルールはHooksに、知識・文脈はCLAUDE.mdに、という分担が効果的です。

Q2. MCPサーバーを追加したら接続エラーが出ます。

90%以上のケースで原因は①Node.jsのバージョンが18未満（node -vで確認、Node.js 22推奨）、②環境変数が未設定（APIキー等がシェルの環境変数に存在するか確認）、③コマンドパスが間違っている（settings.jsonのargs形式を再確認）のどれかです。claude --verboseで起動すると詳細なエラーログが確認できます。

Q3. サブエージェントを使うとコストが2倍になりますか？

サブエージェントは別のコンテキストウィンドウで実行されるため、追加のAPIコールが発生します。ただし、サブエージェントを使わない場合でもメインのコンテキストウィンドウが大量のファイルで消費されるため、全体的なトークン消費はほぼ変わらない（場合によっては減る）ことが多いです。コストが心配な場合は、LLMOps記事で紹介したトークン監視ツールを活用してください。

Q4. チームでClaude Codeを使うとき、全員がAnthropicのAPIキーを持つ必要がありますか？

Claude Codeは個人単位でAnthropicアカウントと紐付きます。企業での一括払いはAnthropicのTeam/Enterpriseプランで対応しています。詳細はAnthropicサポートページでご確認ください。

Q5. Claude Codeは日本語のコードベースやコメントに対応していますか？

はい、完全対応しています。日本語のコメント・変数名・ドキュメントを問題なく処理できます。CLAUDE.mdを日本語で書いても機能します。ただし、コミットメッセージやPR本文を日本語で書きたい場合は、その旨をCLAUDE.mdに明記しておくとスムーズです。

まとめ——Claude Codeを「チームメンバー」として扱う

本記事で解説した上級機能を振り返ります。

第1章：CLAUDE.md設計——階層型配置・書くべきこと／書くべきでないことの仕分け・肥大化時のSkills/Hooksへの委譲。CLAUDE.mdはプロジェクトの「記憶」として、Gitにコミットして全員で共有することが基本です。

第2章：大規模プロジェクト管理——コンテキストウィンドウを意識したサブエージェント活用・Hooksによる確定的な品質ゲート・Git Worktreesによる並列開発・カスタムスラッシュコマンドによるワークフロー自動化。

第3章：MCPサーバー連携——GitHub・JIRA・DBとの連携で「チケット→実装→PR→ステータス更新」を自動化。stdioトランスポートから始め、チームスケールに合わせてSSE/HTTPへ移行。

第4章：チーム開発——共有設定ファイルのGit管理・GitHub ActionsへのClaude Code組み込み・権限設計。`git clone`した瞬間にチーム全員が同じClaude Code体験を得られる環境を作ることが目標です。

Claude Codeを最大限に活用しているチームに共通しているのは、「Claudeを便利なツール」として使うのではなく、「規約を知り、コンテキストを持ち、ツールを使える新しいチームメンバー」として扱うという視点です。

CLAUDE.mdの整備・Hooksによる品質ゲート・MCPによるツール連携は、そのための「オンボーディング」です。時間をかけて整備するほど、Claude Codeの生産性は指数的に上がっていきます。

参考リンク

免責事項：本記事は2026年3月時点の公開情報に基づく情報提供です。Claude Codeの機能・仕様・料金は頻繁に更新されるため、最新情報は公式ドキュメントでご確認ください。本記事内のコードスニペットは動作を保証するものではありません。ご自身の環境でのテストを推奨します。

コメント

タイトルとURLをコピーしました