Shashank Trivedi

Claude Code（または Claude を活用した AI コーディングアシスタント）をプロジェクトに設定する際、指示を効率的に構造化することが、正確なコード生成とトークン消費の抑制に重要です。

単一の CLAUDE.md とモジュール式の .claude/rules/ ファイルを使い分ける方法を理解することで、AI アシスタントの精度と一貫性を高めることができます。

コア階層とスコープ

Claude Code は複数のレベルで設定を探します:

├── ~/.claude/                      # ユーザー / グローバルレベル（すべてのプロジェクトに適用）
└── project-root/
    ├── CLAUDE.md                   # プロジェクト全体レベル（すべてのセッションで読み込まれる）
    ├── .claude/rules/              # モジュール式でスコープ指定されたルール（選択的に読み込まれる）
    └── sub-app/
        └── CLAUDE.md               # サブディレクトリ / モノレポスコープ

Enter fullscreen mode Exit fullscreen mode

  1. CLAUDE.md（グローバルなチートシート）CLAUDE.md は AI 向けのメイン ReadMe として機能します。高レベルのコンテキストと必須のプロジェクトメモリを提供します。 CLAUDE.md を使用する場合:一般的な CLI コマンド: ビルド、テスト、リント、実行スクリプト（npm test、docker compose up）。 コアアーキテクチャ: 技術スタックの概要、全体的なフォルダ構造、設計原則。 グローバルルール: プロジェクト全体に適用される必須のガイドライン（例: 「Strict TypeScript、any の禁止」）。

プロジェクトコンテキスト: E コマース Web アプリ

ビルドとテストコマンド

  • ビルド: npm run build
  • 単一ファイルのテスト: npx jest src/components/Button.test.tsx
  • リント: npm run lint

高レベルガイドライン

  • すべての UI コンポーネントは React 19 の関数コンポーネント構文を使用する必要があります。
  • シークレットや環境変数をハードコードしない。
  1. .claude/rules/（モジュール式でパス指定されたルール）プロジェクトが大きくなるにつれ、すべてのガイドラインを CLAUDE.md に詰め込むとプロンプトコンテキストが膨れ上がり、全体的なコンプライアンスが低下します。.claude/rules/ ディレクトリでは、モジュール式でトピック別またはパス指定されたルール（.yml または .md）を定義できます。 .claude/rules/ を使用する場合:パス指定ルール（グロブ）: 特定のファイルのみに適用されるガイドライン（例: API ルートと React コンポーネントの違い）。 ドメイン分離: ルールを専用ファイルに分割（testing.yml、security.yml、db-migrations.yml）。 トークン最適化: CSS/React コンポーネントを編集する際にバックエンドのマイグレーションルールをコンテキストに読み込まない。

.claude/rules/api-routes.yml

name: API & Endpoint Rules
globs:

  • "src/api/*/.ts"
  • "src/controllers/*/.ts"

rules:

  • id: input-validation description: すべての受信ペイロードを Zod スキーマで検証する。
  • id: error-handling description: API レスポンスに内部 DB エラートレースを露出しない。

プロのヒントとベストプラクティス

  • CLAUDE.md を簡潔に保つ: 100〜150 行以内に収める。具体的なドメインの詳細は .claude/rules/ に移動する。
  • 両方の戦略を組み合わせる: コマンドとコアの柱は CLAUDE.md に記述する[cite: 1]。フレームワーク/ディレクトリ固有の詳細は .claude/rules/ に記述する[cite: 1]。
  • モノレポではサブディレクトリ CLAUDE.md を使用する: 特定のパッケージ/アプリ（例: apps/web/CLAUDE.md や services/auth/CLAUDE.md）内にローカライズされた CLAUDE.md ファイルを配置し、サブチームが独立したコンテキストを維持できるようにする[cite: 1]。