It’s pretty important to have a tight control on how our Claude Code is configured. The more we understand how it’s set, the more confident we can be that our agents will do what we want them to do, and avoid unwanted consequences.
As we’re in the infancy of this tech, and things change very quickly, have in mind I’m writting this on October 2026, and things might change drastically in the future.
Understanding configuration levels
Claude has 3 levels worth mentioning
- Enterprise-level: This is the highest level and the one we have the least control. This is meant for your organization to push rules/restrictions to your harness. If you use Claude outside an organization (just for yourself), you can disregard this.
- User-level: These are configurations that rule all projects in our machine.
- Project-level: Rules that affect only the session started from that specific folder/workspace.
Deterministic vs non-deterministic rules and constrains
There are reasons why we would add rules or constraints in different places.
CLAUDE.MD
Claude’s main entry point. This file will always be read first, loaded into the context and, most of the time, be the main set of instructions.
ANYWAYS… rules like “don’t use X tool” or “never execute Y” are honestly a hit and miss. Many times I got to remind Claude to stop doing something I added in my user level
CLAUDE.MDjust to get the classic “oh right, sorry, I missed that, it won’t happen again”. Hooks are the way to go for those cases.
Keep more broad, less important information here, like “response style” or “verbostity level” because CLAUDE.MD is non-deterministic. 1
Also, keep this file as short as possible because this is information that is loaded in the “context”, that context is finite and we need it. Even though Anthropic doesn’t provide a specific number, general consensus is less that 200 lines is good, less than 60 ideal. 2
Hooks
On the other side, hooks are determinisitic 3. Just like git hooks, these will always be executed upon certain events.
Based on below categories, the events are:
| Category | Events |
|---|---|
| Session | SessionStart, Setup, SessionEnd |
| Turn | UserPromptSubmit, UserPromptExpansion, Stop, StopFailure |
| Agentic Loop | PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, |
| Agent/Team | SubagentStart, SubagentStop, TeammateIdle, TaskCreated, TaskCompleted |
| File/Environment | InstructionsLoaded, ConfigChange, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove, PreCompact, PostCompact |
| Notifications | Notification |
And based on those events there’s supports for multiple handler types (per documentation 4):
| Handler Type | Description |
|---|---|
| Command hooks | Run shell commands (most common) |
| HTTP hooks | POST to an endpoint |
| Prompt hooks | Inject LLM prompts |
| Agent hooks | Spawn subagents |
| MCP tool hooks | Call MCP tools directly |
There’s no need to memorize anything here, but understanding different levels, and the capabilities and limitations that exist gives us a great advantage at getting good results. That should be enough to know when to ask our agent to add a hook or a rule, and at what level depending our workflow.
-
“Non-Deterministic AI” can yield different outputs from the same input due to its reliance on probabilities and variability. ↩︎
-
These are very generic numbers that don’t have into account how many
CLAUDE.MDfiles our repo has (because it can contain many) or how much data we’re loading into the context. ↩︎ -
“Deterministic AI” produces the same output every time for a given input, ensuring predictability and repeatability. ↩︎
-
The documentation goes pretty deep into verious topics like Lifecycle and even it provide some examples of event fires. Documentation in: https://code.claude.com/docs/en/hooks ↩︎