AI駆動開発アーキテクチャ

このページでは、Claude Code の全機能を組み合わせて実際のプロジェクトにどう適用するかを、基幹システムリプレイスを題材にした実践ガイドとして解説します。各機能の設定ファイル全文を掲載しているため、このページを見ながらそのまま設定できます。

AI駆動開発とは

AI駆動開発とは、AIがコードを書き、人間が設計・レビュー・意思決定を担う開発スタイルです。従来の「人間が全てのコードを書く」開発とは、役割分担が根本的に異なります。

Claude Code が担う役割

Claude Code は AI駆動開発において、以下の役割を担います。

• コード生成 -- Issue の内容を読み取り、規約に沿ったコードを自動生成
• コードレビュー -- セキュリティ、パフォーマンス、規約準拠を複数の観点で自動チェック
• テスト作成 -- 実装に対応するユニットテスト・E2Eテストを自動生成
• ドキュメント生成 -- コードから API 仕様書やコメントを自動生成
• Issue 対応 -- Issue の分析から実装、PR 作成までの一気通貫ワークフロー

なぜ AI駆動開発にアーキテクチャが必要か

プロジェクト前提（基幹システムリプレイス）

技術スタック

レイヤー	技術	用途
フロントエンド	Next.js 14 (App Router)	Web アプリケーション
フロントエンド	React 18 + Tailwind CSS	UI コンポーネント・スタイリング
バックエンド	NestJS + Prisma ORM	API サーバー
データベース	PostgreSQL 16	メインデータストア
キャッシュ	Redis 7	セッション・キャッシュ
ストレージ	Amazon S3	ファイルアップロード
インフラ	AWS ECS (Fargate) + Terraform	コンテナオーケストレーション・IaC
CI/CD	GitHub Actions	自動テスト・デプロイ
モノレポ	Turborepo + pnpm	ワークスペース管理

[フロントエンド]          [バックエンド]              [インフラ]
Next.js (App Router)     NestJS + Prisma            AWS ECS (Fargate)
React 18                 PostgreSQL 16              Terraform
Tailwind CSS             Redis 7 (Cache)            GitHub Actions
                         S3 (ファイル)

グランドデザイン全体像

Claude Code の各機能がプロジェクトのどの課題を解決するか、全体のマッピングを示します。

各機能が「なぜ必要か」一覧

機能	解決する課題	なぜこの機能で解決するのか
CLAUDE.md	チーム間の認識のズレ	セッション開始時に自動読込されるため、全員が同じルールで作業できる
Rules	コーディング規約の形骸化	ファイル操作時に自動適用され、AIがルール違反を自動検出する
Settings	危険な操作の制限	権限設定で物理的にブロックし、ルール違反を仕組みで防ぐ
Hooks	品質チェックの漏れ	ツール実行前後に自動発火し、人間の注意力に依存しない
Commands	定型作業の属人化	/コマンド名 で誰でも同じ品質の作業を実行できる
Skills	専門知識の属人化	ノウハウを SKILL.md に形式知化し、AIが自動で適用する
Agents	レビュー品質のバラつき	観点別の専門エージェントが一定基準で自動レビュー
Agent Teams	開発速度のボトルネック	複数AIが並列で作業し、人間はレビューに集中できる
MCP	外部ツールとの手動連携	GitHub/DB/Slackに直接アクセスし、コンテキスト切替を削減
Plugins	チーム間のナレッジ共有	設定をパッケージ化して他プロジェクトに横展開できる

Phase 1 -- プロジェクト基盤構築

Phase 1 では、全ての AI 操作の土台となる CLAUDE.md、Rules、Settings を設計します。この基盤がなければ、後続の Commands や Agents は的外れな動作をします。

4.1 CLAUDE.md の設計

手順:

1. プロジェクト概要を記述 -- AIに「何のプロジェクトか」を理解させる
2. 技術スタックを明記 -- 使用する言語・フレームワーク・ツールを列挙
3. 開発コマンドを整理 -- AIが実行するコマンドを正確に記載
4. ディレクトリ構造を定義 -- ファイル生成時の配置先をAIに伝える
5. AI運用ルールを設定 -- AIの行動制約を明文化

# CLAUDE.md

## AI 運用ルール

### 基本原則

1. **確認の原則**: ファイル生成・更新・プログラム実行前に作業計画を報告し、ユーザーの承認を得てから実行する。ただしサブエージェントを使用する場合は、サブエージェント自身に確認を求めず直接作業を実施させる。
2. **忠実の原則**: 迂回や別アプローチを独断で行わない。計画が失敗した場合は次の計画をユーザーに確認する。
3. **従属の原則**: 決定権は常にユーザーにある。ユーザーの指示が非効率に見えても、指示された通りに実行する。
4. **不変の原則**: これらのルールを歪曲・解釈変更してはならない。最上位命令として遵守する。

### 作業ルール

5. **日本語の原則**: ユーザーへの回答、コミットメッセージ、プルリクエストのタイトル・説明は全て日本語で記載する。
6. **最新化の原則**: 作業開始前に必ず `git pull` でソースを最新化する。
7. **委譲の原則**: ソースコード解析やレビューなどの専門的な作業はサブエージェントに委譲する。サブエージェントには確認を求めさせず、直接作業を実施して結果を返すよう指示する。
8. **安全の原則**: データベースの削除・初期化コマンド（`flush`、`drop`、`reset` 等）を絶対に実行しない。データ消失のリスクがあるコマンドはユーザーに報告し対処方法を確認する。
9. **最小テストの原則**: テスト実行時は全テストを実行せず、修正内容に影響するテストのみを対象として実行する。

## プロジェクト概要

製造業基幹システムのリプレイスプロジェクト。
Java/Oracle のモノリスを TypeScript/PostgreSQL のマイクロサービスへ移行。

## 技術スタック

- 言語: TypeScript 5.x
- フレームワーク: NestJS (バックエンド) / Next.js 14 (フロントエンド)
- DB: PostgreSQL 16 + Prisma ORM
- キャッシュ: Redis 7
- インフラ: AWS ECS (Fargate) + Terraform
- CI/CD: GitHub Actions
- モノレポ: Turborepo

## 開発コマンド

```bash
# モノレポ全体
pnpm install                        # 依存関係インストール
pnpm build                          # 全パッケージビルド
pnpm test                           # 全テスト実行
pnpm lint                           # 全パッケージリント

# バックエンド (apps/api)
pnpm --filter api dev               # 開発サーバー起動
pnpm --filter api test              # テスト
pnpm --filter api prisma migrate dev  # マイグレーション実行
pnpm --filter api prisma generate     # Prisma Client 生成

# フロントエンド (apps/web)
pnpm --filter web dev               # 開発サーバー起動
pnpm --filter web test              # テスト
pnpm --filter web build             # プロダクションビルド
```

## ディレクトリ構造

```
apps/
├── api/                 # NestJS バックエンド
│   ├── src/
│   │   ├── modules/     # 機能モジュール
│   │   ├── common/      # 共通ユーティリティ
│   │   └── prisma/      # Prisma スキーマ・マイグレーション
│   └── test/            # E2E テスト
├── web/                 # Next.js フロントエンド
│   ├── app/             # App Router ページ
│   ├── components/      # UI コンポーネント
│   └── lib/             # ユーティリティ
└── packages/
    ├── shared/          # 共有型定義
    ├── ui/              # 共有 UI ライブラリ
    └── config/          # 共有設定
```

## コーディング規約

- インデント: 2スペース
- 命名: キャメルケース(変数・関数)、パスカルケース(クラス・型・コンポーネント)
- コミット: Conventional Commits + 日本語
- テスト: 新機能には必ずテスト追加

## 注意事項

- 本番DB (production) への直接接続禁止
- .env ファイルのコミット禁止
- main ブランチへの直接プッシュ禁止
- マイグレーションは必ず開発環境で検証後に適用

4.2 Rules の設計

手順:

1. 全体適用ルールを整理（セキュリティ、Git ワークフロー） -- プロジェクト全体で常に守るべきルール
2. パス別ルールを設計（API開発、フロントエンド、DB操作） -- 担当領域ごとに異なるルール
3. テストルールを分離 -- テストファイル操作時のみ適用

（a）セキュリティルール -- 常時適用

# セキュリティルール

- DB削除コマンド（DROP, TRUNCATE, DELETE without WHERE）を絶対に実行しない
- 本番環境の接続文字列をソースコードに含めない
- APIキー・パスワードは環境変数経由で取得する
- SQLインジェクション対策: 必ず Prisma ORM を使用し、$queryRawUnsafe を禁止
- XSS対策: dangerouslySetInnerHTML の使用禁止
- CORS設定: 許可オリジンをホワイトリストで管理

（b）API 開発ルール -- パス別ルール

---
paths:
  - "apps/api/**/*.ts"
---

# API 開発ルール

- 全エンドポイントに認証ガード (@UseGuards) を実装
- リクエストは class-validator の DTO でバリデーション
- レスポンスは統一フォーマット { data, meta, error }
- ページネーションは cursor ベースで実装
- エラーは NestJS の Exception Filter で統一処理
- N+1 問題を防ぐため Prisma の include/select を明示

（c）フロントエンド開発ルール -- パス別ルール

---
paths:
  - "apps/web/**/*.{ts,tsx}"
---

# フロントエンド開発ルール

- コンポーネントは Server Component をデフォルトとし、必要な部分だけ "use client"
- 状態管理は React の useState/useReducer を基本とし、グローバル状態は最小限に
- API 呼び出しは Server Actions または React Query を使用
- スタイリングは Tailwind CSS のユーティリティクラスを使用
- アクセシビリティ: aria-label, role 属性を適切に設定

（d）データベース操作ルール -- パス別ルール

---
paths:
  - "apps/api/src/prisma/**/*"
  - "**/*.prisma"
---

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

- スキーマ変更は必ず Prisma migrate で管理し、手動 SQL を実行しない
- テーブル名は英語スネークケース複数形 (users, order_items)
- カラム名は英語スネークケース (created_at, updated_by)
- 全テーブルに id, created_at, updated_at, deleted_at を含める（ソフトデリート）
- インデックスは WHERE 句で頻繁に使うカラムに設定
- マイグレーションファイルは手動編集禁止。prisma migrate dev で生成

4.3 Settings の設計

手順:

1. チーム共有の許可・拒否ルールを .claude/settings.json に定義
2. 個人用のトークン設定を .claude/settings.local.json に分離（Git管理外）

（a）チーム共有設定

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Bash(pnpm:*)",
      "Bash(npm:*)",
      "Bash(git:*)",
      "Bash(gh:*)",
      "Bash(prisma:*)",
      "Bash(turbo:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(DROP:*)",
      "Bash(TRUNCATE:*)",
      "Bash(psql*production*)"
    ]
  },
  "env": {
    "NODE_ENV": "development",
    "DATABASE_URL": "postgresql://dev:dev@localhost:5432/app_dev"
  }
}

（b）個人用設定（Git管理外）

{
  "permissions": {
    "allow": [
      "mcp__github"
    ]
  },
  "env": {
    "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
  }
}

Phase 2 -- 開発ワークフロー構築

Phase 2 では、日々の開発作業を効率化する Commands、Skills、Hooks を設計します。Phase 1 の基盤（CLAUDE.md, Rules, Settings）の上に構築することで、これらが正しく機能します。

5.1 Commands の設計

（a）/dev-issue -- Issue ベースの実装コマンド

---
description: GitHub Issue に基づいて実装からPR作成まで一括実行
allowed-tools: Bash, Read, Edit, Write, Agent
---

# Issue 実装コマンド

$ARGUMENTS で指定された GitHub Issue に基づいて、以下の手順で実装を行ってください。

## 手順

### 1. 準備
- `git checkout main && git pull origin main` でソースを最新化
- `gh issue view $ARGUMENTS` で Issue の内容を確認
- Issue のタイトルと本文から実装内容を把握

### 2. ブランチ作成
- Issue 番号とタイトルからブランチ名を生成
- 形式: `feature/#-<概要の英語スラッグ>`
- 例: `feature/#42-user-authentication`
- `git checkout -b <ブランチ名>` でブランチ作成

### 3. 実装
- CLAUDE.md の技術スタック・ディレクトリ構造に従ってコードを生成
- .claude/rules/ のルールを参照し、コーディング規約に準拠
- 実装が大きい場合は、論理的な単位でコミットを分割

### 4. テスト
- 実装に対応するユニットテストを作成
- `pnpm --filter <パッケージ名> test` で影響範囲のテストを実行
- テストが全て通ることを確認

### 5. PR 作成
- コミットメッセージは日本語で記述（例: `#42 ユーザー認証のログイン機能を実装`）
- `gh pr create` で PR を作成
- PR タイトル・説明は日本語で記述
- 説明に `Closes #` を含める

## 注意事項
- 不明点がある場合はユーザーに確認する
- セキュリティルール（security.md）を必ず遵守する
- 本番環境に影響する変更は必ずユーザーに報告する

（b）/db-migrate -- マイグレーション実行コマンド

---
description: Prisma マイグレーションを安全に実行する
allowed-tools: Bash, Read
---

# DB マイグレーション実行

Prisma マイグレーションを安全に実行します。以下の手順に従ってください。

## 手順

1. 現在のマイグレーション状態を確認
   ```bash
   pnpm --filter api prisma migrate status
   ```

2. 差分があれば開発DBに適用
   ```bash
   pnpm --filter api prisma migrate dev
   ```

3. Prisma Client を再生成
   ```bash
   pnpm --filter api prisma generate
   ```

4. 型チェック
   ```bash
   pnpm --filter api tsc --noEmit
   ```

5. テスト実行
   ```bash
   pnpm --filter api test
   ```

## 注意事項
- 本番DBへの直接マイグレーションは絶対に実行しない
- マイグレーションファイルの手動編集禁止
- データ消失の可能性がある変更（カラム削除等）は必ずユーザーに確認
- マイグレーション前に必ず現在の状態を確認する

（c）/api-scaffold -- API エンドポイント雛形生成

---
description: NestJS の CRUD エンドポイント雛形を生成
allowed-tools: Bash, Read, Edit, Write
---

# API エンドポイント雛形生成

$ARGUMENTS のリソース名で以下のファイルを生成してください。

## 生成するファイル

1. **Module** - `apps/api/src/modules/$ARGUMENTS/$ARGUMENTS.module.ts`
2. **Controller** - `apps/api/src/modules/$ARGUMENTS/$ARGUMENTS.controller.ts`
   - CRUD エンドポイント (GET /一覧, GET /:id, POST /, PATCH /:id, DELETE /:id)
3. **Service** - `apps/api/src/modules/$ARGUMENTS/$ARGUMENTS.service.ts`
   - ビジネスロジック（Prisma 経由の DB 操作）
4. **DTO** - `apps/api/src/modules/$ARGUMENTS/dto/`
   - `create-$ARGUMENTS.dto.ts` - 作成リクエスト
   - `update-$ARGUMENTS.dto.ts` - 更新リクエスト
5. **Entity** - `apps/api/src/modules/$ARGUMENTS/entities/$ARGUMENTS.entity.ts`
6. **テスト**
   - `apps/api/src/modules/$ARGUMENTS/$ARGUMENTS.controller.spec.ts`
   - `apps/api/src/modules/$ARGUMENTS/$ARGUMENTS.service.spec.ts`

## 規約

- .claude/rules/coding-standards.md のコーディング規約に準拠
- .claude/rules/api-development.md の API 開発ルールに準拠
- 全エンドポイントに認証ガード (@UseGuards(JwtAuthGuard)) を設定
- DTO に class-validator のバリデーションデコレータを付与
- Controller に Swagger デコレータ (@ApiTags, @ApiOperation, @ApiResponse) を付与
- Service のメソッドにはエラーハンドリングを含める
- レスポンスは統一フォーマット { data, meta, error } に準拠

5.2 Skills の設計

（a）/explain-code -- コード解説（自動呼び出し可）

---
name: explain-code
description: コードの仕組みを図解と例え話で解説する
argument-hint: <ファイルパス or コードスニペット>
---

# コード解説スキル

指定されたコードを以下の観点で解説してください。

## 解説の流れ

1. **概要** - このコードは何をするものか（1-2文で）
2. **処理フロー** - 主要な処理の流れを番号付きリストで
3. **図解** - ASCII art でデータフローや処理の流れを視覚化
4. **例え話** - 技術に詳しくない人にも伝わる日常的な例え
5. **重要なポイント** - パフォーマンス、セキュリティ、保守性の観点

## 注意事項
- 専門用語には必ず簡単な説明を付記する
- 「なぜそう書かれているか」の背景・理由も説明する
- プロジェクトの CLAUDE.md、Rules を参照して文脈に即した解説をする

（b）/gen-doc -- ドキュメント生成

---
name: gen-doc
description: コードからドキュメントを自動生成する
argument-hint: <対象ディレクトリ or ファイルパス>
disable-model-invocation: true
---

# ドキュメント生成スキル

指定されたコードからドキュメントを自動生成してください。

## 生成するドキュメント

### モジュールの場合
- モジュール概要
- 提供する API エンドポイント一覧
- 各エンドポイントのリクエスト・レスポンス例
- 依存関係

### 関数・クラスの場合
- JSDoc 形式のコメント
- パラメータの説明
- 戻り値の説明
- 使用例

## 注意事項
- 既存のドキュメントがある場合は上書きではなく更新する
- コードの実装詳細ではなく「使い方」を中心に記述する

（c）/gen-api-spec -- OpenAPI 仕様書生成（基幹システム特有）

---
name: gen-api-spec
description: Prisma スキーマと NestJS コントローラーから OpenAPI 仕様書を生成
argument-hint: <モジュール名>
disable-model-invocation: true
---

# OpenAPI 仕様書生成スキル

指定されたモジュールの Prisma スキーマと NestJS コントローラーを解析し、OpenAPI 仕様書を生成してください。

## 手順

1. `apps/api/src/prisma/schema.prisma` からモデル定義を取得
2. `apps/api/src/modules/<モジュール名>/` 配下のコントローラーを解析
3. DTO のバリデーションルールからリクエストスキーマを生成
4. レスポンスの型定義からレスポンススキーマを生成
5. OpenAPI 3.0 形式の YAML を生成

## 生成フォーマット

```yaml
openapi: 3.0.0
info:
  title: <モジュール名> API
  version: 1.0.0
paths:
  /<リソース名>:
    get:
      summary: 一覧取得
      parameters:
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
```

## 注意事項
- Prisma スキーマの deleted_at カラムがある場合、ソフトデリート対応の仕様を含める
- 認証が必要なエンドポイントには securitySchemes を設定
- cursor ベースのページネーションを正しく記述

5.3 Hooks の設計

Hooks は .claude/settings.json の hooks セクションに定義します。以下に、基幹システムリプレイスに必要な3つのフックを示します。

（a）危険コマンドブロック（PreToolUse / Bash）

Bash ツールが実行される前に発火し、危険なコマンドを含む場合はブロックします。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qiE '(DROP|TRUNCATE|DELETE FROM|rm -rf|--force|production)'; then echo 'BLOCKED: 危険なコマンドが検出されました' >&2; exit 1; fi"
          }
        ]
      }
    ]
  }
}

（b）自動フォーマット（PostToolUse / Write, Edit）

ファイルの書き込み・編集後に自動でフォーマッターを実行し、コードスタイルを統一します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

（c）マイグレーションファイル保護（PreToolUse / Edit）

Prisma が生成したマイグレーションファイルの手動編集を物理的にブロックします。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_FILE_PATH\" | grep -q 'prisma/migrations/'; then echo 'BLOCKED: マイグレーションファイルの手動編集は禁止されています' >&2; exit 1; fi"
          }
        ]
      }
    ]
  }
}

Hooks の統合設定例

上記3つの Hooks を統合した settings.json の全体像です。

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Bash(pnpm:*)",
      "Bash(npm:*)",
      "Bash(git:*)",
      "Bash(gh:*)",
      "Bash(prisma:*)",
      "Bash(turbo:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(DROP:*)",
      "Bash(TRUNCATE:*)",
      "Bash(psql*production*)"
    ]
  },
  "env": {
    "NODE_ENV": "development",
    "DATABASE_URL": "postgresql://dev:dev@localhost:5432/app_dev"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qiE '(DROP|TRUNCATE|DELETE FROM|rm -rf|--force|production)'; then echo 'BLOCKED: 危険なコマンドが検出されました' >&2; exit 1; fi"
          }
        ]
      },
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_FILE_PATH\" | grep -q 'prisma/migrations/'; then echo 'BLOCKED: マイグレーションファイルの手動編集は禁止されています' >&2; exit 1; fi"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Phase 3 -- 品質・セキュリティ体制

Phase 3 では、コードの品質を自動で担保する Agents と、並列作業で開発速度を加速する Agent Teams を設計します。

6.1 Agents の設計

（a）code-reviewer -- コード品質レビュー

---
name: code-reviewer
description: コード品質の総合レビューを実施
model: claude-sonnet-4-6
tools: Read, Grep, Glob
---

# コード品質レビュー

## あなたの役割
コードの品質を総合的にレビューする専門エージェントです。
確認を求めず、直接レビューを実施して結果を返してください。

## チェック観点

1. **コーディング規約** - .claude/rules/coding-standards.md に準拠しているか
2. **命名規則** - 変数・関数・クラスの命名が適切か
3. **関数設計** - 単一責務原則、50行以内、ネスト3段以内
4. **エラー処理** - 空の catch ブロック、握りつぶし
5. **DRY 原則** - 重複コードの有無
6. **YAGNI 原則** - 不要な先回り実装
7. **インポート** - 未使用インポート、順序の統一
8. **型安全性** - any 型の使用、型アサーションの妥当性

## 出力フォーマット

各指摘は以下の形式で報告:
- 指摘レベル: 🔴 Critical / 🟡 Warning / 🔵 Suggestion
- ファイルパス・行番号
- 問題の説明
- 修正コード例

（b）security-reviewer -- セキュリティ監査

---
name: security-reviewer
description: セキュリティ観点でのコードレビューを実施
model: claude-sonnet-4-6
tools: Read, Grep, Glob
---

# セキュリティレビュー

## あなたの役割
セキュリティ脆弱性を検出する専門エージェントです。
確認を求めず、直接レビューを実施して結果を返してください。

## チェック観点

1. **認証・認可** - 全エンドポイントに認証ガードがあるか
2. **SQLインジェクション** - $queryRawUnsafe の使用、パラメータバインディング
3. **XSS** - dangerouslySetInnerHTML、ユーザー入力の直接出力
4. **CSRF** - トークン検証の有無
5. **機密情報** - ハードコードされた API キー、パスワード、接続文字列
6. **入力バリデーション** - DTO のバリデーション漏れ
7. **レスポンス** - 不要な機密データの露出
8. **ログ** - パスワード・トークンのログ出力
9. **ファイルアップロード** - 拡張子・サイズ制限
10. **依存関係** - 既知の脆弱性を持つパッケージ

## 出力フォーマット

各指摘は以下の形式で報告:
- 深刻度: 🔴 Critical / 🟡 Warning / 🔵 Info
- 脆弱性の種類（OWASP Top 10 分類）
- ファイルパス・行番号
- 攻撃シナリオの説明
- 修正コード例

（c）performance-reviewer -- パフォーマンスレビュー

---
name: performance-reviewer
description: パフォーマンス観点でのコードレビューを実施
model: claude-sonnet-4-6
tools: Read, Grep, Glob
---

# パフォーマンスレビュー

## あなたの役割
パフォーマンスの問題を検出する専門エージェントです。
確認を求めず、直接レビューを実施して結果を返してください。

## チェック観点

1. **N+1 クエリ** - Prisma の include/select の適切性。ループ内での DB アクセス
2. **不要なデータフェッチ** - SELECT * 相当の操作。必要なカラムだけ select しているか
3. **インデックス** - WHERE, JOIN, ORDER BY で使うカラムにインデックスがあるか
4. **メモリリーク** - 大量データの一括読み込み。ストリーム処理の必要性
5. **キャッシュ戦略** - Redis の TTL 設定の妥当性。キャッシュすべきデータの判断
6. **バッチ処理** - 大量データ処理のチャンクサイズ。Prisma の createMany/updateMany
7. **非同期処理** - Promise.all の並列度。不要な await の直列化
8. **フロントエンド** - 不要な再レンダリング。React.memo/useMemo の適切な使用
9. **バンドルサイズ** - 不要なライブラリのインポート。Tree shaking の効果

## 出力フォーマット

各指摘は以下の形式で報告:
- 影響度: 🔴 高 / 🟡 中 / 🔵 低
- 問題の種類
- ファイルパス・行番号
- 現在の推定パフォーマンス影響
- 改善案とコード例

（d）db-reviewer -- DB設計レビュー

---
name: db-reviewer
description: データベース設計とマイグレーションのレビュー
model: claude-sonnet-4-6
tools: Read, Grep, Glob
---

# DB設計レビュー

## あなたの役割
データベース設計の問題を検出する専門エージェントです。
確認を求めず、直接レビューを実施して結果を返してください。

## チェック観点

1. **正規化** - 第3正規形が基本。意図的な非正規化にはコメントで理由を明記
2. **インデックス設計** - WHERE, JOIN, ORDER BY で使うカラムにインデックスがあるか
3. **外部キー制約** - リレーションに適切な外部キー制約が設定されているか
4. **ソフトデリート** - 全テーブルに deleted_at カラムがあるか。一貫性の確認
5. **マイグレーション安全性** - データ消失リスクの有無。カラム削除・型変更の影響
6. **命名規則** - テーブル名は英語スネークケース複数形、カラム名はスネークケース
7. **必須カラム** - id, created_at, updated_at, deleted_at の存在
8. **Prisma スキーマ** - schema.prisma と実 DB の整合性
9. **パフォーマンス** - 大テーブルへの ALTER TABLE の影響。ロック時間の見積もり

## 出力フォーマット

各指摘は以下の形式で報告:
- 深刻度: 🔴 Critical / 🟡 Warning / 🔵 Suggestion
- 問題の種類
- 対象テーブル・カラム
- 問題の説明と影響
- 修正案（Prisma スキーマ or マイグレーション SQL）

6.2 Agent Teams の設計

並列レビューの実行例

# PR レビューを4つのエージェントで並列実行
/code-review #42

→ Agent A: code-reviewer（コード品質）
→ Agent B: security-reviewer（セキュリティ）
→ Agent C: performance-reviewer（パフォーマンス）
→ Agent D: db-reviewer（DB設計）
→ 全完了後: レビュー結果を統合して報告

並列実装の実行例

# Issue 実装を複数エージェントで並列実行
/dev-issue-team #42

→ Agent A: バックエンド実装（NestJS module/controller/service）
→ Agent B: フロントエンド実装（React コンポーネント）
→ Agent C: テスト作成（unit + E2E）
→ 全完了後: 統合・PR作成

---
description: GitHub Issue 実装を複数エージェントで並列実行
allowed-tools: Bash, Read, Edit, Write, Agent
---

# 並列 Issue 実装

$ARGUMENTS の GitHub Issue を複数エージェントで並列実装してください。

## 手順

### 1. 準備
- `git checkout main && git pull origin main` でソースを最新化
- `gh issue view $ARGUMENTS` で Issue の内容を確認
- ブランチ作成: `feature/#-<概要>`

### 2. 並列実装（Agent を使用）
以下の3つのエージェントを並列で起動:

**Agent A: バックエンド実装**
- NestJS のモジュール・コントローラー・サービスを生成
- Prisma スキーマの更新（必要な場合）
- api-development.md の Rules に準拠

**Agent B: フロントエンド実装**
- React コンポーネントの生成
- Server Components / Client Components の判断
- frontend.md の Rules に準拠

**Agent C: テスト作成**
- ユニットテスト（*.spec.ts）
- E2E テスト（test/ 配下）
- testing.md の Rules に準拠

### 3. 統合
- 全エージェントの作業結果を統合
- 型チェック: `pnpm tsc --noEmit`
- テスト実行: `pnpm --filter api test && pnpm --filter web test`
- PR 作成: タイトル・説明は日本語、`Closes #` を含める

Phase 4 -- 外部連携

Phase 4 では、Claude Code をプロジェクトの外部ツール（GitHub, DB, Slack）と連携させる MCP と、設定を他プロジェクトに横展開する Plugins を設計します。

7.1 MCP の設計

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
      }
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

各 MCP サーバーの用途

MCP サーバー	用途	活用シーン
github	GitHub API へのアクセス	Issue 読み込み、PR 作成、コードレビューコメント投稿
postgres	開発 DB への直接クエリ	テーブル構造の確認、データの検証、マイグレーション状態の確認
slack	Slack へのメッセージ送信	PR 作成通知、デプロイ完了通知、レビュー依頼
context7	ライブラリの最新ドキュメント取得	NestJS, Prisma, Next.js 等の最新 API 仕様の参照

7.2 Plugins の設計

例えば、本プロジェクトのセキュリティルールと DB 操作ルールを Plugin 化する場合:

{
  "name": "enterprise-security-rules",
  "version": "1.0.0",
  "description": "基幹システム向けセキュリティ・DB操作ルール",
  "rules": [
    "rules/security.md",
    "rules/database.md"
  ],
  "agents": [
    "agents/security-reviewer.md",
    "agents/db-reviewer.md"
  ],
  "skills": [
    "skills/gen-api-spec/SKILL.md"
  ]
}

他のプロジェクトでは以下のコマンドで導入:

# Plugin のインストール
claude plugin add ./path/to/enterprise-security-rules

# または GitHub リポジトリから
claude plugin add github:your-org/enterprise-security-rules

開発フロー全体図

Issue 起票からデプロイまでの一気通貫フローを示します。各ステップでどの Claude Code 機能が使われるかを明示しています。

チーム運用ガイド

オンボーディング手順

新しいメンバーがプロジェクトに参加する際の手順です。

1. リポジトリ clone

   git clone https://github.com/your-org/your-project.git
   cd your-project
   pnpm install

2. Claude Code インストール

   npm install -g @anthropic-ai/claude-code

3. claude で起動 -- CLAUDE.md が自動読込され、プロジェクトの技術スタック・規約が即座に把握される
4. コードベース理解

   /explain-code apps/api/src/main.ts

   Skills が自動でコードの仕組みを図解付きで解説

5. 最初の Issue に取り組む

   /dev-issue 42

   Command が Issue の読み込みから PR 作成まで一括実行。新メンバーでもシニアと同じ手順・品質で作業できる

ナレッジ蓄積サイクル

発見（バグ、ベストプラクティス、注意点）
  │
  ▼
CLAUDE.md / Rules に追記
  │
  ▼
チームに PR で共有・レビュー
  │
  ▼
マージ → 次のメンバーが自動的に恩恵を受ける
  │
  ▼
新たな発見... (サイクルが回り続ける)

導入チェックリスト

Phase	タスク	成果物
Phase 1	CLAUDE.md を作成	.claude/CLAUDE.md
Phase 1	Rules を作成（セキュリティ、Git、コーディング規約）	.claude/rules/*.md
Phase 1	パス別 Rules を作成（API、フロントエンド、DB）	.claude/rules/*.md（paths 付き）
Phase 1	Settings を設定（権限、環境変数）	.claude/settings.json
Phase 2	Commands を作成（dev-issue、db-migrate、api-scaffold）	.claude/commands/*.md
Phase 2	Skills を作成（explain-code、gen-doc、gen-api-spec）	.claude/skills/*/SKILL.md
Phase 2	Hooks を設定（危険コマンドブロック、自動フォーマット）	.claude/settings.json（hooks セクション）
Phase 3	Agents を作成（code/security/performance/db-reviewer）	.claude/agents/*.md
Phase 3	Agent Teams のコマンドを作成（dev-issue-team）	.claude/commands/dev-issue-team.md
Phase 4	MCP を設定（GitHub、PostgreSQL、Slack）	.mcp.json
Phase 4	Plugin 化を検討（横展開対象のルール・エージェント）	plugin.json