Claude Code完全ガイド｜CLAUDE.md設計・hooks・カスタムコマンド・チーム開発運用まで徹底解説

# Node.js 18以上が必要
node --version

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

# バージョン確認
claude --version

# ログイン（ブラウザが開いてAnthropicアカウントで認証）
claude login

# インタラクティブモードで起動してコードレビューを依頼
claude
> src/api/users.py を見てセキュリティ上の問題を指摘してください

# 1回だけ実行
claude "package.jsonのdependenciesを最新バージョンに更新してください"

# パイプラインで使う（CI/CDでの利用例）
git diff HEAD~1 | claude -p "このdiffをレビューして問題点を箇条書きで返してください"

# CLAUDE.mdを自動生成
cd my-project
claude /init

# グローバル行動原則

## 自律実行の方針
- 小さな修正（typo・インポート追加・フォーマット）は確認なしで実行する
- ファイル削除・本番環境への操作・外部サービスへの送信は必ず確認を取る
- 複数ファイルにまたがる変更は、実行前に変更内容の概要を1〜2行で説明する

## 応答スタイル
- 回答は簡潔に。実行したことを長々と説明しない（diffを見れば分かる）
- 不明点があれば推測で進めず、1つだけ質問して確認する
- コードの説明はインラインコメントで行い、別途の解説文は最小限にする

## コーディング規範
- 新しいファイルを作る前に既存ファイルの修正で対応できないか検討する
- テストを追加する際は既存のテストスタイルに合わせる
- セキュリティリスク（インジェクション・認証不備・シークレットのハードコード）は必ず指摘する

## 確認が必要な操作
- git push / git force-push
- 本番DBへの直接操作
- 外部APIへの書き込み操作（メール送信・Slack通知等）

# プロジェクト概要
- **名称**: ECサイトバックエンドAPI
- **技術スタック**: Python / FastAPI / PostgreSQL / Redis / Docker
- **環境**: ローカル=Docker Compose, 本番=AWS ECS

## ディレクトリ構造
```
app/
  api/        # ルーター（エンドポイント定義）
  services/   # ビジネスロジック
  models/     # SQLAlchemyモデル
  schemas/    # Pydanticスキーマ
tests/        # pytest
migrations/   # Alembicマイグレーション
```

## 開発ルール
- ビジネスロジックは services/ に書く（api/ に書かない）
- DBアクセスは必ずリポジトリパターンを通す（services/ から直接クエリしない）
- 新しいエンドポイントには必ず対応するテストを追加する
- 環境変数は app/config.py の Settings クラスで管理する（os.environ直接参照禁止）

## よく使うコマンド
```bash
docker compose up -d          # 開発環境起動
pytest tests/ -v              # テスト実行
alembic upgrade head          # マイグレーション適用
alembic revision --autogenerate -m "説明"  # マイグレーション生成
```

## 注意事項
- migrations/ は自動生成後に必ず内容を確認してからコミットする
- tests/fixtures/ にテスト用のデータファクトリがある（新規テストはこれを使う）
- Redis接続は app/cache.py の get_redis() を使う

# データベース操作ルール

このルールはDBマイグレーションや直接SQL操作を行うときに適用されます。

## マイグレーション
- DROP TABLE / DROP COLUMN は必ず人間の確認を取る
- カラム追加は nullable または DEFAULT 値を持たせてゼロダウンタイムを確保する
- インデックス作成は CONCURRENTLY オプションを付ける（本番DB向け）

## クエリ
- N+1問題になりそうな箇所は指摘してeager loadingを提案する
- 全件取得（LIMIT なし）は禁止。必ずページネーションを実装する

# フロントエンドルール（frontend/ ディレクトリ内で適用）

## コンポーネント設計
- 1ファイル1コンポーネント。200行を超えたら分割を提案する
- propsの型は必ず明示する
- API呼び出しはカスタムフックに分離する（コンポーネント内に直接書かない）

## アクセシビリティ
- インタラクティブ要素には aria-label または aria-labelledby を付ける
- img タグには必ず alt 属性を書く

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "echo '? ファイル編集を検出'"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '? コマンド実行前'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '✅ Claude Codeの応答が完了しました'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "cd $CLAUDE_PROJECT_DIR && npm run lint --silent 2>&1 | head -20 || true"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo "実行予定のコマンド: $CLAUDE_TOOL_INPUT" >> ~/.claude/command-log.txt"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification "Claude Codeの応答が完了しました" with title "Claude Code"' 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

.claude/
  commands/
    review.md          # /project:review で呼び出す
    test-gen.md        # /project:test-gen で呼び出す
    changelog.md       # /project:changelog で呼び出す
    deploy-check.md    # /project:deploy-check で呼び出す
  settings.json
  rules/
    database.md

---
description: コードレビューを実行して問題点をリストアップする
---

以下の観点でコードレビューを行い、問題点を重大度（critical/major/minor）付きで箇条書きにしてください。

**レビュー観点**
1. バグ・ロジックエラー（変数の未初期化・境界値の扱い・エラー処理の漏れ）
2. セキュリティ（インジェクション・認証・シークレットのハードコード）
3. パフォーマンス（N+1・無駄なループ・不要なDB呼び出し）
4. 可読性・保守性（命名・重複コード・関数の肥大化）
5. テスト（カバレッジの欠落・エッジケースの見落とし）

問題がない観点は省略し、良い点が目立つ場合は最後に「良い点」として1〜2点添えてください。

$ARGUMENTS

---
description: 指定したファイルのユニットテストを自動生成する
---

$ARGUMENTS に指定されたファイルのユニットテストを生成してください。

**要件**
- 既存のテストファイルがある場合は、そのスタイル・命名規則に合わせる
- 正常系・異常系・エッジケースを網羅する
- モック・スタブが必要な箇所は適切に設定する
- テストの意図がわかるようにdescribeとitの説明文を日本語で書く

まず対象ファイルを読んでから、テストを生成してください。

---
description: 直近のコミット履歴からCHANGELOGエントリを生成する
---

以下のgit logを取得して、ユーザー向けのCHANGELOGエントリを生成してください。

```bash
git log --oneline -20
```

**フォーマット**
## [バージョン] - YYYY-MM-DD

### 追加
- 新機能の説明（ユーザー視点で）

### 変更
- 変更内容

### 修正
- バグ修正の説明

技術的な内部実装の詳細ではなく、ユーザーやチームメンバーが理解できる言葉で書いてください。

# カスタムコマンドを呼び出す
/project:review src/api/auth.py
/project:test-gen src/services/payment.py
/project:changelog

# 引数なしで呼び出す
/project:deploy-check

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/user/projects"
      ]
    },
    "brave-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

# Claude Code起動時にMCPの接続状態を確認
claude
> /mcp

# MCPツールを使う（自然な日本語で指示するだけ）
> GitHubのissue一覧を取得して、未対応のバグ系issueを優先度順に整理してください
> PostgreSQLのusersテーブルの構造を確認して、インデックスの最適化案を提案してください

.claude/
  settings.json          # Git管理（MCPサーバー定義・hooks設定）
  settings.local.json    # .gitignore対象（個人のAPIキー・ローカル設定）
  commands/
    review.md
    test-gen.md
    changelog.md
    deploy-check.md
  rules/
    database.md
    security.md
    api-design.md
CLAUDE.md                # Git管理（プロジェクト概要・開発ルール）

# Claude Code個人設定（APIキー等）
.claude/settings.local.json

# Claude Codeのキャッシュ
.claude/cache/

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "cd $CLAUDE_PROJECT_DIR && npm run lint --silent 2>&1 | tail -5 || true"
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)"
    ]
  }
}

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Edit(*)",
      "Write(src/**)",
      "Bash(npm run *)",
      "Bash(python -m pytest *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(rm -rf *)",
      "Bash(DROP *)",
      "WebFetch(https://internal-api.*)"
    ]
  }
}

claude "src/services/ 以下のすべてのファイルを確認して、例外処理が統一されていない箇所を洗い出し、
app/exceptions.py で定義されているカスタム例外クラスを使うよう修正してください。
修正前に変更ファイルの一覧を提示してください。"

claude "以下の仕様でAPIエンドポイントを実装してください。
まずテストを書き、テストがパスするように実装を進めてください。

仕様:
- POST /api/v1/users
- リクエスト: { name, email, role }
- メールの重複チェック（409を返す）
- roleは admin/user/viewer のいずれか（バリデーション）
- 成功時は作成したユーザーをJSONで返す（201）"

name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run AI Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git diff origin/main...HEAD > /tmp/pr-diff.txt
          REVIEW=$(cat /tmp/pr-diff.txt | claude -p             "このPRのdiffをレビューして、critical/majorの問題のみ箇条書きで報告してください。
            問題がなければ「問題なし」とだけ返してください。")
          echo "## AI Code Review" >> $GITHUB_STEP_SUMMARY
          echo "$REVIEW" >> $GITHUB_STEP_SUMMARY

# コミットフックに組み込む例（.git/hooks/pre-commit）
#!/bin/bash

# APIエンドポイントファイルが変更された場合、ドキュメントを自動更新
if git diff --cached --name-only | grep -q "src/api/"; then
  echo "APIファイルの変更を検出。ドキュメントを更新します..."
  claude -p "src/api/ 以下の変更を確認して、docs/api-reference.md を最新の状態に更新してください。
  エンドポイントの追加・変更・削除を反映してください。" --no-interactive
  git add docs/api-reference.md
fi