Mastering Claude Code Configs: `CLAUDE.md` vs `.claude/rules/`

An engineer explains how to configure Claude Code, an AI coding assistant, by using a single CLAUDE.md file for high-level project context and modular .claude/rules/ files for path-scoped, domain-specific guidelines. The approach aims to keep token consumption low and improve compliance by loading only relevant rules for each task.

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.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. - .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 .