## ベストプラクティス

このドキュメントは、Claude Code ユーザーが実際の開発現場で培った経験をまとめたものです。Claude Code を使い始めたばかりの新人から、さらに効率を上げたいと考えている経験豊富なユーザーまで、誰もが役立つテクニックを見つけられるでしょう。

内容は入門から上級まで順に構成しているので、まずは一読してから、日常の業務のなかで少しずつ活用していくことをおすすめします。

## プロジェクト初期化のベストプラクティス

良い始まりは成功の半分です。プロジェクトで Claude Code を初めて使用する前に、10 分間かけて初期化すれば、それ以降のすべてのインタラクションが効率的になります。

### 第一歩：CLAUDE.md を作成する

これが最も重要なステップです。`CLAUDE.md` は Claude への「プロジェクト取説」のようなもので、Claude Code を起動するたびに自動的に読み込まれ、プロジェクトの概要を理解します。

**なぜこのステップがこんなに重要なのか？**

CLAUDE.md を書かなければ、同じことを Claude に何度も説明することになります：

```
あなた：pnpm で依存関係をインストールして
Claude：了解しました、npm install を実行しますね...
あなた：npm じゃなくて pnpm です！
Claude：すみません、pnpm install を実行します...
```

CLAUDE.md があれば、このような基本情報は一度だけ説明すれば済みます。

**CLAUDE.md テンプレート例：**

```markdown
# 私のプロジェクト名

## 概要
Next.js 15 ベースのEC 管理システムを TypeScript で構築しています。

## 技術スタック
- ランタイム：Node.js 22 LTS
- フレームワーク：Next.js 15 (App Router)
- スタイリング：Tailwind CSS v4
- データベース：PostgreSQL 16 + Prisma ORM
- パッケージマネージャー：pnpm 9
- テストフレームワーク：Vitest + Playwright

## よく使うコマンド
- 依存関係のインストール：`pnpm install`
- 開発サーバー：`pnpm dev`（ポート 3000）
- テスト実行：`pnpm test`
- コードチェック：`pnpm lint`
- データベースマイグレーション：`pnpm prisma migrate dev`
- 本番ビルド：`pnpm build`

## コーディング規約
- TypeScript を厳格に使用し、`any` は禁止
- React コンポーネントは関数型 + hooks で記述
- スタイリングは Tailwind のみとし、インライン style や CSS ファイルは使用しない
- すべての API ルートは `{ success: boolean, data?: T, error?: string }` を返す
- データベースクエリはすべて service 層を経由し、route で直接 Prisma を呼び出さない
- コミットメッセージの形式：`feat:` / `fix:` / `docs:` / `refactor:` などのプレフィックス

## プロジェクト構造
- `src/app/` — ページと API ルート（App Router）
- `src/components/` — 再利用可能な UI コンポーネント
- `src/components/ui/` — 基本コンポーネント（Button、Input など）
- `src/services/` — ビジネスロジック層
- `src/lib/` — ユーティリティ関数と設定
- `prisma/` — データベーススキーマとマイグレーションファイル

## 注意事項
- `prisma/migrations/` 下のファイルは手動で編集しない
- 環境変数は `.env.local` に設定（Git にはコミットしない）
- API 認証ミドルウェアは `src/middleware.ts`
- 画像リソースは `public/images/` に置き、next/image コンポーネントで読み込む
```

**/init コマンドで素早く生成：**

手動で書きたくない場合は、`/init` コマンドで Claude にプロジェクトを自動分析させ、生成してもらうこともできます：

```
/init
```

Claude はプロジェクト構造、package.json、設定ファイルなどをスキャンし、自動的に CLAUDE.md を生成します。その後、チームルールなどで見落とされた情報を手動で補完してください。

### 第二歩：.claudeignore を設定する

`.gitignore` と同様に、`.claudeignore` は Claude にどのファイルを無視するかを指示します。これにより検索が高速化するだけでなく、Claude が無関係なファイルに惑わされることも防げます。

```bash
# .claudeignore

# 依存関係ディレクトリ
node_modules/
vendor/
.venv/

# ビルド成果物
dist/
build/
.next/
out/

# 大容量データファイル
*.sql
*.csv
*.sqlite
data/

# バイナリファイルとメディアファイル
*.jpg
*.png
*.mp4
*.zip

# 自動生成コード
generated/
*.gen.ts
prisma/migrations/

# ログ
logs/
*.log
```

### 第三歩：CLAUDE.md にディレクトリ構造を記述する

このステップはよく見落とされますが、効果は絶大です。Claude がディレクトリ構造を理解すれば、ファイルの検索場所と作成場所が分かるようになります：

```markdown
## プロジェクト構造
src/
├── app/                 # Next.js App Router
│   ├── (auth)/          # ログインが必要なページ
│   ├── (public)/        # 公開ページ
│   └── api/             # API ルート
├── components/
│   ├── ui/              # 基本 UI コンポーネント（shadcn/ui）
│   ├── forms/           # フォームコンポーネント
│   └── layouts/         # レイアウトコンポーネント
├── services/            # ビジネスロジック（各モジュールごと1ファイル）
├── hooks/               # カスタム React hooks
├── lib/                 # ユーティリティ関数
│   ├── auth.ts          # 認証関連
│   ├── db.ts            # データベース接続
│   └── validators.ts    # Zod スキーマ定義
└── types/               # TypeScript 型定義
```

## 日常コーディングのベストプラクティス

初期化が終わったら、日常使用するこれらの習慣が効率を大幅に向上させます。

### 曖昧な指示ではなく、具体的な要件を記述する

これは最も基本的かつ重要な原則です。Claude は心を読むことはできません。要求が具体的であればあるほど、正確な結果を得られます。

| 曖昧な指示（効果は低い） | 具体的な説明（効果が高い） |
|---|---|
| 「ログイン機能を修正して」 | 「src/app/api/auth/login/route.ts にログイン失敗回数制限を追加：同一 IP で 5 分間に 5 回失敗すると 15 分間ロックし、Redis でカウントを保存」|
| 「コンポーネントを作って」 | 「UserAvatar コンポーネントを作成して、src/components/ui/ 下に配置。name と imageUrl の2つの props を受け取り、画像がない場合は氏名の頭文字を表示。円形のアイコンには Tailwind の rounded-full を使用」|
| 「バグがあるから直して」 | 「商品一覧ページでページネーションをクリックすると、フィルター条件がリセットされるという報告があります。src/app/products/page.tsx のページネーションロジックを確認し、ページ移動時に URL query params が保持されるようにしてください」|

### @ 参照を効果的に使用する

Claude に特定のファイルを参照させたい場合は、`@` 記号で直接指定すると、自分で検索させるよりも速く正確に結果を得られます：

```
@src/services/order-service.ts と @src/types/order.ts を確認して、
order-service に注文キャンセルメソッドを追加してください。
注文ステータスがキャンセル可能かどうかを確認するようにしてください。
```

**@ 参照のいくつかの方法：**

```bash
@src/services/auth.ts       # 単一ファイルを参照
@src/components/            # ディレクトリ全体を参照
@package.json               # 設定ファイルを参照
@https://nextjs.org/docs    # オンラインドキュメントを参照（内容をクロール）
```

> **コスト削減のコツ**：`@` で関連ファイルを積極的に参照すると、Claude にプロジェクト全体を検索させるよりもはるかにコストを抑えられます。Claude は検索時に大量のファイルを読み込み、余分な token を消費するためです。

### 一度に1つのことだけを行う

1つのプロンプトにあまりに多くのタスクを詰め込まないでください。Claude は1つのことに集中しているとき最も良い結果を出します：

```
# 非推奨：一度に多くを求めすぎる
「ユーザーモジュールにアバターアップロード機能を追加して、
ログインページのスタイルも変更して、
それに検索ボックスのデバウンスも追加して、
パスワードリセットメールテンプレートも更新して。」

# 推奨：ステップバイステップ
ステップ 1：「UserProfile コンポーネントにアバターアップロード機能を追加、S3 で保存」
ステップ 2：「ログインページのスタイルを更新、@docs/design-spec.md のデザイン稿を参照」
ステップ 3：「検索ボックスに 300ms デバウンスを追加、カスタム hook を使用」
ステップ 4：「パスワードリセットメールテンプレートを更新、@src/templates/welcome.html のスタイルを参照」
```

### Claude に先に読ませてから変更させる

既存のコードを扱う場合は、Claude に先にコードを理解させてから変更させた方が、直接変更するよりも効果的です：

```
# ステップ 1：先に理解する
「@src/services/payment-service.ts を読んでいただき、現在の決済フローの処理ロジックを教えてください。
特にエラーハンドリングとリトライの仕組みに注目ください。コードは変更しないでください。」

# ステップ 2：次に計画する
「理解した上で、WeChat 決済チャンネルを追加したいと考えています。
修正方針を作成し、変更が必要な箇所をリストアップしてください。」

# ステップ 3：修正を実行する
「方針に問題なさそうでしたら、実行してください。まず payment-service.ts を変更してください。」
```

### 複雑なタスクには Plan Mode を使用する

複数のファイルにまたがる大規模なタスクには、Plan Mode（`Shift+Tab` で切り替え）を使用して、Claude に先に計画を作成させます：

```
[Plan Mode]
既存のシステムに RBAC（役割ベースのアクセス制御）権限システムを追加する必要があります。
現在ユーザーは admin と user の2種類のみですが、カスタムロールと細粒度の権限をサポートする必要があります。
まず既存のコードを分析し、詳細な実施計画を立ててください。
```

Claude は段階的な計画を生成するので、確認後に通常モードに戻して少しずつ実行できます。

### /clear と /compact を有効活用する

この2つのコマンドはコンテキスト管理の中核ツールです：

```bash
/compact    # 現在の会話履歴を圧縮し、重要な情報を保持してコンテキスト空間を解放
/clear      # 会話履歴を完全にクリアし、ゼロから開始

# 使用タイミング：
# - 完全に別のタスクに切り替える場合 → /clear
# - 同じタスクだが会話が長くなった場合 → /compact
# - Claude の応答品質が低下した場合（コンテキスト過載）→ /compact
# - ある機能を終えて次の機能を開始する場合 → /clear
```

> **重要な原則**：トピックを変更する場合は、必ず先に `/clear` してください。残った古いコンテキストは token を浪費するだけでなく、Claude の応答に干渉する可能性もあります。

## コードレビューのベストプラクティス

Claude Code はコードを書くだけでなく、コードレビューも手伝うことができます。

### /review コマンドを使用する

現在の Git 変更を素早くレビュー：

```
/review
```

Claude は未コミットのすべての変更をチェックし、潜在的な問題を指摘します：
- ロジックエラーとエッジケース
- セキュリティリスク（SQL インジェクション、XSS など）
- パフォーマンス問題
- コードスタイルの不整合
- エラーハンドリングの欠如

### Claude にテストを書かせて修正を検証させる

コードを修正した後、Claude にテストを書かせて検証させます：

```
@src/services/order-service.ts の注文キャンセルロジックを修正しました。
このメソッドのユニットテストを書いていただき、以下のシナリオをカバーしてください：
1. 正常に発送待ち注文をキャンセル
2. 発送済み注文のキャンセルを試行（失敗するはず）
3. 存在しない注文をキャンセル
4. 同一注文の並行キャンセル
```

### 複数回レビューのワークフロー

重要なコード変更については、複数回のレビューを行うことができます：

```
# 第1回：全体レビュー
「@src/services/payment-service.ts の最新の変更をレビューしてください。
セキュリティとエラーハンドリングに注目ください。」

# フィードバックに基づいて修正後、第2回：
「修正後のコードを再度レビューしてください。
今回はパフォーマンスとエッジケースに注目ください。」

# 第3回（任意）：比較レビュー
「修正前と修正後のコードを突き合わせて、
すべての問題が解決され、新しい問題が導入されていないことを確認してください。」
```

## デバッグのベストプラクティス

Bug 修正は Claude Code の得意分野の一つです。正しいデバッグの方法を身につければ、Claude がより迅速に問題を発見する手助けをしてくれます。

### 完全なエラーログを提供する

エラーの最後の行だけを Claude に見せないでください。完全なコンテキストを提供します：

```
pnpm build を実行するとエラーが発生しました。完全なエラーログは以下の通りです：

```
Type error: Argument of type 'string | undefined' is not assignable
to parameter of type 'string'.
  Type 'undefined' is not assignable to type 'string'.
  > 42 |   const user = await getUser(session.userId)
       |                                      ^^^^^^^
  43 |   return NextResponse.json(user)
```

このエラーは @src/app/api/user/route.ts で発生しています。
セッションの型定義に問題があると思われるので、確認してください。
```

### ステップバイステップでデバッグ：まず診断してから修復

Claude に直接修復させるのではなく、まず診断させましょう：

```
# ステップ 1：診断
「ユーザーからログイン後たまに 404 ページにリダイレクトされるという報告があります。
@src/middleware.ts と @src/app/(auth)/layout.tsx を確認し、
この問題の原因になりうる要因を分析してください。コードは変更しないでください。」

# ステップ 2：原因を確認してから修復
「分析が理にかなっています。確かにセッション期限切れ時のリダイレクトロジックに問題があります。
この問題を修復し、後続の調査がしやすいように適切なエラーログも追加してください。」
```

### スクリーンショットを活用する

Claude Code はスクリーンショットの読み取りをサポートしており、UI 関連のバグに特に有効です：

```
このスクリーンショット @screenshot.png をご覧ください。
テーブルの最後の列のテキストが切れています。
@src/components/DataTable.tsx のスタイルを確認し、この問題を修復してください。
```

ターミナルでは、画像ファイルを Claude Code の入力エリアに直接ドラッグ＆ドロップすれば、自動的に処理されます。

## Git ワークフローのベストプラクティス

Claude Code は Git と深く統合されており、これらの機能を有効に活用すればバージョン管理がずっと楽になります。

### /commit で自動生成のコミットメッセージを使用する

Claude はコード変更を分析し、規範的なコミットメッセージを自動生成します：

```
/commit
```

生成されるコミットメッセージには通常以下が含まれます：
- 変更タイプのプレフィックス（feat、fix、refactor など）
- 簡潔な変更の説明
- 影響範囲の説明

自動生成されたメッセージが満足できない場合は、修正を依頼できます：

```
/commit
# Claude が生成したメッセージが不十分な場合
「コミットメッセージをもっと詳しくしてください。このロジックを変更した理由を説明してください」
```

### フィーチャーブランチ + PR ワークフロー

推奨されるワークフロー：

```bash
# 1. フィーチャーブランチを作成
git checkout -b feature/order-cancel

# 2. Claude Code で開発を開始
claude

# 3. 開発中は小まめにコミット
> 「注文キャンセルの基本ロジックを実装」
> /commit

> 「キャンセル理由フィールドとバリデーションを追加」
> /commit

> 「注文キャンセル関連のユニットテストを追加」
> /commit

# 4. 開発完了、PR を作成
> 現在のブランチに Pull Request を作成し、
> すべてのコミットの変更をまとめ、規範的な PR 説明文を生成
```

### main ブランチで直接修正することを避ける

```
# CLAUDE.md にこのルールを追加：
## Git 規範
- すべての修正はフィーチャーブランチで行うこと。main ブランチを直接修正しない
- ブランチ命名：feature/xxx、fix/xxx、refactor/xxx
- コミット前に `pnpm lint && pnpm test` を実行して問題がないことを確認
```

CLAUDE.md に記述すると、Claude は自動的にこれらのルールに従います。誤って main ブランチでコードを修正するよう Claude に指示した場合、新しいブランチを作成するよう促されます。

## チームコラボレーションのベストプラクティス

Claude Code をチームで使用する場合、規範を統一すればコラボレーションがスムーズになります。

### CLAUDE.md 規範を共有する

CLAUDE.md を Git リポジトリにコミットし、チームメンバーが同じプロジェクト設定を共有します：

```bash
# プロジェクトルートの CLAUDE.md → Git にコミット
git add CLAUDE.md
git commit -m "docs: add CLAUDE.md project configuration"

# 個人の好みの設定 → .claude/CLAUDE.md に置き、.gitignore に追加
echo ".claude/CLAUDE.md" >> .gitignore
```

**チームの CLAUDE.md に含めるべきもの：**
- プロジェクトの技術スタックとアーキテクチャの説明
- コーディング規範と命名規則
- よく使うコマンドとスクリプト
- ディレクトリ構造の説明
- チームの約束事（ブランチ戦略、コミット規範、review フロー）

**個人の .claude/CLAUDE.md に含められるもの：**
- 個人のコーディングの好み
- よく使うコードスニペット
- 特定の開発環境設定

### PR Review の標準化

CLAUDE.md に PR review 基準を定義し、Claude に統一されたレビューを実行させます：

```markdown
## PR Review 基準
コードをレビューする際は以下を確認してください：
1. **機能正確性**：要件が完全に実装されているか
2. **エラーハンドリング**：例外ケースがカバーされているか
3. **セキュリティ**：SQL インジェクション、XSS、権限バイパスなどのリスクはないか
4. **パフォーマンス**：不必要なデータベースクエリ、メモリリークはないか
5. **テストカバー**：新しいコードに対応テストがあるか
6. **コードスタイル**：プロジェクト規範に合っているか
7. **ドキュメンテーション**：公開 API に JSDoc コメントがあるか
```

### コードスタイルの統一

CLAUDE.md を通じてコードスタイルを強制的に統一します：

```markdown
## コードスタイル
- 命名：コンポーネントは PascalCase、関数/変数は camelCase、定数は UPPER_SNAKE_CASE
- ファイル名：コンポーネントファイルは PascalCase（例：UserAvatar.tsx）、
  それ以外は kebab-case
- import の順序：React → サードパーティライブラリ → 内部モジュール → 型 → スタイル
- 関数の最大行数：50 行、超えたら分割
- コンポーネント props が 3 つ以上の場合は interface で定義
```

## 上級者向けテクニック集

以下は、経験豊富なユーザーが積み重ねてきた高度なテクニックです：

### カスタム Slash コマンド

`.claude/commands/` ディレクトリにカスタムコマンドテンプレートを作成します：

```bash
# .claude/commands/review-security.md
以下のコードをセキュリティレビューしてください。重点的に確認する項目：
1. SQL インジェクションリスク
2. XSS 攻撃面
3. CSRF 防御
4. 権限チェックが完全か
5. 機密データが暗号化されているか
6. ログに機密情報が漏洩していないか

確認範囲：$ARGUMENTS
```

使用方法：

```
/review-security @src/app/api/
```

### 複数ファイルの協調修正

複数のファイルを同時に修正する必要がある場合、Claude に明確な全体像を提供します：

```
注文システムにクーポン機能を追加する必要があります。
以下のファイルが関連します：
- @src/types/coupon.ts — 新規作成、クーポンタイプを定義
- @src/services/coupon-service.ts — 新規作成、クーポンビジネスロジック
- @src/services/order-service.ts — 修正、決済時にクーポンを適用
- @src/app/api/coupons/route.ts — 新規作成、クーポン API
- @prisma/schema.prisma — 修正、Coupon モデルを追加

上記の順序で処理し、各ファイルの完了時に報告してください。
```

### Extended Thinking を活用する

複雑なアーキテクチャの決定については、Claude に拡張思考機能を使用させます：

```
[Opus モデルを使用]
現在の REST API を GraphQL に移行することを検討しています。
以下の要素を考慮して、利点と欠点を深く分析してください：
1. 既存の 50+ API エンドポイントの移行コスト
2. フロントエンドクエリの最適化によるメリット
3. キャッシュ戦略の変化
4. チームの学習曲線
5. 既存の React Query との統合方針

コードを書く必要はありません。詳細な技術分析レポートをください。
```

### Claude に自分で検証させる

Claude が自らの修正を検証する習慣を身につけます：

```
修正完了後、以下を確認してください：
1. pnpm lint を実行してフォーマット問題がないことを確認
2. pnpm test を実行して既存のテストが壊れていないことを確認
3. 型エラーがある場合は自分で修正
```

## よくある誤解

最後に、避けるべきいくつかのやり方を挙げます：

| 誤解 | 正しいやり方 |
|------|---------|
| ファイル全体を会話に貼り付ける | `@ファイルパス` で参照する |
| 1つのプロンプトで Claude に5つのことをさせる | 1つずつ、段階的に進める |
| 要件説明が曖昧で不明瞭 | 具体的なファイル、動作、期待結果を提示する |
| CLAUDE.md を使用しない | 10 分かけて作成すれば、以後の無数の時間を節約できる |
| /clear や /compact を決して使用しない | トピック変更時は /clear、会話が長い時は /compact |
| Claude に理解させずに直接修正させる | 先にコードを読み、計画し、最後に実行する |
| すべてのことに Opus を使用する | 日常は Sonnet、複雑な決定のときだけ Opus |
| エラーが出ても同じコマンドを繰り返し実行する | 考え方を変えて、より多くのコンテキストを提供する |

これらのベストプラクティスを習得するには時間がかかります。まずは最も基本的なことから始めることをお勧めします：CLAUDE.md を作成する、具体的な要件を述べる、一度に1つのことを行う。この3つだけで、使用体験が大幅に向上します。使用を重ねるうちに、さらに多くの上級テクニックを徐々に活用していきましょう。