CLAUDE.md: global and project
Use global CLAUDE.md for personal operating preferences that apply everywhere. Use project CLAUDE.md for repo facts, commands, safety rules, and review standards the whole team should share.
Claude Code does not get better because every rule is added to one giant file. The stronger setup puts durable context in CLAUDE.md and enforceable constraints in the layers that can actually enforce them.
Use global CLAUDE.md for personal operating preferences that apply everywhere. Use project CLAUDE.md for repo facts, commands, safety rules, and review standards the whole team should share.
Settings belong to deterministic tool behavior such as permissions, hooks, and feature toggles. Do not bury a permission rule in prose when the settings layer can enforce it.
Hooks are for checks that must run at a predictable moment. Use them for formatting, generated-file guards, security scans, or other rules where failure should be mechanical.
Slash commands and skills are best for repeatable workflows with named inputs and outputs. Keep durable repo policy in CLAUDE.md, then let commands call that policy during specific tasks.
MCP rules belong where external tools, data sources, or write actions are granted. Treat them as capability boundaries, not as a place for general coding style.
Runtime versions, secrets availability, network access, and sandbox limits shape what the agent can actually do. Put stable facts in the harness and verify volatile facts with commands.
If the rule is project knowledge, put it in project CLAUDE.md.
If the rule blocks a dangerous action, enforce it in settings, hooks, or permissions.
If the rule describes one repeatable workflow, put it in a slash command or skill.
If the rule differs by machine, document the environment variable or command that proves it.
If the rule appears in more than one layer, name the source of truth.
AgentLint checks the harness around Claude Code: CLAUDE.md, AGENTS.md, adjacent rule files, CI, and hooks.
Install AgentLint