Shashank Trivedi

When configuring Claude Code (or Claude-driven AI coding assistants) in your projects, structuring your instructions efficiently is key to getting accurate code generation while keeping token consumption low.

Understanding when to use a single CLAUDE.md versus modular .claude/rules/ files will help keep your AI assistant sharp, focused, and predictable.

The Core Hierarchy & Scope

Claude Code looks for configurations across multiple levels:

├── ~/.claude/                      # User / Global level (applies to all your projects)
└── project-root/
    ├── CLAUDE.md                   # Global project level (loaded into every session)
    ├── .claude/rules/              # Modular & scoped rules (loaded selectively)
    └── sub-app/
        └── CLAUDE.md               # Sub-directory / Monorepo scope

Enter fullscreen mode Exit fullscreen mode

  1. CLAUDE.md (The Global Cheat Sheet)Think of CLAUDE.md as the main ReadMe for the AI. It provides high-level context and essential project memory. When to use CLAUDE.md:Common CLI Commands: Build, test, lint, and run scripts (npm test, docker compose up). Core Architecture: Tech stack summary, overall folder structure, and design principles. Global Rules: Non-negotiable guidelines that apply project-wide (e.g., "Strict TypeScript, no any").

Project Context: E-Commerce Web App

Build & Test Commands

  • Build: npm run build
  • Test single file: npx jest src/components/Button.test.tsx
  • Lint: npm run lint

High-Level Guidelines

  • All UI components must use React 19 functional syntax.
  • Never hardcode secrets or environment variables.
  1. .claude/rules/ (Modular & Path-Scoped Rules)As projects grow, packing every guideline into CLAUDE.md bloats the prompt context and reduces overall compliance. The .claude/rules/ directory lets you create modular, topic-specific, or path-scoped rules (in .yml or .md). When to use .claude/rules/:Path-Specific Rules (globs): Guidelines that apply only to certain files (e.g., API routes vs. React components). Domain Separation: Splitting rules into dedicated files (testing.yml, security.yml, db-migrations.yml). Token Optimization: Prevent loading backend migration rules into context when editing CSS/React components.

.claude/rules/api-routes.yml

name: API & Endpoint Rules
globs:

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

rules:

  • id: input-validation description: Validate all incoming payloads with Zod schemas.
  • id: error-handling description: Never expose internal DB error traces in API responses.

Pro-Tips & Best Practices

  • Keep CLAUDE.md Concise: Aim for under 100–150 lines. Move specific domain details into .claude/rules/.
  • Combine Both Strategies: Put Commands & Core Pillars in CLAUDE.md[cite: 1].Put Framework/Directory Specifics in .claude/rules/[cite: 1].
  • Use Sub-Directory CLAUDE.md in Monorepos: Place localized CLAUDE.md files inside specific packages/apps (e.g., apps/web/CLAUDE.md and services/auth/CLAUDE.md) so sub-teams maintain isolated contexts[cite: 1].