Claude Code: Configuration & Context

Claude Code can read a repository, but code alone does not tell it your branch rules, the odd test command, which generated files must stay untouched, or why one pattern is preferred over another. CLAUDE.md gives each new session that project briefing before the first request.

Useful project configuration stays selective and easy to review. It supplies facts Claude cannot infer, points to working examples, and keeps task-only detail out of every session.

Scopes, imports, path rules, auto memory, and skills each need one clear job inside the available context.

I stopped re-explaining recurring Claude Code rules once a reviewed CLAUDE.md and a narrow hook could carry the instruction and enforcement separately.

What CLAUDE.md Does

Claude Code loads CLAUDE.md as instructions when a session begins. The file can name build commands, code conventions, architecture decisions, repository etiquette, and traps that are hard to spot from source. It is Markdown, so the best version reads like a short briefing rather than a machine schema.

Run /init to generate a starter from the repository, then edit it. Run /context to confirm the file loaded. Anthropic's memory guide says CLAUDE.md files load in full, which is why every line needs to earn space.

Do not put secrets in any project instruction file. A shared CLAUDE.md is committed to Git, and even a private local file is model context. Store tokens in the secret system used by the project and refer to the variable name only when Claude needs to know it exists.

Choose the Right Scope

Scope	Location	Who Gets It
Managed	Operating-system policy path	Everyone in the organization
User	~/.claude/CLAUDE.md	You, in every project
Project	./CLAUDE.md	The team through Git
Local	./CLAUDE.local.md	You, in this project

Put personal defaults in the user file and repository facts in the project file. A local file fits machine paths or a temporary personal rule that teammates should not inherit. Add CLAUDE.local.md to .gitignore before using it.

Claude loads broader instructions before narrower project instructions. A project can refine a user preference, but conflicting rules create drift rather than a clean override. Remove the conflict or state the exception in one place.

Write a Useful Project Brief

Start with facts the agent would otherwise have to rediscover or guess. Name the package manager, test commands, branch lane, generated paths, and one or two source files that show the house pattern. Skip file-by-file maps and standard language advice Claude already knows.

# Acme Storefront

## Commands
- Install with `pnpm install`
- Run focused tests with `pnpm test -- <path>`
- Run `pnpm build` before a commit

## Repository Rules
- Work on `feature/*` branches from `development`
- Ask before adding a package
- Do not edit generated files under `src/api/client/`

## Patterns
- Follow `src/server/routes/orders.ts` for API handlers
- Read `docs/auth.md` before editing session code

"Follow best practices" is too broad to alter behavior. "Follow src/server/routes/orders.ts for API handlers" gives Claude code it can inspect. A rule such as "ask before adding a package" names a decision point. Test each line by asking what mistake it prevents; remove it if the answer is unclear.

Treat the instruction file like any other reviewed source file. Review it when Claude repeats a mistake, when commands move, or when the branch process shifts. Avoid appending every correction from one isolated session. First decide whether the lesson belongs in a shared instruction, a path rule, a reusable skill, or only the current prompt.

Split Detail with Imports and Rules

CLAUDE.md can import another file with @path/to/file. Use imports for short project docs that apply to every session, such as Git rules or a compact architecture map. Imported text also uses context, so an import is not a way to hide a large manual from the context window.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Architecture map: @docs/architecture-summary.md

Path-scoped rules fit detail that matters only when Claude works in part of the tree. Put them under .claude/rules/ and add frontmatter patterns for the paths they cover. An API rule can load for src/api/**/*.ts without taxing a CSS task.

This is a cleaner form of the context-guidebook idea recovered from the earlier Claude Code guide. The root file stays an index of always-needed facts, while auth, data, UI, and release detail sit near the code or path rule that calls for them. Keep each source owned by one domain so two docs do not give Claude different answers.

Separate Instructions, Memory, and Skills

• CLAUDE.md: instructions you author and review for every matching session.
• Auto memory: machine-local facts Claude records while you work.
• Skills: topic knowledge or repeatable routines loaded when needed.
• Settings: permissions, hooks, plugins, model choices, and tool behavior.

Claude stores auto memory under ~/.claude/projects/ on your machine. Claude loads the first 200 lines or 25 KB of its MEMORY.md index, whichever comes first, and reads topic files when needed. Run /memory to inspect or edit it. Memory is local to the machine; team documentation still belongs in Git.

Use a skill when the full text is relevant only to a class of tasks. A release routine, security review, or API convention can live in .claude/skills/<name>/SKILL.md. Claude sees the skill description at startup and loads the full instructions when the task calls for them, which keeps the base context smaller.

Manage the Session Context

The context window contains far more than your prompt. It holds conversation history, files Claude read, command output, instruction files, auto memory, loaded skills, and tool definitions. Long build logs and broad repository searches can consume more space than the request itself.

Run /context when answers begin to lose earlier decisions. Run /clear whenever you switch from one task to an unrelated task. Use /compact focus on the API changes when you need a summary that preserves one thread. You can also add compact instructions to CLAUDE.md for facts that must survive a long session.

Claude clears old tool output and compacts the conversation near the limit, but a summary can omit a detail. A fresh session with a short handoff often beats a long rescue attempt. Put persistent rules in files, record the current state in Git, and start the next task with only the sources it needs.

Configure Large Codebases by Domain

A large repo should not have one giant instruction manual. Keep the root CLAUDE.md for commands and rules shared across the tree. Add child CLAUDE.md files or path rules for packages that have their own build steps, data models, or review checks.

Point to code that already carries the pattern. For an auth task, name the auth rule or doc and one handler that shows the expected flow. Ask a subagent to map an unfamiliar package if that search would flood the main session with file reads. The subagent returns a summary while keeping its investigation in a separate context.

Select context even when the model advertises a large window. A relevant test, type, and handler beat hundreds of unrelated files. The Claude Code architecture guide explains that tool output and loaded extensions share the same finite context as your request.

Give each package one owner for its instructions. If both the root file and a package file describe the same test routine, one copy will go stale. Keep the shared rule at the root and the package exception beside that package. A short pointer is safer than two full versions of the same policy.

Troubleshoot Instruction Drift

• Run /context to confirm which instruction files loaded.
• Run /memory and check whether auto memory conflicts with the project rule.
• Search for the same instruction in user, parent, project, local, and path-scoped files.
• Rewrite vague rules as an action, boundary, command, or pointer to a source file.
• Move a must-hold boundary to a hook, permission rule, sandbox, or CI check.

Test a revision with a small task that used to fail. If the agent still misses it, adding capital letters may make the file louder without making it clearer. Cut nearby clutter, remove conflicts, and state the rule beside the command or path it governs.

FAQ

Where should I put CLAUDE.md?

Put shared project instructions in CLAUDE.md or .claude/CLAUDE.md at the repository root and commit them. Put personal rules that apply to every project in ~/.claude/CLAUDE.md. Use CLAUDE.local.md for private project instructions and keep it out of Git. Managed organization instructions belong in the policy location for the operating system.

How long should CLAUDE.md be?

Anthropic gives no fixed word or line limit. Keep only instructions Claude cannot infer by reading the repository, such as uncommon test commands, branch rules, architecture decisions, and known traps. CLAUDE.md loads in full each session, so remove prose that does not prevent a likely mistake and link to focused detail instead.

Does CLAUDE.md enforce rules?

No. Claude reads CLAUDE.md as project instructions, but vague, conflicting, or buried rules can be missed. Use a PreToolUse hook, permission rule, sandbox, branch rule, or CI check when a boundary must hold. Keep CLAUDE.md for guidance that helps the model choose the right code pattern and workflow.

What is the difference between CLAUDE.md and auto memory?

CLAUDE.md is authored project or personal instruction text that you review and may share through Git. Auto memory is machine-local information Claude records while you work. Its MEMORY.md index is partly loaded at session start, while topic files are read when needed. Use /memory to inspect, edit, disable, or remove saved entries.

Keep Configuration Reviewable

Keep CLAUDE.md short enough to review and specific enough to alter behavior. Put shared commands and repository rules at the root, move domain detail into imports or path rules, and reserve skills for routines that load on demand. Check /context when a session drifts, then move must-hold boundaries out of prose and into enforcement.

Updated July 2026 with facts checked against official Anthropic sources on July 28, 2026.