<div style="display: none;" hidden="true" aria-hidden="true">Are you an LLM? You can read better optimized documentation at /guides/claude/developer-overrides.md for this page in Markdown format</div>

Per-Developer Overrides

See also: System Overview | Agent Catalog | Repo Flexibility | Usage Guide

How to customize Claude Code configuration for your local workflow without affecting the team's shared setup.

---

Quick Start

1. Open .claude/settings.local.json (gitignored) and add your preferred permissions
2. Start a session — the shared detect-repo.sh hook runs automatically
3. Rules in .claude/rules/ load automatically when you access matching files

No other setup required. Everything below is optional customization.

---

Override Hierarchy

Settings are resolved from highest to lowest priority. Higher layers override lower ones.

Priority	Source	Scope	Committed?
1	CLI flags (--agents, --allowedTools)	Session only	No
2	.claude/settings.local.json	Per-developer	No (gitignored)
3	.claude/settings.json	Team-shared	Yes
4	~/.claude/settings.json	User-level (all projects)	No

Merge Behavior

Feature	Behavior
Permissions	Arrays merge across scopes. Deny wins absolutely at any layer.
Hooks	All scopes fire (merge, not override). Cannot remove a shared hook.
Agents	Same-name file: project-level wins over user-level.
Rules	Merge additively across project and user levels.
CLAUDE.md	All files loaded (project + user + directory-specific).
Skills	No user-level override mechanism.

Full Override Matrix

Feature	User (~/.claude/)	Project Local (settings.local.json)	Project Shared (.claude/)
Permissions	settings.json	settings.local.json	settings.json
Hooks	settings.json	settings.local.json	settings.json
Agents	agents/*.md	deny via permissions	agents/*.md
Rules	rules/*.md	—	rules/*.md
CLAUDE.md	CLAUDE.md	exclude via claudeMdExcludes	./CLAUDE.md
MCP Servers	~/.claude.json	—	.mcp.json
Keybindings	keybindings.json	—	—
Skills	—	—	skills/*/

---

Common Recipes

1. Auto-Allow Common Commands

Add to .claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Bash(vendor/bin/phpunit:*)",
      "Bash(php:*)",
      "Bash(git add:*)",
      "Bash(git push:*)",
      "Bash(npm run:*)",
      "Bash(composer:*)",
      "Skill(code-reviewer)"
    ]
  }
}

2. Disable Unused Agents

If you never use certain agents, deny them in settings.local.json:

{
  "permissions": {
    "deny": [
      "Agent(feed-writer)",
      "Agent(patcher-writer)"
    ]
  }
}

3. Add Personal MCP Servers

MCP servers are configured per-project in ~/.claude.json (user-level):

{
  "projects": {
    "/path/to/adveshop4": {
      "mcpServers": {
        "my-db-tool": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://..."]
        }
      }
    }
  }
}

Team-shared MCP servers go in .mcp.json at the project root.

4. Add Personal Rules

Create rules in ~/.claude/rules/ that apply to all your projects:

<!-- ~/.claude/rules/my-preferences.md -->
---
paths:
  - "**"
---
When generating PHP code, always add a blank line before return statements.

Or project-scoped rules in .claude/rules/ (these are committed).

5. Personal CLAUDE.md Preferences

Create ~/.claude/CLAUDE.md for instructions that apply across all projects:

# Personal Preferences
- Always explain architectural decisions before implementing
- Use verbose git commit messages
- Prefer explicit type hints in PHP

6. Override an Agent's Model

To use a different model for a specific agent, create a same-named file at ~/.claude/agents/:

<!-- ~/.claude/agents/schema-analyzer.md -->
---
model: haiku
---
(copy the full agent content from .claude/agents/schema-analyzer.md)

The user-level file is used when no project-level file exists. Since our project commits agents, the project version takes precedence. To truly override, you'd need to use CLI flags or deny+recreate.

7. Exclude Specific CLAUDE.md Files

If a directory-level CLAUDE.md conflicts with your workflow:

{
  "claudeMdExcludes": ["path/to/specific/CLAUDE.md"]
}

Add this to .claude/settings.local.json.

8. Add Personal Hooks

Add hooks in ~/.claude/settings.json (user-level) — they fire alongside project hooks:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'File written: $TOOL_INPUT_FILE_PATH'"
          }
        ]
      }
    ]
  }
}

---

Clean settings.local.json Template

Starting point for new developers:

{
  "permissions": {
    "allow": [
      "Bash(vendor/bin/phpunit:*)",
      "Bash(php:*)",
      "Bash(git add:*)",
      "Bash(git push:*)",
      "Skill(code-reviewer)"
    ]
  }
}

---

Client Repo Notes

The same override mechanisms work identically in client repos:

• .claude/settings.local.json — per-developer permissions
• ~/.claude/agents/ — personal agent overrides
• ~/.claude/rules/ — personal rules
• ~/.claude.json — personal MCP servers

The detect-repo.sh hook auto-detects the repo type. Agents automatically switch to client mode (writing to custom/ and application/ instead of src/ and ecommercen/).

---

What NOT to Override

These are critical shared infrastructure — overriding them will break agent behavior:

Item	Why
Skills (.claude/skills/)	Knowledge bases agents depend on. No user-level override mechanism exists.
SessionStart hook (detect-repo.sh)	Repo detection is critical for all agents. Hooks merge — you can't remove a shared hook.
CLAUDE.md core conventions	Agent delegation rules, namespace patterns, file structure. Wrong overrides cause bad code generation.
Agent workflow logic	Encodes correct generation pipelines. Changing model is fine; changing logic risks broken output.

---

File Reference

File	Location	Committed?	Purpose
.claude/settings.json	Project	Yes	Team hooks
.claude/settings.local.json	Project	No	Developer permissions
.claude/agents/*.md	Project	Yes	Shared agent definitions
.claude/skills/*/	Project	Yes	Shared skill knowledge bases
.claude/rules/*.md	Project	Yes	Path-specific conventions
CLAUDE.md	Project root	Yes	Core project instructions
.mcp.json	Project root	Yes	Team MCP servers
~/.claude/settings.json	User home	No	User-level settings/hooks
~/.claude/agents/*.md	User home	No	Personal agent overrides
~/.claude/rules/*.md	User home	No	Personal rules
~/.claude/CLAUDE.md	User home	No	Personal instructions
~/.claude.json	User home	No	Personal MCP servers