Configuration Layers

Where each rule, skill, agent and hook is installed, and which layer wins when two of them say different things. More specific always wins: a project’s CLAUDE.md overrides the global manifest, and CLAUDE.local.md overrides both.

Every setting these files hold is listed in the Configuration Reference.

~/.claude/CLAUDE.md                ← Global agent manifest (base)
~/.claude/rules/*.md               ← Global rules (always loaded, 4 files)
  ├── coding-standards.md              Quality gates, prohibited patterns, verification discipline…
  ├── copilot-conventions.md           Cross-copilot portable conventions: target alignment…
  ├── copyright-headers.md             Copyright header rules for generated source files. Applies…
  └── safety.md                        Non-negotiable safety constraints: destructive action guards…
~/.claude/skills/*/SKILL.md        ← On-demand skills (SKILL.md format, 20 skills)
  ├── agent-team-protocol/             Multi-agent delegation rules, three-phase workflow…
  ├── auto-build-loop/                 Autonomous build driver after SDD spec approval: phase-scoped…
  ├── clarification-protocol/          When and how to ask clarifying questions before implementing.…
  ├── design-system/                   Derive a unique, domain-fit design direction and enforce…
  ├── environment-setup/               Environment variable patterns, config file validation, and…
  ├── infra-verification/              Infrastructure artifact verification: Docker builds, CI…
  ├── integration-testing/             Test integration points early. Verify cross-service…
  ├── memkernel-memory/                MemKernel persistent memory protocol. Self-guarding…
  ├── opus-4-7-features/               Optional guidance for sessions using Claude Opus 4.7…
  ├── origin-confirmation/             Origin-confirmation circuit breaker: machine-checkable origin…
  ├── phase-workflow/                  Phase transition rules, post-phase verification steps, peer…
  ├── provider-collaboration-protocol/ Cross-provider peer review protocol: session flags, review…
  ├── ralph-loop/                      Single-agent autonomous iteration loop: PRD-driven…
  ├── review-loop/                     Agent-driven peer review loop: structured findings…
  ├── spec-workflow/                   SDD specification protocol: risk-based spec_mode…
  ├── stack-constraints/               Stack version pinning and dependency compatibility guards.…
  ├── team-lead-efficiency/            Build team lead efficiency rules: limit sub-agents, polling…
  ├── token-efficiency/                Token economy rules: diff-over-rewrite, context compression…
  ├── visual-review/                   Closed visual-review loop for generated UI: render the…
  └── wiki-first-query/                Wiki-first query convention: consult knowledge/wiki/index.md…
~/.claude/agents/*.md              ← Phase + utility agents (14 files)
  ├── build.md                         Decomposes approved plans into tasks, delegates to…
  ├── code-simplifier.md               Reviews recently changed code for unnecessary complexity.…
  ├── cooldown-report.md               Generates a cooldown report — bug fixes shipped + pitches…
  ├── cycle-retro.md                   Generates a cycle retrospective from pitch.md, hill.json, and…
  ├── doc-writer.md                    Generates and updates project documentation after feature…
  ├── phase-recap.md                   Generates a phase recap document summarizing what was built…
  ├── pitch-shaper.md                  Takes a rough idea, asks clarifying questions, and produces a…
  ├── plan.md                          Asks clarifying questions, produces implementation plans with…
  ├── research.md                      Explores codebase, reads docs, searches the web. No code…
  ├── review.md                        Holistic review of all changes — correctness, consistency…
  ├── scope-executor.md                Executes a single scope of an active Shape-Up pitch. Reads…
  ├── security-review.md               Scans code for common security vulnerabilities. Checks for…
  ├── verify-app.md                    Runs end-to-end verification of the project. Executes test…
  └── visual-reviewer.md               Drives the visual-review loop for generated UI — boots the…
~/.claude/hooks/*.sh               ← Deterministic lifecycle hooks (always active, 11 files)
  ├── auto-format.sh                   After a source file is edited, auto-detects and runs the…
  ├── memkernel-post-compact.sh        PostCompact hook: recover MemKernel context after compaction…
  ├── memkernel-pre-compact.sh         PreCompact hook: save a MemKernel checkpoint before…
  ├── memkernel-recall.sh              SessionStart hook: recall MemKernel context (self-guarding…
  ├── notify.sh                        Sends a workspace-aware notification when Claude Code fires a…
  ├── peer-review-on-stop.sh           Validates that the review loop completed before the session…
  ├── protect-files.sh                 Blocks edits to protected files: .env, *.lock, .git/*…
  ├── protect-git.sh                   Guards git commit and git push. On first attempt, blocks and…
  ├── reinject-context.sh              After compaction or session start, re-injects critical…
  ├── verify-after-edit.sh             After a source file is edited, auto-detects and runs the…
  └── verify-on-stop.sh                When Claude finishes responding, auto-detects and runs the…
~/.claude/settings.json            ← Hooks wiring and global settings
./CLAUDE.md                        ← Project-level (overrides global)
./.claude/commands/*.md            ← Project slash commands
./CLAUDE.local.md                  ← Personal overrides (gitignored)

Project-level rules override global rules. More specific always wins.

Project-level rules override global rules. More specific always wins.