@shinyaz

CLAUDE.md でAIコーディングアシスタントを最大活用する

約9分
ai-tools
#claude-code#ai-tools#dx#documentation
目次

この記事は、Claude Codeの生産性を組織レベルで最大化するシリーズの第1回だ。まずはCLAUDE.mdの設計と効果を紹介し、続く記事でスキルシステムによる最適化、メタスキルによる自動化、チーム展開の構想へと発展させていく。

課題：AIアシスタントにプロジェクトのコンテキストが伝わらない

Claude CodeやGitHub Copilotなど、AIコーディングアシスタントを使っていて「なぜそんなコードを生成するんだ」と思ったことはないだろうか。私のNext.jsブログでも、Claude Codeが提案するコードがプロジェクトの規約と合わないことが頻繁にあった。Tailwind CSS v4を使っているのにv3の書き方を提案したり、Veliteのコンテンツ構造を理解せずにファイルを直接読もうとしたり。

問題の根本は、AIにプロジェクト固有のコンテキストが不足していることだ。READMEはユーザー向けの説明であり、AIが必要とする技術的な詳細やコーディング規約は含まれていない。そこで導入したのがCLAUDE.mdファイル — Claude Codeがリポジトリのコンテキストを理解し、プロジェクトの規約に従ったコードを生成するための専用ガイドラインだ。

CLAUDE.md の構成と設計思想

注意： この記事では最初に作成した詳細なCLAUDE.md（355行）を紹介するが、後にこの詳細さが逆効果になることが判明した。CLAUDE.mdは毎回のセッション開始時にコンテキストウィンドウを消費するため、肥大化するとClaudeが重要な指示を見落とす原因になる。第2回の記事で、この問題をスキルシステムで解決し59行まで削減した経緯を紹介している。CLAUDE.mdは「短く、本当に必要な情報だけ」が公式のベストプラクティスでも推奨されている原則だ。

CLAUDE.mdは単なるドキュメントではなく、AIとの協働を最適化するためのインターフェースとして設計した。全体を5つのセクションに構成し、AIが必要とする情報に素早くアクセスできるようにしている。

1. Quick Reference — 即座に必要な情報

CLAUDE.md（一部抜粋）
## Quick Reference
 
### Commands
```bash
npm run dev          # Dev server (http://localhost:3000)
npm run build        # Production build (next build --turbopack)
npm start            # Start production server
npm run lint         # ESLint + Prettier check
npm test             # Unit/component tests (Vitest)
npm run test:e2e     # E2E tests (Playwright, requires build)
```
 
### Code Change Checklist
When modifying code, complete these steps in order:
1. **Run tests if applicable:**
   - `src/lib/` or `src/components/` changes → `npm test`
   - Routing, pages, or i18n changes → `npm run test:e2e`

最初のセクションには、AIが頻繁に参照する情報を配置した。コマンドの一覧と、コード変更時の必須チェックリストだ。これにより、Claude Codeは「ビルドコマンドは何か」「テストはどう実行するか」といった基本的な質問に対して、正確な回答を即座に提供できる。

2. Architecture — システムの全体像

アーキテクチャセクションでは、表形式とフロー図を活用して視覚的に理解しやすくした。

CLAUDE.md（Tech Stack部分）
### Tech Stack
 
| Layer | Technology | Purpose |
|-------|------------|---------|
| **Framework** | Next.js 16 (App Router) | React framework with SSG support |
| **Content** | Velite + MDX | Static content generation from Markdown |
| **Styling** | Tailwind CSS v4 | Utility-first CSS with theme tokens |
| **i18n** | Custom implementation | TypeScript dictionaries, no external lib |

特に重要なのは、Content Pipelineの説明だ。VeliteがMDXファイルをどのように処理し、Next.jsがどのように消費するかを、ディレクトリ構造とフロー図で明確に示している。これにより、Claude Codeは「新しいブログ記事を追加したい」という要求に対して、適切なディレクトリにMDXファイルを作成し、正しいfrontmatterを設定できる。

3. Testing — テスト戦略の明確化

CLAUDE.md（Test Conventions部分）
### Test Conventions
 
- Mock `#site/content` → `__tests__/__mocks__/velite.ts`
- New functions in `src/lib/` → add tests in `__tests__/lib/`
- Component changes → add tests in `__tests__/components/<subdirectory>/`
- Page/routing changes → add E2E tests in `e2e/`

テストセクションでは、どの変更にどのテストが必要かを明確にルール化した。これにより、Claude Codeは新しい機能を実装する際に、適切なテストも一緒に生成してくれる。

4. Content Writing — スタイルガイドの統合

このブログの大きな特徴の一つが、詳細なコンテンツスタイルガイドだ。CLAUDE.mdには、ブログ記事とTILエントリーの書き方を具体例と共に記載している。

CLAUDE.md（Blog Post Structure）
### Blog Posts (`content/posts/{en,ja}/`)
 
**Structure:**
1. **Hook** (1–2 paragraphs) — Start with the problem or outcome
2. **Body** — Logical sections with descriptive headings
3. **Closing** — Transferable insights in 3–4 bullets
 
**Voice:** First person ("I discovered"), share opinions, acknowledge limitations

これにより、Claude Codeに「この内容でブログ記事を書いて」と依頼すると、プロジェクトのスタイルガイドに準拠した記事を生成してくれる。タイトルの付け方、説明文の書き方、コードブロックの記法まで、すべて統一された形式で出力される。

5. Development Guidelines — プロジェクト固有の規約

最後のセクションでは、このプロジェクト特有の開発方針を明文化した。

CLAUDE.md（Project-Specific Practices）
### Project-Specific Practices
 
**This blog's patterns:**
- **Content-first development** — Features exist to enhance content, not vice versa
- **Progressive enhancement** — Core content readable without JavaScript
- **Bilingual parity** — Features must work equally well in both locales
- **Static-first** — Prefer build-time generation over runtime computation

これらの原則により、Claude Codeは単に動作するコードではなく、プロジェクトの思想に沿ったコードを生成する。例えば、新しい機能を実装する際も「JavaScriptが無効でもコンテンツが読めるか」「日英両方で同じように動作するか」を考慮した実装を提案してくれる。

実際の効果：AIとの協働が劇的に改善

CLAUDE.mdを導入してから、Claude Codeとの協働が劇的に改善した。具体的な効果を3つ紹介する。

1. 正確なコマンド実行

以前は「テストを実行して」と依頼すると、npm run testやjestなど、プロジェクトに存在しないコマンドを提案することがあった。CLAUDE.md導入後は、常に正しいコマンド（npm test）を使用し、さらに変更内容に応じて適切なテスト（単体テストかE2Eテストか）を選択するようになった。

2. 規約に準拠したコード生成

Tailwind CSS v4の新しい記法、Veliteのコンテンツ構造、Server Componentsの使い分けなど、プロジェクト固有の技術スタックを正確に理解してコードを生成するようになった。特に、#site/contentエイリアスの存在を理解し、Veliteが生成したコンテンツを適切にインポートできるようになったのは大きな改善だ。

3. スタイルガイドに沿ったコンテンツ作成

ブログ記事やTILエントリーの作成を依頼すると、タイトルの付け方、frontmatterの構成、本文の構造まで、すべてスタイルガイドに準拠した形で生成される。「具体的でアウトカム指向のタイトル」「第一人称での執筆」「transferable insightsでの締めくくり」など、細かい規約もきちんと反映される。

実装のポイント：効果的なCLAUDE.mdの書き方

CLAUDE.mdを書く際に意識した3つのポイントがある。

1. 具体例を豊富に含める

抽象的な説明より、具体的なコード例やコマンド例の方がAIには理解しやすい。「テストを書く」ではなく「src/lib/の変更なら__tests__/lib/にテストを追加」のように、具体的なパスとアクションを示す。

2. 表とフロー図を活用する

複雑な情報は、箇条書きより表やフロー図の方が構造を理解しやすい。Tech Stackの表、Content Pipelineのフロー図など、視覚的な表現を積極的に使用した。

3. "Why"を明記する

単なるルールの羅列ではなく、その背景にある理由も記載する。「Content-first development」の原則があるのはなぜか、「No external i18n library」を選択した理由は何か。これにより、AIは表面的なルールだけでなく、プロジェクトの思想を理解して適切な判断ができる。

見落としやすい落とし穴：暗黙的な期待の明示化

CLAUDE.mdを書いたのに、Claude Codeが意図どおりに動いてくれない — そんな経験はないだろうか。『実践Claude Code入門』（技術評論社）では、この問題の根本原因を「暗黙的な期待が明示されていない」ことだと分析している。

エキスパートが「当然」と思う手順

例えば「プロフィール編集機能を追加してください」と指示したとき、エキスパートの開発者なら以下の手順を踏む：

  1. README.mdを読んで全体像を把握
  2. architecture.mdを確認してレイヤー構造を理解
  3. Grepで既存の類似機能を検索
  4. 見つかった既存実装のパターンを確認
  5. 既存パターンに従って新機能を実装
  6. テストを実行

しかし、CLAUDE.mdに書かれているのが「新機能を実装する際は、README.mdとarchitecture.mdを必ず確認すること」だけだとどうなるか。手順3〜5（既存パターンの検索と確認）が書かれていないため、Claude Codeはこの手順を「オプション」と解釈する。結果、architecture.mdだけを頼りに実装を始め、既存コードとは異なるパターンのコードを生成してしまう。

エキスパートにとって「類似機能を検索して既存パターンに合わせる」のは自然すぎる行為で、わざわざドキュメント化する発想がない。だが、Claude CodeにとってはCLAUDE.mdに書かれていない手順は必須ではないのだ。

もう一つの罠：資料間のコンフリクト

暗黙的な期待と同様に問題になるのが、複数のドキュメント間での指示の矛盾だ。例えば：

  • architecture.md：「UIレイヤーは必ずサービスレイヤーを経由してデータにアクセスすること」
  • development-guidelines.md：「パフォーマンスが重要な画面では、直接データソースにアクセスすることを推奨」
  • 既存コードのDashboard.tsx：直接データアクセスで実装されている

この状況で「ダッシュボードを拡張してください」と指示すると、Claude Codeは3つの矛盾する情報に直面する。どれを優先すべきかの指針がなければ、実行するたびに異なるパターンを採用する不安定な動作になる。

対策：暗黙知をCLAUDE.mdに書き出す

この問題への対策は、自分が「当然」だと思っている手順を意識的にCLAUDE.mdに書き出すことだ。以下のような問いかけが有効である：

  • 「新機能を実装するとき、自分はまず何をするか」 — 検索、既存パターンの確認、設計ドキュメントの参照など、無意識にやっている手順を洗い出す
  • 「ドキュメント間で矛盾する指示はないか」 — 複数のルールが衝突する場合、優先順位を明記する
  • 「この指示を読んだ新人は、自分と同じ行動をとるか」 — 新人開発者を想像すると、暗黙の前提に気づきやすい

CLAUDE.mdの効果を最大化するには、「ルールを書く」だけでなく、「ルールに従うための手順」も含めて明示化する視点が重要だ。

CLAUDE.mdの限界と今後の展望

CLAUDE.mdは万能ではない。現時点での限界もある。

まず、メンテナンスコストの問題だ。プロジェクトの構造が変わるたびにCLAUDE.mdも更新する必要がある。これを怠ると、AIに誤った情報を与えることになる。現在は、アーキテクチャ変更時にCLAUDE.mdの更新も必須タスクとしてチェックリストに含めることで対応している。

また、AIモデルによる理解度の差もある。Claude Code向けに最適化されたガイドラインが、他のAIアシスタントでも同じように機能するとは限らない。将来的には、複数のAIアシスタントに対応した、より汎用的なフォーマットが必要になるかもしれない。

まとめ

  • READMEではなくAI専用のインターフェースを設計する — 人間向けのドキュメントとAIが必要とする情報は異なる。技術スタック、テスト戦略、コーディング規約をAIが消費しやすい形で構造化することで、規約に沿ったコード生成が実現する。
  • 抽象的な説明より具体例がAIに伝わる — 「テストを書く」ではなく「src/lib/の変更なら__tests__/lib/にテストを追加」のように、具体的なパスとアクションを示す方がAIの精度が上がる。
  • CLAUDE.mdは肥大化すると逆効果になる — 詳細に書くほど良いわけではない。355行まで膨れた結果、重要な指示がノイズに埋もれてClaudeが見落とすようになった。「常に読み込まれるコスト」を意識した設計が必要だ。
  • "Why"を明記すると応用が効く — ルールだけでなく背景を書くことで、AIが想定外のケースでも適切な判断を下せるようになる。
  • 暗黙の手順を意識的に書き出す — エキスパートが「当然」と思う手順ほどCLAUDE.mdから抜け落ちやすい。「新人でも同じ行動をとれるか」を基準に、手順を明示化する。

AIコーディングアシスタントを使っているなら、ぜひCLAUDE.mdの導入を検討してみてほしい。最初は簡単なコマンドリストとアーキテクチャの説明から始めて、徐々に充実させていけばいい。AIとの協働が、きっと今より快適になるはずだ。

ただし、充実させすぎるとCLAUDE.mdが肥大化し、逆にAIのパフォーマンスを下げてしまう問題がある。次の記事では、355行に膨れ上がったCLAUDE.mdをスキルシステムで83%削減した方法を紹介する。

共有する

田原 慎也

田原 慎也

ソリューションアーキテクト @ AWS

AWS ソリューションアーキテクトとして金融業界のお客様を中心に技術支援をしており、クラウドアーキテクチャや AI/ML に関する学びをこのサイトで発信しています。このサイトの内容は個人の見解であり、所属企業の公式な意見や見解を代表するものではありません。

もっと見る→

関連記事