IT女子 アラ美お疲れ様です！IT業界で働くアライグマです！
「Claude Codeを導入したのに、毎回同じことを説明し直している」「プロジェクトの命名規則を無視したコードが生成される」。こんな経験はありませんか？AIコーディングツールは便利ですが、プロジェクト固有の知識が伝わらないと、期待した生産性向上には繋がりません。
この記事では、Claude CodeのCLAUDE.mdとカスタム指示を活用して、プロジェクト固有の知識をAIに覚えさせ、開発品質を劇的に改善する実践テクニックを解説します。PjMとして複数チームのAIツール導入を支援してきた経験をもとに、失敗パターンと成功パターンの両面からお伝えします。
Claude Codeが「プロジェクトを理解しない」問題の正体
IT女子 アラ美Claude Codeは強力なAIコーディングアシスタントですが、そのままでは「あなたのプロジェクト」を何も知りません。プロジェクトのディレクトリ構造やファイル内容は読み取れても、チームが暗黙的に共有している設計思想・命名規則・アーキテクチャの判断基準までは理解できないのです。
この問題は、特に以下のような場面で顕在化します。
- 命名規則の不統一: キャメルケースで統一しているプロジェクトでスネークケースのコードが生成される
- 既存ライブラリの無視: プロジェクト内にユーティリティ関数があるのに、同じ機能を新規実装してしまう
- テストパターンの逸脱: チームで決めたテストの書き方やモックの使い方と異なるコードが出てくる
- アーキテクチャの理解不足: レイヤードアーキテクチャやクリーンアーキテクチャの境界を無視した依存関係のコードを提案する
すでにClaude Code実践ガイドでAIエージェントの基本的な使い方を解説しましたが、ツールの使い方を覚えただけでは、この「コンテキスト不足」の壁は越えられません。AIに「何ができるか」ではなく「何を知っているべきか」を教え込む仕組みが必要です。
その解決策が、Claude CodeのCLAUDE.mdファイルです。プロジェクトルートに配置するだけで、AIがセッション開始時に自動で読み込み、プロジェクト固有のルールやコンテキストを理解した上でコード生成を行うようになります。
IT女子 アラ美
ITアライグマCLAUDE.mdなしで開発した失敗パターン
あるSaaS開発チーム（エンジニア5名、React + Node.js構成）では、Claude Codeを導入して3か月間、CLAUDE.mdを設置せずに運用していました。チームリーダーのBさん（30代バックエンドエンジニア）は「AIが書いたコードのレビュー指摘が減らない」と悩んでいました。
Before: CLAUDE.mdなしの状態
導入前は、チーム全員がClaude Codeを「便利な補完ツール」として使っていました。しかし実態は以下のような問題が積み重なっていたのです。
- PRレビューの指摘件数が週平均32件: 命名規則違反、不要なimport、テストの書き方の不統一が大半を占めていた
- 既存ユーティリティの再発明が月4〜5件:
libs/utils/にある共通関数を知らずに、同じロジックを別ファイルに書いてしまう - アーキテクチャ違反の混入: ドメイン層から直接インフラ層のモジュールをimportするコードが生成され、依存方向が崩れる
Bさんは「Claude Codeが悪いのではなく、プロジェクトのルールを伝える手段がなかった」と振り返っています。
なぜ口頭での指示では不十分なのか
チームでは当初、各エンジニアがClaude Codeのプロンプトに「うちのプロジェクトではキャメルケースを使って」「テストはVitestで書いて」と毎回手動で入力していました。しかし、この方法には致命的な限界があります。
- 人によって伝える内容が異なる: あるエンジニアは命名規則を伝え、別のエンジニアはディレクトリ構造を伝える。結果として品質にバラつきが出る
- 新しいセッションで記憶がリセットされる: Claude Codeを再起動するたびに、同じ説明を繰り返す必要がある
- 暗黙知が言語化されていない: 「なんとなくこう書く」というチームの暗黙ルールは、そもそもプロンプトに含まれない
一方で、MCPサーバーを自作して外部ツールと連携させる方法もありますが、まず取り組むべきはCLAUDE.mdによるプロジェクトルールの明文化です。MCPは「外部データの取得」に強みがありますが、コーディング規約やアーキテクチャ方針の伝達にはCLAUDE.mdのほうが直接的かつ効果的です。
IT女子 アラ美ITアライグマケーススタディ：CLAUDE.mdとカスタム指示で開発品質が変わった成功パターン
IT女子 アラ美前述のBさんのチームは、CLAUDE.mdを導入してから2週間で目に見える変化が現れました。
Action: CLAUDE.mdに何を書いたか
チームが作成したCLAUDE.mdは約120行。以下の4セクションで構成されていました。
- プロジェクト概要（10行）: 技術スタック、ディレクトリ構造の概要、主要な依存ライブラリ
- コーディング規約（40行）: 命名規則（変数はcamelCase、コンポーネントはPascalCase）、import順序、エラーハンドリングのパターン
- アーキテクチャ方針（30行）: レイヤー間の依存方向、共通ユーティリティの場所と使い方、新規モジュール追加時のディレクトリ配置ルール
- テスト方針（40行）: テストファイルの配置規則、モックの書き方、カバレッジ基準、E2Eテストのスコープ
特に効果が大きかったのは、「やってはいけないこと」を明記した点です。「ドメイン層からインフラ層を直接importしない」「axiosを直接使わず、apiClient経由で呼ぶ」といった禁止事項を書くことで、AIが「べからず」を理解してコード生成するようになりました。
After: 導入2週間後の数値変化
- PRレビュー指摘件数が週32件 → 12件に減少（62%削減）
- 既存ユーティリティの再発明がゼロに: CLAUDE.mdに共通関数の一覧と用途を記載したことで、AIが適切に既存コードを参照
- 新メンバーの立ち上がり期間が2週間 → 5日に短縮: CLAUDE.mdがプロジェクトのオンボーディングドキュメントとしても機能
- コードレビューの所要時間が1PR平均25分 → 15分に短縮
Bさんは「CLAUDE.mdの副次的な効果として、チームの暗黙知が言語化されたこと」を最大の収穫として挙げています。AIナレッジベースの構築という観点では、Gemini×NotebookLMの組み合わせも有効ですが、開発現場のコンテキスト共有にはCLAUDE.mdのほうがワークフローに直接組み込める分、即効性があります。
カスタム指示との併用で効果を最大化する
CLAUDE.mdに加えて、Claude Codeのカスタム指示（Custom Instructions）を設定することで、さらに精度が向上します。CLAUDE.mdがプロジェクト全体のルールを定義するのに対し、カスタム指示は個人の作業スタイルや担当領域に特化した指示を補完します。
例えばフロントエンド担当のエンジニアは「レスポンシブデザインを常に考慮すること」「アクセシビリティのaria属性を忘れないこと」を個人のカスタム指示に設定し、バックエンド担当は「SQLインジェクション対策を常にチェックすること」「N+1問題を検知したら警告すること」を設定するといった使い分けが効果的です。
IT女子 アラ美ITアライグマ今日から始めるCLAUDE.md作成ステップ
CLAUDE.mdの効果は理解できても、「何から書けばいいかわからない」という声をよく聞きます。ここでは、今日から実践できる3ステップを紹介します。
ステップ1: プロジェクトの「当たり前」を書き出す
最初に取り組むべきは、チーム内で「言わなくてもわかっている」とされていることの言語化です。以下のテンプレートをベースに、プロジェクトルートにCLAUDE.mdを作成しましょう。
# プロジェクト概要
- 技術スタック: React 18 + TypeScript + Node.js + PostgreSQL
- パッケージマネージャ: pnpm
- 主要ディレクトリ: src/domain/, src/infra/, src/ui/
# コーディング規約
- 変数名: camelCase
- コンポーネント名: PascalCase
- ファイル名: kebab-case.ts
# 禁止事項
- domain/ から infra/ を直接importしない
- any型を使わない（unknown + type guardで対処）
ポイントは最初から完璧を目指さないことです。まず20〜30行で始めて、AIの出力を見ながら足りないルールを追記していくのが現実的な進め方です。
ステップ2: 「やってはいけないこと」を優先的に追加する
CLAUDE.mdで最も費用対効果が高いのは、禁止事項の記述です。AIは「こうしてほしい」という正の指示よりも、「これだけはやるな」という負の指示のほうが守りやすい傾向があります。
コードレビューで繰り返し指摘される項目をリストアップし、CLAUDE.mdの禁止事項セクションに追加していきましょう。これだけで、AIが生成するコードの品質は大きく変わります。
ステップ3: チーム全体で運用する仕組みを作る
CLAUDE.mdはGitリポジトリにコミットしてチーム全体で共有することが前提です。以下の運用ルールを決めておくと、形骸化を防げます。
- 月1回のメンテナンス日を設ける: スプリント振り返りのタイミングでCLAUDE.mdの更新を議題に入れる
- PRレビューで「CLAUDE.mdに書くべきか？」を意識する: 繰り返し指摘される項目は、個人の記憶に頼るのではなくCLAUDE.mdに追記する
- 新メンバー参加時にCLAUDE.mdを読んでもらう: オンボーディングドキュメントとしても活用する
なお、SESから自社開発への転職を考えているエンジニアにとっても、CLAUDE.mdの運用経験は「チームの開発プロセスを改善できる人材」としてのアピールポイントになります。転職先の面接で「前職ではAIツールの運用ルールを整備し、レビュー工数を60%削減しました」と言えれば、即戦力としての評価は間違いなく上がるでしょう。
ワークライフバランスを重視し、安定した環境で長く働きたい方は、以下の社内SE特化型エージェントなどを検討してみてください。
| 比較項目 | 社内SE転職ナビ | レバテックキャリア | リクルートエージェント |
|---|---|---|---|
| ターゲット | 社内SE・定着率重視客先常駐なし | Web・SIer全般キャリアアップ重視 | 全職種・大量募集広く浅く |
| 残業時間の確認 | 厳密に審査済み | 担当者に確認要 | 不明確な場合が多い |
| 面接対策 | 「面接1回」も交渉可 | 専門的な対策あり | 担当者による |
| おすすめ度 | 安定志向なら必須 | A挑戦したい人向け | B求人数重視 |
| 公式サイト | 無料相談する | - | - |
IT女子 アラ美ITアライグマまとめ
Claude CodeのCLAUDE.mdは、AIに「プロジェクトの一員」としての知識を注入する仕組みです。本記事のポイントを振り返ります。
- CLAUDE.mdなしの問題: 命名規則違反やアーキテクチャ無視のコードが生成され、レビュー負荷が増大する
- 導入効果: PRレビュー指摘62%削減、新メンバーの立ち上がり期間を2週間→5日に短縮した実績がある
- 書き方のコツ: 「やってはいけないこと」を優先的に書き、20〜30行から始めて段階的に育てる
- チーム運用: Gitにコミットして共有し、月1回のメンテナンスで形骸化を防ぐ
CLAUDE.mdへの投資は、一度書けばチーム全員・全セッションで効果が持続するため、費用対効果は極めて高いと断言できます。まずは「プロジェクト概要」と「禁止事項」の2セクションだけでも作成して、AIの出力の変化を体感してみてください。
IT女子 アラ美ITアライグマ
