Claude Code設定のベストプラクティス — CLAUDE.md・ルール・レビューエージェント完全ガイド

# CLAUDE.md

## Tech Stack
- Framework: Astro 5 (静的サイト生成)
- UI: React (Islands Architecture)
- Styling: Tailwind CSS v4
- Deploy: Vercel

## Commands
npm run dev        # 開発サーバー
npm run build      # 本番ビルド
npm run test       # テスト実行

## Architecture
- src/pages/       - ルーティング
- src/components/  - UIコンポーネント
- src/content/     - コンテンツ（.astroファイル）
- src/layouts/     - レイアウト

## Conventions
- 記事はHTML + Tailwind CSS（マークダウン不使用）
- クイズは必ず3〜5問含める
- コンポーネントはnamed exportを使用

.claude/rules/
├── frontend.md        # フロントエンド規約
├── api.md             # API開発ルール
├── testing.md         # テスト方針
├── security.md        # セキュリティルール
└── content.md         # コンテンツ生成ルール

---
globs: "src/components/**/*.tsx"
---

# Reactコンポーネントルール

- propsにはTypeScript型定義を必ず付与する
- useEffectの依存配列は明示的に指定する
- client:load は即座に操作が必要な要素のみに使用する
- client:visible をスクロール下部の要素に優先的に使用する

---
globs: "src/content/**/*.astro"
---

# コンテンツ生成ルール

- 本文はHTML + Tailwind CSSで記述（マークダウン不使用）
- 見出し階層: h2 → h3 → h4（h1はレイアウト側で出力）
- 各記事の末尾にクイズ3〜5問を含める
- ビジュアル要素を最低2種類使用する

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(sudo:*)",
      "Bash(rm -rf:*)"
    ],
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Bash(npm run build)",
      "Read(src/**)",
      "Edit(src/**)",
      "Write(src/content/**)"
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|DROP TABLE|--force' && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}

---
name: deploy-production
description: >
  プロダクション環境へのデプロイを実行するスキル。
  「デプロイして」「本番に反映」「deploy」「リリース」
  などのリクエストで発動。
allowed-tools: Bash, Read, Glob
---

# プロダクションデプロイ

## 前提条件チェック
1. mainブランチにいることを確認
2. 未コミットの変更がないことを確認

## 手順
1. `npm run build` でビルド
2. `npm run test` でテスト実行
3. テスト成功後、`vercel --prod` でデプロイ
4. デプロイURLを報告

# 悪い例 — 発動しにくい
description: ダッシュボードを作成するスキル

# 良い例 — トリガーワードを明示
description: >
  ダッシュボードを作成するスキル。
  「ダッシュボード」「データ可視化」「メトリクス表示」
  「グラフを作って」「分析画面」などユーザーがデータの
  可視化に言及した場合は必ず使用すること。

# Review Rules

## 必ずチェックする項目
- 新しいAPIエンドポイントには統合テストがあること
- DBマイグレーションは後方互換であること
- 環境変数の追加は .env.example にも反映されていること
- セキュリティ関連の変更はセキュリティチームのレビューを必須にする

## コードスタイル
- 関数は50行以内を推奨
- ネストは3段階まで
- 早期リターンを推奨

## スキップする項目
- /gen/ 配下の自動生成ファイルのフォーマット指摘
- フォーマットのみの変更
- テストファイルの命名規約（柔軟に許容）

.claude/agents/
├── security-reviewer.md    # セキュリティレビュー
├── test-writer.md          # テスト自動生成
└── doc-writer.md           # ドキュメント生成

---
name: security-reviewer
description: セキュリティ観点でコードをレビューする
tools: Read, Glob, Grep, WebSearch
model: sonnet
---

# Security Reviewer

コード変更に対してOWASP Top 10の観点でチェックする:
- SQLインジェクション・NoSQLインジェクション
- XSS（反射型・格納型・DOM型）
- 認証・認可の不備
- シークレットのハードコード
- 依存関係の脆弱性

重大度の高い問題を発見した場合は、修正案も提示する。

# プロジェクト全体の構成
my-project/
├── CLAUDE.md                    # チーム共有ルール（Git管理）
├── CLAUDE.local.md              # 個人設定（.gitignore）
├── REVIEW.md                    # レビュー専用ルール（Git管理）
├── .claude/
│   ├── settings.json            # 権限・Hooks（Git管理）
│   ├── settings.local.json      # 個人設定（.gitignore）
│   ├── rules/
│   │   ├── frontend.md          # フロントエンド規約（globs付き）
│   │   ├── api.md               # API規約（globs付き）
│   │   └── security.md          # セキュリティルール（常時適用）
│   ├── skills/
│   │   ├── deploy/SKILL.md      # デプロイスキル
│   │   └── generate/SKILL.md    # コード生成スキル
│   └── agents/
│       ├── security-reviewer.md # セキュリティレビュー
│       └── test-writer.md       # テスト生成
└── src/
    └── ...