Memory and rules

Each Claude Code session starts with a new context window. Two mechanisms preserve project knowledge: the CLAUDE.md instructions you maintain and the auto memory Claude accumulates.

#CLAUDE.md and auto memory

Both are context, not enforced permissions. Use permission rules or hooks to enforce restrictions.

#File locations

Claude searches upward from the current directory for CLAUDE.md and CLAUDE.local.md. Content closer to the working directory enters context later and is more specific. Subdirectory CLAUDE.md files load as Claude reads relevant files.

#Recommended structure

your-project/
├── CLAUDE.md
└── .claude/
    ├── settings.json
    └── rules/
        ├── testing.md
        ├── api.md
        └── frontend.md

Use CLAUDE.md for the overall structure:

# Project conventions

- Package manager: pnpm
- Run `pnpm lint` after changes, and `pnpm typecheck` for type-related changes
- Do not put .env files, keys, or production configuration in documentation or commits

## Directories

- Pages: `src/app`
- Components: `src/components`
- Documentation: `content/docs`

## Working process

- Propose a plan before large changes
- Check light and dark modes after UI changes
- Include validation commands in the final report

#Shorter rules are easier to follow

Aim for fewer than 200 lines. Long files consume context and are more likely to contain contradictions.

Effective rules tend to be:

• Specific: say pnpm lint, not “run necessary checks.”
• Verifiable: say “do not commit .env,” not “be careful with security.”
• Organized by topic: separate build, testing, directories, and style.

#Import other files

CLAUDE.md supports @path imports. Relative paths resolve from the containing CLAUDE.md directory, with up to four levels of recursive imports.

@README.md
@docs/development.md

## Claude Code additions

- Prefer existing components
- Avoid unrelated refactoring

To display the string literally, wrap it in backticks, such as ` @README.md `.

The first import of a file outside the project requires confirmation. A rejected import does not automatically prompt again; adjust it manually if needed.

#Projects using AGENTS.md

For installations using CLAUDE.md rather than native AGENTS.md loading, an existing AGENTS.md can be imported:

@AGENTS.md

## Claude Code

- Use plan mode before broad changes
- Check mobile, light, and dark layouts after UI changes

A symlink is another option, but the @AGENTS.md import is easier on Windows. Check the current official memory documentation for your version's native AGENTS.md support before keeping both mechanisms enabled.

#.claude/rules/

Rule files provide more granular CLAUDE.md guidance. Rules without frontmatter load at startup:

# Testing rules

- Run the relevant unit tests after fixing a bug
- Do not skip failing tests

Rules with paths load when matching files are accessed:

---
paths:
  - "src/api/**/*.ts"
  - "app/api/**/*.ts"
---

# API rules

- Validate all inputs
- Return a consistent `{ code, message }` error shape
- Never put server secrets in the client bundle

This is especially useful in large repositories, reducing irrelevant context and cache invalidation.

#Auto memory

Auto memory records lessons Claude learns from corrections and shares them across sessions for a repository. It is useful for project-specific experience such as build commands, test prerequisites, and recurring failure causes.

Common controls:

#Troubleshooting

#Official references

• How Claude remembers your project
• Explore the .claude directory
• Debug your configuration