Claude Codeの効率的な使用のためのベストプラクティス、プロジェクト初期化からチームコラボレーションまでの包括的ガイド
ベストプラクティス¶
このドキュメントは、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 テンプレート例：
# 私のプロジェクト名
## 概要
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 が無関係なファイルに惑わされることも防げます。
# .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 がディレクトリ構造を理解すれば、ファイルの查找場所と作成場所が分かるようになります：
## プロジェクト構造
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 に注文キャンセルメソッドを追加してください。
注文ステータスがキャンセル可能かどうかを確認するようにしてください。
@ 参照のいくつかの方法：
@src/services/auth.ts # 単一ファイルを参照
@src/components/ # ディレクトリ全体を参照
@package.json # 設定ファイルを参照
@https://nextjs.org/docs # オンラインドキュメントを参照（内容をクロール）
コスト削減のコツ：
@で関連ファイルを積極的に参照すると、Claude にプロジェクト全体を検索させるよりもはるかにコストを抑えられます。Claude が検索的时候会读取大量文件、额外的 token を消費します。
一度に1つのことだけを行う¶
1つのプロンプトに 너무 many タスクを詰め込まないでください。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 を有効活用する¶
这两个コマンドはコンテキスト管理の核心ツールです：
/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 ワークフロー¶
推奨されるワークフロー：
# 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 リポジトリにコミットし、チーム成员が同じプロジェクト設定を共有します：
# プロジェクトルートの 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 に統一されたレビューを実行させます：
## PR Review 基準
コードをレビューする際は以下を確認してください：
1. **機能正確性**：要件が完全に実装されているか
2. **エラーハンドリング**：例外ケースがカバーされているか
3. **セキュリティ**：SQL インジェクション、XSS、権限バイパスなどのリスクはないか
4. **パフォーマンス**：不必要なデータベースクエリ、メモリリークはないか
5. **テストカバー**：新しいコードに対応テストがあるか
6. **コードスタイル**：プロジェクト規範に合っているか
7. **ドキュメンテーション**：公開 API に JSDoc コメントがあるか
コードスタイルの統一¶
CLAUDE.md を通じてコードスタイルを強制的に統一します：
## コードスタイル
- 命名：コンポーネントは PascalCase、関数/変数は camelCase、定数は UPPER_SNAKE_CASE
- ファイル名：コンポーネントファイルは PascalCase（例：UserAvatar.tsx）、
それ以外は kebab-case
- import の順序：React → サードパーティライブラリ → 内部モジュール → 型 → スタイル
- 関数の最大行数：50 行、 超えたら分割
- コンポーネント props が 3 つ以上の場合は interface で定義
上級者向けテクニック集¶
以下是、経験豊富なユーザーが積み重ねてきた高度なテクニックです：
カスタム Slash コマンド¶
.claude/commands/ ディレクトリにカスタムコマンドテンプレートを作成します：
# .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つだけで、使用体験が大幅に向上します。使用を重ねるうちに、さらに多くの上級テクニックを徐々に活用していきましょう。