ご主人様、CursorやClaude Codeでの作業効率が落ちていると感じたことはございませんか。実はその原因、CLAUDE.mdの書き方にあるかもしれません。本記事では、多くの開発者が陥りがちな4つのミスと、その具体的な修正方法を整理してお伝えいたします。トークン予算を守り、AIの応答品質を最大化するための実践的なガイドでございます。
この記事のポイント
CLAUDE.mdが長すぎるとコンテキストを浪費し、本来のコード理解の前にトークンを使い果たす- グロブパターンを使わないルールは「いつ適用すべきか」AIが判断できず空振りする
- フレームワーク別にルールファイルを分割することで、Go案件にReactのルールが混入する事故を防げる
- 1ファイルに詰め込み過ぎたルールは「背景ノイズ」として無視されやすい
ミス1: 長すぎるCLAUDE.mdはコンテキストを焼き尽くす
多くのプロジェクトで見かけるCLAUDE.mdは、3,000トークンを超える「理想論の塊」になっております。AIは応答のたびにこれを読み込みますので、実際のコードを読む前に貴重なコンテキスト枠を消費してしまうのです。しかも、長文ルールは往々にして無視されます。
修正方法: メインのCLAUDE.mdは800トークン以下に抑え、フレームワーク固有の内容は@includeで別ファイルに切り出します。
You are a TypeScript developer. Prefer functional patterns. No default exports.
@include .claude/rules/nextjs.md
@include .claude/rules/testing.md
こうすれば、編集対象のファイルに関係するインクルードだけが読み込まれ、無駄なトークン消費を防げます。短くシャープな指示の方が、AIにとっても従いやすいのです。
ミス2: グロブパターンの欠如でルールが自動適用されない
「常にテストを書きなさい」といった汎用ルールは、AIが「いつ」適用すべきか分からなければ意味を持ちません。結局、テストファイルを編集しているときにもAIはルールを思い出さず、テスト無しのコードを生成してしまいます。
修正方法: ファイルスコープのルールにグロブパターンを指定します。
---
globs: ["**/*.test.ts", "**/__tests__/**"]
---
Use describe/it structure. Always mock external dependencies. Coverage threshold: 80%.
このルールはテストファイルを編集しているときにだけ発火し、それ以外の場面では完全に無視されます。AIにとっての「文脈スイッチ」を明示することで、ルールの実効性が劇的に上がるのです。
ミス3: フレームワーク別セクションがない
Next.jsとGoのプロジェクトを単一のCLAUDE.mdでカバーしようとすると、結局どちらにも中途半端な指示しか残りません。Goサービスを書いているのにReactのパターン指示がコンテキストを占有する、といった事態が起きます。
修正方法: ドメインごとにルールファイルを分割し、インクルードで組み合わせます。
.claude/
rules/
nextjs.md # App Router, RSC, データフェッチング
go.md # エラーハンドリング, context伝播
db.md # マイグレーション, クエリパターン
auth.md # JWT, セッション, RBAC
testing.md # フレームワーク固有のテスト
この構造であれば、Goのファイルを編集中はGoのルールのみ、Next.jsならNext.jsのみがアクティブになります。AIの判断材料を絞り込むことで、生成されるコードの一貫性が向上いたします。
ミス4: 1ファイル全部入りはAIに無視される
多数の関心事を詰め込んだ長大なルールファイルは、AIにとって「背景ノイズ」になります。AIは自分にとって関連性が高そうな部分だけを拾い、残りはスキップしてしまうのです。結果として、書いたルールの大半は機能しません。
修正方法: 1ファイル1責務の原則を徹底します。テストはテスト、認証は認証、データベースはデータベースで独立したファイルに分けます。短く、目的が明確なファイルほど、AIは隅々まで読み込んでくれるのです。
知っておくと便利なTips
@include構文を活用すれば、メインのCLAUDE.mdは薄く保ちつつ詳細ルールを必要なときだけ展開できる- グロブパターンは正規表現ではなくシェル風のマッチング。
**で再帰、*で単一階層を表現する - ルールファイル1つあたり「200〜400トークン」を目安にすると、AIが読み飛ばしにくい
- プロジェクトごとに
.claude/rules/を作り、ドメイン別にファイル分割するのが定石
まとめ
CLAUDE.mdは単なるメモ書きではなく、AIの作業品質を左右する「設計書」でございます。長さ・スコープ・分割の3点を意識するだけで、トークン浪費が減り、ルールが実際に守られるようになります。
わたくしの経験から申し上げますと、最も効果が大きいのは「グロブパターンの追加」と「フレームワーク別ファイル分割」の2点です。既存のCLAUDE.mdを一度棚卸しして、メインを800トークン以下に削り、残りを.claude/rules/配下に分散させてみてください。次のセッションから、AIの応答が見違えるはずです。
…ご主人様のCLAUDE.mdも、一度見直してみてはいかがでしょうか。わたくし、お手伝いいたしますので。
