チーム開発でClaude Codeを活用する5つのパターン｜CLAUDE.mdからHooksまで

個人利用とチーム利用の違い：組織として使うとはどういうことか

エンジニアが個人でClaude Codeを使う場合、その恩恵は個人の生産性向上に留まります。一方、チームが組織的に活用すると、以下の相乗効果が生まれます。

• ノウハウの共有：誰かが見つけた良いプロンプトがチーム全員に展開される
• 品質の均一化：ベテランの暗黙知をCLAUDE.mdに落とし込み、全員が同品質で作業できる
• 並列開発の加速：Git Worktreeを活用した複数フィーチャーの同時進行
• 標準化の自動施行：Hooksを使ってコーディング規約を人に依存せず強制できる

パターン1：CLAUDE.mdをチームの共有知識基盤として活用する

CLAUDE.mdは単なる「説明書」ではなく、チームの開発知識を蓄積する生きたドキュメントです。Gitで管理することで、チーム全員が同じコンテキストでClaude Codeを使えるようになります。

推奨するCLAUDE.mdの構成

# [プロジェクト名] - CLAUDE.md

## プロジェクト概要（Claude Code向け）
このリポジトリは[サービス名]のバックエンドAPIです。
メインの利用者: B2B企業のシステム管理者
重要: 破壊的変更は必ずマイグレーションスクリプトを用意すること

## 技術スタック（クイックリファレンス）
- Runtime: Node.js 20 (LTS)
- Framework: Fastify 4 + TypeScript 5
- ORM: Drizzle ORM
- Database: PostgreSQL 16
- Cache: Redis 7
- Test: Vitest + Supertest
- CI: GitHub Actions

## コマンド一覧
```
npm run dev          # 開発サーバー起動
npm test             # テスト実行
npm run test:watch   # watchモード
npm run lint         # ESLint + Prettier
npm run db:migrate   # DBマイグレーション実行
npm run db:studio    # Drizzle Studio起動
```

## 重要な規約（必ず守ること）
1. APIレスポンスは必ず `src/types/api.ts` の型を使う
2. エラーハンドリングは `src/utils/errors.ts` のクラスを使う
3. 認証が必要なエンドポイントには `authenticate` ミドルウェアを付ける
4. DBクエリは必ずトランザクション内で実行する（`withTransaction` を使う）
5. テストは `describe → it → expect` のネスト構造を統一する

## よくある作業パターン
### 新しいAPIエンドポイントを追加する場合
1. `src/routes/` に新ファイル作成
2. `src/routes/index.ts` に登録
3. OpenAPI仕様を `src/openapi/` に追加
4. 統合テストを `tests/api/` に作成

### DBスキーマを変更する場合
1. `src/db/schema.ts` を修正
2. `npm run db:generate` でマイグレーションファイル生成
3. マイグレーションの内容を必ずレビューしてからコミット

CLAUDE.md のチーム運用のポイント

• チームの規約変更はCLAUDE.mdを更新してからコミットする習慣をつける
• レビューで「このパターンをCLAUDE.mdに追加しよう」という会話を積極的にする
• サブディレクトリにもCLAUDE.mdを置けるため、マイクロサービス構成でも活用できる

パターン2：Hooksでチーム規約を自動施行する

Claude Code Hooksは、AIがアクションを実行する前後に任意のスクリプトを実行できる機能です。「Claude Codeが変更したら必ずlintを実行する」「危険なコマンドを実行しようとしたらブロックする」といったルールを自動化できます。

PreToolUse Hook：危険な操作の防止

# .claude/hooks/pre_bash.sh
# Claude Codeがbashコマンドを実行する前に呼ばれる

COMMAND="$1"

# 本番DBへの直接操作を防ぐ
if echo "$COMMAND" | grep -q "DATABASE_URL=postgres://prod"; then
    echo "ERROR: 本番DBへの直接コマンドは禁止されています" >&2
    exit 1
fi

# rm -rf の暴走防止
if echo "$COMMAND" | grep -qE "rm\s+-rf\s+/"; then
    echo "ERROR: ルートディレクトリへのrm -rfは禁止されています" >&2
    exit 1
fi

exit 0

PostToolUse Hook：変更後の自動品質チェック

# .claude/hooks/post_edit.sh
# Claude Codeがファイルを編集した後に呼ばれる

EDITED_FILE="$1"

# TypeScriptファイルが編集された場合、型チェックを実行
if [[ "$EDITED_FILE" == *.ts || "$EDITED_FILE" == *.tsx ]]; then
    echo "型チェックを実行中..."
    npx tsc --noEmit 2>&1
    if [ $? -ne 0 ]; then
        echo "WARNING: TypeScriptエラーが検出されました。修正が必要です。"
    fi
fi

# テストファイルが編集された場合、対応するテストを実行
if [[ "$EDITED_FILE" == *.test.ts ]]; then
    echo "テストを実行中..."
    npx vitest run "$EDITED_FILE"
fi

Hooksの設定ファイル

# .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/pre_bash.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/post_edit.sh"
          }
        ]
      }
    ]
  }
}

パターン3：Git Worktreeで並列開発を加速する

Git Worktreeを使うと、同一リポジトリを複数のディレクトリに展開できます。これをClaude Codeと組み合わせると、複数のフィーチャー開発を完全に並列で進めることが可能になります。

なぜGit Worktreeが必要か

通常のブランチ切り替えでは「stashする → ブランチを切り替える → stashを戻す」という手順が必要で、Claude Codeの実行中には特に不便です。Worktreeを使えば、複数のブランチを同時に別ターミナルで開いておけます。

# メインプロジェクトのディレクトリ
cd /path/to/my-project

# feature-Aのworktreeを作成
git worktree add ../my-project-feature-a feature/user-authentication

# feature-Bのworktreeを作成
git worktree add ../my-project-feature-b feature/payment-integration

# ターミナル1でfeature-A
cd ../my-project-feature-a
claude "ユーザー認証機能を実装して。JWT使用。テストも書いて"

# ターミナル2でfeature-B（同時に実行可能）
cd ../my-project-feature-b
claude "Stripe連携の決済機能を実装して"

Worktree活用の注意点

• それぞれのWorktreeで独立してClaude Codeが動くため、node_modulesは別々に必要
• DBマイグレーションが絡む場合は、競合に注意して順序を管理する
• 作業が終わったWorktreeは git worktree remove で忘れずに削除する

パターン4：コードレビューをClaude Codeで効率化する

レビュワーの時間を最も食う「機械的なチェック」（命名規則、テスト漏れ、セキュリティパターン等）をClaude Codeに任せ、人間は「設計や要件の適切性」に集中できます。

PRレビュー自動化スクリプト

#!/bin/bash
# scripts/ai-review.sh
# 使い方: ./scripts/ai-review.sh feature/my-feature

BRANCH=$1
BASE_BRANCH=${2:-main}

# 差分を取得
DIFF=$(git diff $BASE_BRANCH...$BRANCH)

# Claude Codeにレビューを依頼
claude --no-interactive << EOF
以下のPRの差分をレビューしてください。
チェック観点:
1. バグ・潜在的なエラー
2. セキュリティリスク（SQLインジェクション、XSS等）
3. テストの不足
4. パフォーマンス上の問題
5. CLAUDE.mdの規約違反

差分:
$DIFF

フォーマット: マークダウンで、重要度（Critical/Major/Minor）付きで指摘してください。
EOF

GitHub Actions との統合

# .github/workflows/ai-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    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
          ./scripts/ai-review.sh ${{ github.head_ref }} ${{ github.base_ref }} \
            > review-output.md

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

パターン5：ドキュメント自動生成ワークフローの構築

コードが更新されるたびにドキュメントが古くなる「ドキュメント腐敗」は、多くのチームが抱える問題です。Claude Codeを使ったドキュメント自動生成ワークフローで、この問題を根本から解決できます。

APIドキュメントの自動更新

# scripts/update-docs.sh
# コード変更があった場合にドキュメントを自動更新

CHANGED_FILES=$(git diff --name-only HEAD~1 HEAD | grep -E '\.(ts|js)$')

if [ -z "$CHANGED_FILES" ]; then
    echo "コード変更なし。ドキュメント更新をスキップします。"
    exit 0
fi

claude --no-interactive << EOF
以下のファイルが更新されました:
$CHANGED_FILES

各ファイルの変更内容を確認し、関連するAPIドキュメント（openapi/paths/）を更新してください。
また、README.mdの「変更履歴」セクションに今回の変更を1行で追記してください。
EOF

これら5つのパターンをすべて導入したチームでは、PRのレビュー時間が平均40%短縮され、ドキュメントの最新性が大幅に改善されたと報告するケースがあります。一度にすべて導入する必要はなく、チームの課題に応じて1つずつ試していくことをお勧めします。