Overview

Claude Code uses a three-level configuration hierarchy that separates personal preferences, team-shared settings, and local overrides. This architecture follows official best practices and ensures clean separation between user-level automation and project-specific configuration.

The Three Levels

graph TD
  A[User Level<br/>~/.claude/] --> B[Personal Config]
  A --> C[Applies to ALL projects]

  D[Repo Level<br/>repo/.claude/] --> E[Team-Shared Config]
  D --> F[Committed to git]

  G[Local Level<br/>repo/.claude/*.local.*] --> H[Personal Overrides]
  G --> I[Gitignored]

  B --> J[Resolution Order]
  E --> J
  H --> J
  J --> K[Local > Repo > User]

  style A fill:#F55036,color:#fff
  style D fill:#3B82F6,color:#fff
  style G fill:#2D7A4F,color:#fff

Why This Architecture?

• Clear boundaries: Personal vs team-shared vs local overrides
• Portability: Repos work independently without workspace dependencies
• Collaboration: Team members share the same base configuration
• Flexibility: Personal customization without affecting the team
• Official compliance: Follows Claude Code best practices exactly

Architecture Levels

User Level (~/.claude/)

Personal configuration that applies to all projects you work on. This is your private workspace for automation, skills, and preferences.

~/.claude/
├── CLAUDE.md                   # Global rules
├── settings.json               # User settings & permissions
├── agents/                     # Personal automation agents
│   ├── doc-syncer.md
│   ├── git-workflow-agent.md
│   └── workspace-test-runner.md
├── skills/                     # Personal workflow skills
│   ├── context-review.md
│   ├── qcheck.md
│   ├── sprint-complete.md
│   └── sprint-report.md
├── guides/                     # Reference documentation
│   └── claude-agent-sdk-guide.html
└── maintenance/                # Session workflows
  ├── session-start.md
  ├── session-end.md
  └── monthly-review.md

Repo Level (<repo>/.claude/)

Team-shared configuration committed to git. This is the official project configuration that all collaborators inherit when they clone the repository.

/.claude/
├── settings.json               # Team settings (committed)
├── settings.local.json         # Personal overrides (gitignored)
├── agents/                     # Project-specific agents
│   ├── citation-validator.md
│   └── deployment-orchestrator.md
├── skills/                     # Project-specific skills
│   └── manifest.json
└── scratch/                    # Temporary workspace (gitignored)

Local Level (<repo>/.claude/.local.)

Personal overrides for a specific project. These files are gitignored and never committed.

settings.local.json    # Personal permission overrides
CLAUDE.local.md        # Personal notes about the project
scratch/               # Temporary files

Workspace Level (~/workspace/CLAUDE.md)

A special case: your workspace can have a CLAUDE.md at the root to define conventions that apply to all repos in that directory. Important: No .claude/ directory at workspace level - only a CLAUDE.md file.

Migration Summary

On January 2, 2026, the custom three-level architecture (User/Workspace/Repo) was migrated to the official Claude Code architecture (User/Repo/Local).

What Changed

Migration Timeline

1. Backup: Full backup created at ~/workspace/docs/archives/claude-architecture-migration-2026-01-02/
2. User level: Created new directories, standardized agent formats (JSON → MD)
3. Content migration: Moved guides, skills, maintenance to user level
4. Settings consolidation: Merged permissions into user-level settings.json
5. Agent distribution: citation-validator to multiple repos, deployment-orchestrator to multiple repos
6. Repo setup: Created team settings.json, updated .gitignore in all repos
7. Cleanup: Archived workspace configuration, cleaned up directory
8. Documentation: Updated CLAUDE.md files, created architecture guide

Configuration Files

CLAUDE.md Hierarchy

CLAUDE.md files define rules and conventions. They are resolved in this order:

graph LR
  A[Code Behavior] --> B[Repo CLAUDE.md]
  B --> C[Workspace CLAUDE.md]
  C --> D[Global CLAUDE.md]

  style A fill:#2D7A4F,color:#fff
  style B fill:#3B82F6,color:#fff
  style C fill:#F59E0B,color:#fff
  style D fill:#F55036,color:#fff

1. Actual code behavior (ground truth)
2. Repo CLAUDE.md (<repo>/CLAUDE.md) - Project-specific rules
3. Workspace CLAUDE.md (~/workspace/CLAUDE.md) - Multi-repo conventions
4. Global CLAUDE.md (~/.claude/CLAUDE.md) - Universal rules

settings.json vs settings.local.json

User Level (~/.claude/settings.json)

{
  "model": "sonnet",
  "enabledPlugins": {
    "rust-analyzer-lsp@claude-plugins-official": true
  },
  "alwaysThinkingEnabled": true,
  "permissions": {
    "allow": [
      "Bash(git fetch:*)",
      "Bash(npm install)",
      "WebSearch",
      "Read($HOME/**)"
    ],
    "deny": [],
    "ask": []
  }
}

Repo Level (<repo>/.claude/settings.json)

{
  "permissions": {
    "allow": [
      "Bash(pnpm test)",
      "Bash(cargo check:*)"
    ],
    "deny": [],
    "ask": []
  }
}

Local Override (<repo>/.claude/settings.local.json)

{
  "permissions": {
    "allow": [
      "Bash(rm -rf dist/)"
    ]
  }
}

.gitignore Patterns

Every repo should include these patterns in .gitignore:

# Claude Code local overrides
.claude/settings.local.json
.claude/CLAUDE.local.md
.claude/scratch/

Agents & Skills

Where to Put Agents

Agent Format Requirements

All agents must use Markdown with YAML frontmatter:

---
name: my-agent
description: Brief description of what this agent does and when to use it
tools: Read, Bash, Grep
model: sonnet
permissionMode: default
---

# Agent Name

System prompt and instructions for the agent go here...
This defines the agent's role, expertise, and approach.

Required fields:

• name - Unique identifier (lowercase, hyphens)
• description - What the agent does AND when to invoke it (max 1024 chars)

Optional fields:

• tools - Comma-separated list; if omitted, inherits all parent tools
• model - sonnet, opus, haiku, or ‘inherit’ (defaults to sonnet)
• permissionMode - default, acceptEdits, dontAsk, bypassPermissions, plan, ignore
• skills - Comma-separated list of skills to load for this agent

Skill Discovery

Skills are discovered from two locations:

• User-level: ~/.claude/skills/ (personal workflow automation)
• Repo-level: <repo>/.claude/skills/ (project-specific tools)

Distribution Strategy

The migration distributed agents based on relevance:

• citation-validator → 6 repos (all repos with documentation)
• deployment-orchestrator → multiple repos (data-pipeline, dict-app, landing-page)
• git-workflow-agent → User level (applies to all repos)

Best Practices

When to Use Each Level

Naming Conventions

• Agents: kebab-case.md (e.g., citation-validator.md)
• Skills: kebab-case.md (e.g., sprint-complete.md)
• Settings: settings.json (team) or settings.local.json (personal)

Version Control

Examples

Creating a User-Level Skill

Create a personal workflow skill at ~/.claude/skills/my-skill.md:

---
name: my-skill
version: 1.0.0
description: My personal workflow automation
when_to_use: When I need to do X across all projects
---

# My Skill

Instructions for this skill...

Adding a Repo-Specific Agent

For a project that needs custom validation:

# Create agent directory
mkdir -p ~/projects/my-app/.claude/agents

# Create agent file
cat > ~/projects/my-app/.claude/agents/custom-validator.md << 'EOF'
---
name: custom-validator
version: 1.0.0
description: Project-specific validation rules
tools:
  - Read
  - Grep
when_to_use: Before commits in this project
---

# Custom Validator

Validation logic for this project...
EOF

# Commit to git so team gets it
git add .claude/agents/custom-validator.md
git commit -m "Add custom validator agent"

Setting Up Local Overrides

Override permissions for a specific project:

# Create local override
cat > ~/projects/my-app/.claude/settings.local.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(rm -rf dist/)",
      "Bash(docker-compose down -v)"
    ]
  }
}
EOF

# This file is gitignored - won't be committed

Multi-Repo Workflow

Working across multiple repos with consistent tooling:

1. User level: Create git-workflow-agent.md for commit/PR automation
2. Each repo: Add repo-specific settings.json with project permissions
3. Local overrides: Add settings.local.json in repos where you need exceptions

Troubleshooting

Configuration Conflicts

Permission Issues

Agent/Skill Not Found

---
name: agent-name
version: 1.0.0
description: Brief description
tools:
  - Read
  - Bash
when_to_use: When to invoke
---

Rollback Procedures

If the migration causes issues, restore from backup:

# Restore user-level config
cp -r ~/workspace/docs/archives/claude-architecture-migration-2026-01-02/user-claude-backup/* ~/.claude/

# Restore workspace configuration (if needed)
cp -r ~/workspace/docs/archives/claude-architecture-migration-2026-01-02/workspace-backup ~/workspace/.claude

# Restore specific repo
cp -r ~/workspace/docs/archives/claude-architecture-migration-2026-01-02/my-app-backup ~/projects/my-app/.claude

Quick Reference

Directory Tree Overview

~/.claude/                          # User Level (Personal)
├── CLAUDE.md
├── settings.json
├── agents/
│   ├── doc-syncer.md
│   ├── git-workflow-agent.md
│   └── workspace-test-runner.md
├── skills/
│   ├── context-review.md
│   ├── qcheck.md
│   ├── sprint-complete.md
│   └── sprint-report.md
├── guides/
│   └── claude-agent-sdk-guide.html
└── maintenance/
  ├── session-start.md
  ├── session-end.md
  └── monthly-review.md

~/workspace/CLAUDE.md             # Workspace Level (Conventions)

~/projects/my-app/                # Repo Level (Team-Shared)
├── CLAUDE.md
└── .claude/
  ├── settings.json             # Team (committed)
  ├── settings.local.json       # Personal (gitignored)
  ├── agents/
  │   ├── citation-validator.md
  │   └── deployment-orchestrator.md
  └── skills/
      └── manifest.json

Command Cheat Sheet

File Path Templates

# User Level
~/.claude/CLAUDE.md
~/.claude/settings.json
~/.claude/agents/{agent-name}.md
~/.claude/skills/{skill-name}.md
~/.claude/guides/{guide-name}.html
~/.claude/maintenance/{workflow-name}.md

# Workspace Level
~/workspace/CLAUDE.md

# Repo Level (Team-Shared)
<repo>/CLAUDE.md
<repo>/.claude/settings.json
<repo>/.claude/agents/{agent-name}.md
<repo>/.claude/skills/{skill-name}.md

# Repo Level (Personal)
<repo>/.claude/settings.local.json
<repo>/.claude/CLAUDE.local.md
<repo>/.claude/scratch/

Common Patterns