Claude Code × CLAUDE.md 活用術：プロジェクト専用の指示書で出力品質を劇的に上げる実践ノウハ...

はじめに：なぜCLAUDE.mdが重要なのか

Claude Codeを使い始めてしばらくすると、「毎回同じことを説明している」「プロジェクト固有のルールを伝え忘れる」という問題に直面します。たとえば、チームで決めたコーディング規約、使用しているフレームワークのバージョン、テストの書き方など、プロジェクトごとに異なるルールをいちいちプロンプトで指示するのは非効率です。

そこで活用したいのがCLAUDE.mdファイルです。これはプロジェクトのルートディレクトリに配置する「Claude Code専用の指示書」で、Claude Codeが作業を開始する際に自動的に読み込まれます。筆者がこのファイルを本格的に運用し始めてから、Claude Codeの出力品質が体感で2〜3倍向上しました。この記事では、その過程で得た具体的なノウハウをお伝えします。

CLAUDE.mdの基本：最初に書くべき3つの情報

CLAUDE.mdに何を書けばいいか迷ったら、まずこの3つから始めてみてください。

1. プロジェクトの技術スタック

使っているフレームワーク、言語バージョン、主要ライブラリを明記します。「React 19 + TypeScript 5.7 + Next.js 15 App Router」のように具体的に書くのがポイントです。バージョンを省略すると、Claude Codeが古い書き方で提案してくることがあります。

# 技術スタック
- フロントエンド: React 19 + TypeScript 5.7
- フレームワーク: Next.js 15 (App Router)
- スタイリング: Tailwind CSS v4
- 状態管理: Zustand v5
- テスト: Vitest + Testing Library
- パッケージマネージャー: pnpm

2. ディレクトリ構成の説明

プロジェクトのディレクトリ構成を簡潔に説明します。特に、独自の命名規則やレイヤー構成がある場合は必ず書きましょう。筆者の経験では、この情報があるだけで「ファイルをどこに作ればいいか」というClaude Codeの判断が格段に正確になります。

# ディレクトリ構成
src/
  app/          # Next.js App Routerのルーティング
  components/   # 再利用可能なUIコンポーネント
  features/     # 機能ごとのドメインロジック
  lib/          # ユーティリティ・共通処理
  types/        # 型定義
  hooks/        # カスタムフック

3. コーディング規約のエッセンス

チームで守っているルールのうち、Claude Codeが守りにくいものを重点的に書きます。ESLintで自動検知できるものは不要で、「暗黙の了解」になっているルールこそ明文化が効果的です。

# コーディング規約
- コンポーネントは関数コンポーネント + アロー関数で統一
- Props型はコンポーネントと同ファイルで定義し、exportしない
- APIレスポンスの型はzodスキーマから生成する
- エラーハンドリングはResult型パターンを使用する
- 日本語コメントを使用する（JSDocも日本語）

実践で見つけた効果的な書き方のコツ

基本情報を書いた後、さらに出力品質を上げるためのテクニックを紹介します。これらは実際に数ヶ月運用する中で見つけた「効くポイント」です。

「やらないこと」を明示する

Claude Codeは親切心からか、聞かれていないことまで手を加えることがあります。これを防ぐには「やらないこと」を明確に書くのが有効です。筆者のプロジェクトでは以下のルールを追加してから、不要な変更が大幅に減りました。

# やらないこと（重要）
- 既存のimport文の順序を勝手に変更しない
- 依頼されていないリファクタリングを行わない
- console.logを勝手に削除しない（デバッグ中の可能性がある）
- 型を any に変更しない。型エラーが解決できない場合は相談すること

良い例・悪い例をセットで書く

「こう書いてほしい」だけでなく「こう書かないでほしい」も添えると効果的です。特にClaude Codeがよくやりがちなパターンを悪い例として示すと、同じミスの再発を防げます。

# エラーハンドリングの例

## 良い例
const result = await fetchUser(id)
if (result.isErr()) {
  return { error: result.error.message }
}
const user = result.value

## 悪い例（try-catchを使わない）
try {
  const user = await fetchUser(id)
} catch (e) {
  // このパターンは使用しない
}

頻出タスクのテンプレートを用意する

新規コンポーネント作成やAPIエンドポイント追加など、繰り返し発生するタスクのテンプレートをCLAUDE.mdに含めると非常に便利です。Claude Codeがテンプレートに沿って一貫性のあるコードを生成してくれます。

# 新規コンポーネント作成時のテンプレート
1. src/components/配下に PascalCase.tsx を作成
2. 同階層にPascalCase.test.tsx を作成
3. Storybookを使用している場合はPascalCase.stories.tsx も作成
4. コンポーネントにはJSDocで概要を記述する

チーム開発でのCLAUDE.md運用術

個人での利用だけでなく、チームでCLAUDE.mdを運用する際のポイントを紹介します。

Gitで管理してレビュー対象にする

CLAUDE.mdはプロジェクトのルールブックです。コードと同様にGitで管理し、変更時にはプルリクエストでレビューを通すようにしましょう。筆者のチームではCLAUDE.mdの変更PRには必ずチームリードのレビューを必須にしています。ルールの一貫性を保つうえで、これは欠かせない運用です。

定期的に見直しの場を設ける

月に1回程度、CLAUDE.mdの内容をチームで振り返る時間を設けるのがおすすめです。「この指示は効果があったか」「新たに追加すべきルールはあるか」を話し合うことで、継続的に品質が向上します。スプリントの振り返りに5分追加する程度で十分です。

.claude/ ディレクトリでの個人設定との使い分け

プロジェクトルートのCLAUDE.mdはチーム共通のルールを、.claude/ディレクトリ配下の設定は個人の好みを書くのが理想的です。たとえば「レスポンスは日本語で返してほしい」「変更箇所の説明を詳しめに書いてほしい」といった個人的な好みは共通設定に含めず、個人設定に分離しましょう。

よくある失敗パターンと対処法

CLAUDE.mdの運用で陥りがちな失敗と、その対処法をまとめます。

失敗1：情報を詰め込みすぎる

CLAUDE.mdが長くなりすぎると、Claude Codeが重要なルールを見落とすことがあります。筆者の経験では、200行を超えるとこの問題が顕著になりました。対策として、本当に重要なルールだけをCLAUDE.mdに残し、詳細なドキュメントは別ファイルに分離して「必要に応じて参照してください」と記載するのが効果的です。

失敗2：抽象的すぎる指示

「きれいなコードを書くこと」のような曖昧な指示は効果がありません。「関数は30行以内にする」「ネストは3段階まで」のように具体的な数値や基準を示しましょう。Claude Codeは具体的な指示ほど忠実に従います。

失敗3：更新を怠る

プロジェクトの技術スタックやルールが変わったのにCLAUDE.mdを更新しないと、古い指示に従ったコードが生成されてしまいます。ライブラリのメジャーバージョンアップ時や、新しい規約を導入した際は忘れずに更新しましょう。CIでCLAUDE.mdの最終更新日をチェックする仕組みを入れるのも一つの手です。

まとめ：CLAUDE.mdは育てるもの

CLAUDE.mdは一度書いて終わりではなく、プロジェクトとともに育てていくものです。最初は技術スタックとディレクトリ構成だけで始めて、Claude Codeとのやり取りの中で「これは指示書に書いておくべきだ」と感じたことを随時追加していくのが、最も自然で効果的な運用です。

小さく始めて、継続的に改善する。この姿勢こそが、Claude Codeを最大限に活用するための鍵だと、筆者は日々の実践を通じて確信しています。ぜひ今日からあなたのプロジェクトでもCLAUDE.mdを書き始めてみてください。

Claude Code × CLAUDE.md 活用術：プロジェクト専用の指示書で出力品質を劇的に上げる実践ノウハウ