Shared Instructions and Org Policies

When you work alone, CLAUDE.md is just for you. Write whatever rules you want, tweak them whenever.

The moment a second person starts using Claude Code on the same repo, everything changes. You need consistency. Everyone's Claude Code following the same conventions, the same testing patterns, the same architectural boundaries. Without shared instructions, you get chaos. One developer's Claude produces camelCase, another's produces snake_case. One writes Jest tests, another writes Vitest tests.

Claude Code has a layered system for this. Each layer has a different scope, and they stack.

The Four Layers of CLAUDE.md

Claude Code loads instructions from four places, in this order:

1. Managed policy (org-wide, highest authority). IT or platform teams deploy this to every machine.
2. User instructions at ~/.claude/CLAUDE.md. Your personal preferences, all projects.
3. Project instructions at ./CLAUDE.md or ./.claude/CLAUDE.md. Checked into version control, shared with the team.
4. Local instructions at ./CLAUDE.local.md. Personal overrides for this specific project. Not in git.

All four merge together. Later layers add to earlier ones but can't override managed policy. Managed always wins.

Project-Level CLAUDE.md

Most common starting point. Create a CLAUDE.md at your repo root and commit it. Everyone who opens Claude Code in that repo gets the same baseline.

A good team CLAUDE.md covers the things that cause fights:

# Project Instructions
 
## Architecture
- Next.js App Router with TypeScript
- Server components by default. Only use "use client" when necessary.
- Styles via Tailwind CSS v4 (config in globals.css, not tailwind.config.js)
 
## Testing
- Every new function needs a unit test in the adjacent __tests__ directory
- Use vitest, not jest
- Run `npm test` before suggesting a task is complete
 
## Git
- Commit messages follow conventional commits (feat:, fix:, chore:)
- Never force push to main
- Never skip pre-commit hooks

New developer joins, clones the repo, Claude Code immediately knows the rules. No onboarding doc to read. No "ask Sarah how we do testing here."

The .claude/rules/ Directory

A single CLAUDE.md works for small projects. For larger codebases it gets unwieldy fast. The .claude/rules/ directory lets you split instructions into separate files:

.claude/
  rules/
    testing.md
    api-design.md
    security.md
    frontend/
      components.md
      accessibility.md

Claude Code discovers these recursively. Organize into subdirectories however you want. Each file covers one concern, making them easy to maintain and review in PRs.

The really useful bit is path-specific rules. Add YAML frontmatter so a rule only activates when Claude touches matching files:

---
paths:
  - "src/api/**/*.ts"
---
 
# API Development Rules
 
- All endpoints must validate input with zod schemas
- Return standardized error responses using the ApiError class
- Include rate limiting headers in every response
- Log request duration to the metrics service

This rule only loads when Claude touches files matching src/api/**/*.ts. Frontend developers never see API rules cluttering their context. API developers get them automatically.

Rules without paths frontmatter load unconditionally, same as content in the main CLAUDE.md. You can also symlink rules across repositories if your org has a central set of coding standards.

Managed Policy for Organizations

For larger organizations, project-level instructions aren't enough. Some rules need to be enforced everywhere. Every repo, every developer, no exceptions.

Managed CLAUDE.md files live at system-level paths:

• macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
• Linux/WSL: /etc/claude-code/CLAUDE.md
• Windows: C:\Program Files\ClaudeCode\CLAUDE.md

Deploy them through whatever you already use. MDM on macOS, Group Policy on Windows, Ansible or Chef on Linux. The mechanism doesn't matter. What matters is that individual developers can't exclude or override these.

A managed policy might look like:

# Organization Policy
 
- Never commit secrets, API keys, or credentials to any file
- All code must be compatible with Node 20 LTS
- Do not install packages from outside the approved registry
- Security-sensitive changes require a second review

These load before everything else. Can't be bypassed with claudeMdExcludes or any local setting. Your security team can actually rely on them.

Managed Settings and Permissions

Beyond instructions, you can enforce specific Claude Code settings org-wide: permission configs, approved tools, behavioral defaults.

Share approved permissions through .claude/settings.json in version control:

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npm run build)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)"
    ]
  }
}

Commit this file. Every team member gets the same allowlist and denylist. Dangerous commands blocked. Safe ones run without prompts. No more "are you sure?" fatigue for npm test.

For org-wide enforcement, OpenTelemetry metrics and ConfigChange hooks give platform teams visibility into how Claude Code is being used across the org.

CLAUDE.local.md for Personal Overrides

Your team has shared rules. Your org might have managed policy. But you've still got personal preferences. Maybe you prefer explicit types over inference. Maybe single-letter variables drive you crazy.

CLAUDE.local.md is your escape hatch. Place it at the project root, add to .gitignore:

# My local preferences
 
- I prefer explicit types over inference in TypeScript
- When writing commit messages, include the ticket number from my branch name
- Use verbose variable names. I find single-letter variables hard to scan.

Layers on top of the shared CLAUDE.md. Never gets committed, teammates never see it. You can also put user-level rules in ~/.claude/rules/ for preferences that apply to every project.

claudeMdExcludes for Monorepos

Large monorepos have CLAUDE.md files scattered across packages. Working in packages/auth/? You don't want instructions from packages/billing/CLAUDE.md polluting your context.

Exclusion patterns in .claude/settings.local.json:

{
  "claudeMdExcludes": [
    "packages/billing/**",
    "packages/legacy/**",
    "apps/deprecated-admin/**"
  ]
}

Glob patterns, matched against absolute file paths. Keeps your context clean. One constraint: managed policy files can't be excluded. Those always load.

Try It

Set up a layered instruction system for a real project:

1. Create .claude/rules/ in your repo.
2. Add testing.md with your team's testing conventions (no frontmatter, loads globally).
3. Add frontend.md with path-specific rules using paths: ["src/components/**"] in the frontmatter.
4. Create CLAUDE.local.md at the project root with one personal preference. Add it to .gitignore.
5. Open Claude Code and ask "what instructions are you following?"

You'll see everything it loaded and where each instruction came from. The layers merge exactly as described.

The whole system boils down to one idea: conventions that travel with the code. Project CLAUDE.md gives you baseline rules on clone. .claude/rules/ lets you split those rules by concern and scope them to specific file paths. Managed policy handles the non-negotiable org standards nobody can bypass. And CLAUDE.local.md is your personal escape hatch that never touches git.