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