CLAUDE.md, rules, and settings for Claude Code

Summary

`CLAUDE.md`

durable project context and instructions loaded into the conversation.

Path rules

smaller Markdown instruction files under `.claude/rules/`, optionally limited to matching paths.

Shared project settings

team configuration for permissions, hooks, environment values, plugins, and supported defaults.

Local project settings

personal overrides that should not be committed.

`CLAUDE.local.md`

personal instructions for one project; add it to `.gitignore`.

Hooks, permissions, sandboxing, tests, and policy

use these when a rule must be enforced rather than merely requested.

Choose the right instruction surface

A useful Claude Code setup separates knowledge, preference, and enforcement. Project architecture and ordinary workflow guidance belong in context. File-specific conventions belong in path-scoped rules. Permissions, hooks, sandbox settings, and other client behavior belong in settings. A repeated procedure may belong in a skill. A command that must run at a lifecycle event belongs in a hook.

`CLAUDE.md` is not a security boundary. Anthropic describes it as context that Claude reads and tries to follow. A vague or conflicting line can be ignored or applied inconsistently. Use settings, permission rules, hooks, operating-system controls, review, and tests for a requirement that must hold.

Read Anthropic's current guide to CLAUDE.md, rules, imports, loading, and auto memory.

Understand CLAUDE.md scopes

Managed policy

an organization-wide `CLAUDE.md` deployed by IT or DevOps for company standards and policy.

User

`~/.claude/CLAUDE.md` for personal preferences that apply across projects.

Project

`./CLAUDE.md` or `./.claude/CLAUDE.md` for team-shared project architecture, commands, standards, and workflow.

Local

`./CLAUDE.local.md` for personal project details that stay outside source control.

Nested

a `CLAUDE.md` in a subdirectory for instructions that belong to that part of the repository.

Claude Code walks upward from the working directory and loads discovered ancestor instruction files. It concatenates them rather than treating the closest file as a complete replacement. Files below the working directory load when Claude reads files in those areas. Within a directory, local instructions follow the shared file. Conflicting rules can still create uncertain behavior, so audit the complete loaded set with `/memory`.

A gitignored `CLAUDE.local.md` exists only in the worktree where it was created. If the same personal rule must apply across worktrees, keep it in the user file or import a trusted file from the home directory. Do not commit local URLs, credentials, or personal test data.

Create a project file with `/init`

Run `/init` in the project root to generate a starting file. Claude inspects the repository for commands and conventions. If a file already exists, the current workflow proposes improvements instead of replacing it. Review the result as code. Remove guessed facts, add missing boundaries, run every command, and ask another maintainer to approve team-wide instructions.

A practical CLAUDE.md structure

1. 1Purpose: one paragraph explaining what the product does and who it serves.
2. 2Repository map: the few directories and sources of truth that prevent navigation mistakes.
3. 3Commands: exact install, development, test, type-check, lint, build, and targeted verification commands.
4. 4Architecture: boundaries, ownership, generated files, schemas, and patterns that are not obvious from one file.
5. 5Workflow: branch, ticket, review, migration, release, and documentation steps the team actually follows.
6. 6Constraints: concrete prohibited actions, security boundaries, compatibility requirements, and approval gates.
7. 7Definition of done: the checks and evidence required before work can be handed off.

Write rules a reviewer can verify. Prefer `Run bun test before commit` to `test your work`. Prefer `API handlers live in src/api/handlers` to `keep files organized`. Explain the reason only when it helps someone apply the rule in a new case. Avoid broad style advice that duplicates the formatter, linter, compiler, or documentation.

Anthropic currently recommends keeping each file concise and targeting fewer than 200 lines. Every startup instruction consumes context. A large file can reduce adherence, especially when it mixes universal rules with rare procedures. Remove stale entries during normal maintenance instead of treating the file as an append-only notebook.

Organize focused Claude Code rules

Markdown files under `.claude/rules/` let a team split one long instruction file by topic. These Claude rules can load for the whole project or use `paths` frontmatter for matching files. Use separate guidance for testing, API work, database changes, UI, documentation, or releases when it does not belong in every session.

• Give each rule file one clear owner and purpose.
• Use path patterns narrow enough to exclude unrelated code.
• Keep shared rules in source control and review them like implementation changes.
• Check for contradictions with ancestor files, nested files, managed policy, and personal instructions.
• Move a multi-step reusable procedure to a skill when it requires more than standing guidance.
• Use a hook or tool permission when compliance cannot depend on model instruction-following.

Configure the client with settings.json

The phrase Claude settings.json usually refers to the configuration files Claude Code reads at several scopes. User scope applies across projects. Shared project scope belongs in source control, while local project scope stays uncommitted. Managed settings provide organization policy. Many CLI flags and environment variables can also affect a session. Use the directory explorer below for the current exact paths.

Use settings for supported permissions, hooks, environment values, model defaults, sandbox behavior, plugins, and other client configuration. Project settings can take precedence over user choices, while array settings can merge across scopes. Managed policy cannot be weakened by a project. Check the current settings reference before assuming that an object replaces or extends a value.

Do not try to point Claude Code at an instruction file with a `claudeMd` key in ordinary user, project, or local settings. The current memory documentation says that setting has no effect at those scopes. Use the documented file locations or imports. Managed deployments have separate supported policy mechanisms.

Check the current Claude Code settings scopes, precedence, schema, and supported keys.

What belongs in the .claude directory?

The .claude directory is the project home for more than instructions. It can contain `CLAUDE.md`, `rules/`, shared and local settings, skills, commands, agents, output styles, and related configuration. Hooks are defined through settings. Other project configuration, such as `.mcp.json`, remains at the repository root. Do not invent a file location because it looks tidy; use the documented scope for that feature.

Use Anthropic's .claude directory explorer to verify each file, scope, and commit rule.

Use imports without hiding the source of truth

A `CLAUDE.md` file can import another file with `@path/to/file`. Relative paths resolve from the file that contains the import. Current documentation allows recursive imports up to five levels. External imports trigger a trust prompt when first encountered. Imports help organization, but imported content still enters the startup context, so they do not solve an oversized instruction set.

Claude Code reads `CLAUDE.md`, not `AGENTS.md`, by default. A repository that supports several agents can create a short `CLAUDE.md` containing `@AGENTS.md`, then add Claude-specific instructions below it. A symbolic link also works where the operating system and repository policy support it. Review shared content for instructions that conflict across tools.

Protect secrets

• Do not place API keys, access tokens, passwords, private customer data, or production secrets in committed instructions or settings.
• Deny access to sensitive paths through current permission controls; a sentence saying not to read a secret is not equivalent.
• Use hooks and continuous integration for checks that must run at a specific point.
• Use a sandbox and operating-system boundaries to limit file and network access where the workflow requires isolation.
• Keep generated or managed policy distinct from editable team guidance, and document who can change each layer.
• Review pull requests that alter instructions, permissions, hooks, plugins, MCP servers, or executable commands as security-sensitive changes.

Why is Claude not following CLAUDE.md?

1. 1Run `/memory` and confirm that the expected project, ancestor, local, nested, and rule files are loaded.
2. 2Reduce the failure to one instruction and one representative task.
3. 3Rewrite vague wording as a specific action with a path, command, condition, or observable result.
4. 4Search every loaded source for conflicts, including managed policy, user instructions, imports, and path-scoped rules.
5. 5Remove stale or duplicated rules and keep the smallest source of truth.
6. 6If a requirement needs deterministic enforcement, implement it with settings, permissions, hooks, tests, policy, or another suitable control.

Frequently asked questions about CLAUDE.md

Project instruction audit

• Every instruction has the narrowest correct scope and a clear owner.
• All commands, paths, and architectural facts were verified in the current repository.
• Shared, personal, managed, and local content are separated.
• Path-specific guidance lives in rules instead of the global startup context.
• Enforced requirements use deterministic controls.
• No secrets or private environment details are committed.
• Imports are trusted, short, and traceable to a maintained source.
• The complete loaded instruction set has no known conflicts.
• A representative task shows whether the intended behavior occurs.
• The team reviews and prunes configuration as the project changes.