How to Structure Claude Code Rules and Enable Automatic Memory for Scalable Projects

Why Split CLAUDE.md into .claude/rules/

When a single CLAUDE.md exceeds 200 lines, context consumption grows, compliance drops, and team collaboration suffers. Splitting rules into a .claude/rules/ directory keeps the core file small and lets each topic be maintained independently.

.claude/
├── CLAUDE.md          # core config (~50 lines)
└── rules/
    ├── typescript.md  # TypeScript rules (~50 lines)
    ├── react.md       # React rules (~40 lines)
    ├── testing.md     # Testing rules (~30 lines)
    └── api/design.md  # API design rules (~25 lines)

Basic .claude/rules/ Setup

Create the directory: mkdir -p .claude/rules Add rule files with descriptive names, e.g.:

your-project/
├── .claude/
│   ├── CLAUDE.md          # project directives
│   └── rules/
│       ├── code-style.md # code‑style guide
│       ├── testing.md    # testing conventions
│       └── security.md   # security requirements

All .md files are discovered recursively. Loading order: user‑level rules ( ~/.claude/rules/) load first, then project rules (which can override them).

Path‑Specific Rules

Use YAML front‑matter paths to apply a rule only to matching files. Example for API files:

---
paths:
  - "src/api/**/*.ts"
---
# API development rules
- All API endpoints must include input validation
- Use a standard error response format
- Include OpenAPI documentation comments

Supported glob patterns include **/*.ts, src/**/*, *.md, src/components/*.tsx. Multiple patterns can be combined with braces:

---
paths:
  - "src/**/**/*.{{ts,tsx}}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---
# TypeScript and test rules
...

Rules are loaded only when a matching file is opened, saving context.

Sharing Rules via Symlinks

# Link an entire shared directory
ln -s ~/shared-claude-rules .claude/rules/shared
# Link a single file
ln -s ~/company-standards/security.md .claude/rules/security.md

Symlinks are treated as normal files; circular links are detected.

User‑Level Rules

Personal rules in ~/.claude/rules/ apply to all projects. Example:

~/.claude/rules/
├── preferences.md   # personal coding preferences
└── workflows.md     # preferred workflows

User rules load before project rules, but project rules have higher priority and can override them.

Automatic Memory System

What It Is

Claude automatically records notes during work—build commands, debugging insights, architecture decisions, code‑style preferences, and workflow habits—without manual editing.

Storage Location

Each project gets a local memory directory under ~/.claude/projects/<project>/memory/ (derived from the Git repository or project root):

~/.claude/projects/<project>/memory/
├── MEMORY.md          # concise index loaded each session (first 200 lines)
├── debugging.md       # detailed debugging notes
├── api-conventions.md # API design decisions
└── ...                # additional topic files created by Claude

The memory is machine‑local and not shared across environments.

Loading Behavior

MEMORY.md

: first 200 lines loaded at the start of every conversation.

Topic files (e.g., debugging.md): loaded on demand when referenced.

Enabling/Disabling

Toggle in a conversation with /memory.

Set "autoMemoryEnabled": false in the Claude Code config.

Use environment variable export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Auditing and Editing

All memory files are plain markdown and can be edited or deleted at any time. Commands: /memory – list loaded files, toggle memory, open the memory folder.

Open directly, e.g., code ~/.claude/projects/$(basename $(pwd))/memory/.

Correct erroneous notes; Claude will update its memory.

Combining CLAUDE.md and Automatic Memory

Use CLAUDE.md and .claude/rules/ for explicit, version‑controlled directives. Rely on automatic memory for experiential knowledge that Claude learns from corrections and repeated actions.

Typical Workflow

New project : run /init to generate a base CLAUDE.md, then create .claude/rules/ and split rules.

Discovering patterns : tell Claude a habit (e.g., always use pnpm); Claude records it automatically.

Team collaboration : project‑level rules live in the repo, personal rules in ~/.claude/rules/, and experiential notes in automatic memory.

Advanced Techniques

Rule Priority

When multiple rule files could apply, priority is:

Specific path rule > General rule > User‑level rule

Large‑Team Management

In monorepos, exclude unrelated CLAUDE.md files with the claudeMdExcludes array in the config:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

Organization‑wide CLAUDE.md files cannot be excluded.

Integration with Settings

{
  "autoMemoryEnabled": true,
  "claudeMdExcludes": ["**/node_modules/**"]
}

Best Practices

Rule Organization

One theme per rule file.

Descriptive filenames.

Use path‑specific rules for file‑type‑specific guidance.

Share common rules via symlinks.

Automatic Memory

Allow Claude to learn naturally.

Periodically audit memory content.

Manually correct wrong notes.

Keep core policies in CLAUDE.md, not only in memory.

Team Collaboration

Version‑control project rules.

Store personal preferences in ~/.claude/rules/.

Share company standards with symlinks.

Summary

.claude/rules/ provides modular rule maintenance, path‑specific loading, and cross‑project sharing. Automatic memory captures build commands, debugging insights, and other experiential knowledge without manual effort, loading only the first 200 lines of MEMORY.md each session. Together they give fine‑grained control over Claude’s behavior while keeping context usage efficient.