CLAUDE.md Scope Hierarchy
| Scope | File Location | Shared With Team? | Use For |
|---|---|---|---|
| Enterprise managed policy | Deployed by org IT/security, outside any repo | N/A - organization-wide, always wins | Non-overridable org policy |
| Project-level | CLAUDE.md at repo root | Yes - checked into version control | Build/test commands, architectural conventions, style rules |
| User-level | ~/.claude/CLAUDE.md | No - individual only | Personal preferences, individual tooling shortcuts |
@path/to/file imports let a root CLAUDE.md pull in more detailed docs (e.g. a testing guide) without bloating the file loaded every session.
Key exam rule: match guidance scope to file scope - team-wide conventions go in the committed project file; personal preferences go in the user-level file only. Mixing the two bloats the shared file with noise no teammate needs.
Permission System: allow / ask / deny
Configured in settings.json (not CLAUDE.md prose). Rules are Tool(pattern) strings, e.g. Bash(git commit:*), Bash(rm:*), Edit.
| List | Behavior |
|---|---|
| allow | Runs without prompting |
| ask | Prompts the user before running |
| deny | Blocked outright, no prompt |
| Settings File | Scope |
|---|---|
| .claude/settings.json | Project - checked in, shared with team |
| .claude/settings.local.json | Individual - gitignored personal overrides |
| ~/.claude/settings.json | User - across all of that person's projects |
| Enterprise-managed file | Organization - always wins |
Precedence rule (exam-critical): within permission evaluation, a matching deny always beats a matching allow, regardless of which file each rule came from. You cannot allow-list your way past a deny.
Hooks, Slash Commands & Session Reset
| Hook Event | Fires When | Can Block? |
|---|---|---|
| PreToolUse | Before a tool runs | Yes - exit code 2 blocks it |
| PostToolUse | After a tool runs | No - reacts to the result |
| UserPromptSubmit | User submits a prompt | No |
| Stop | Claude finishes responding | No |
Hook scripts receive event JSON on stdin. Exit 0 = continue normally. Exit 2 = block the action; stderr is fed back to Claude as the reason so it can adjust and retry.
| Command | Effect | When to Use |
|---|---|---|
| /clear | Wipes context, starts fresh | Switching to an unrelated task |
| /compact | Summarizes and shrinks the conversation | Same task, conversation approaching the context window |
| /permissions, /mcp | Inspect current permission / MCP config | Debugging a missing tool or unexpected block |
Custom /name | Runs a Markdown template from .claude/commands/ | Packaging a repeated prompt; $ARGUMENTS substitutes trailing text |
Headless Mode Output Formats
claude -p "<prompt>" (or --print) runs to completion with no REPL and no human - the CI shape. Returns a non-zero exit code on failure so a pipeline step can branch on it.
| --output-format | Returns | Use When |
|---|---|---|
| text (default) | Plain text final response | Human reading a log - fragile for scripts |
| json | One JSON object: result, session ID, usage/cost | CI script needs to parse pass/fail - the reliable choice |
| stream-json | Newline-delimited JSON events as the run progresses | Long CI step; want progress streamed into the log |
Scoping an Unattended Run
| Flag | Controls |
|---|---|
| --allowedTools | Explicit tool allowlist for this invocation |
| --disallowedTools | Explicit tool denylist for this invocation |
| --permission-mode plan | Produces a plan, executes nothing |
| --permission-mode acceptEdits | Auto-approves file edits, still gates other risky actions |
| --permission-mode bypassPermissions | Skips permission checks entirely |
| --max-turns N | Caps agentic turns - bounds time and cost |
bypassPermissions / --dangerously-skip-permissions removes the only safety net in an unattended run. Use it only inside an ephemeral, sandboxed CI container with no access to real credentials or production systems - never on a shared runner or dev machine.
CI Auth & Session Hygiene
- Authenticate with the
ANTHROPIC_API_KEYenvironment variable sourced from the CI provider's secret store - never hardcoded or committed. - Interactive
claude loginneeds a browser and a human; it does not work on a CI runner. - Each run should start a fresh session - do not pass
--resumeor--continue, which pull in a prior run's context and break reproducibility. - The official
anthropics/claude-code-actionGitHub Action wraps headless mode for@claudementions on issues/PRs; needs repo permissions (e.g.contents: write,pull-requests: write) plus the API key as a repo secret.
| Distractor | Correct Practice |
|---|---|
| Parse free-text output with regex | Request --output-format json |
| Reuse one long-lived session across CI runs | Fresh session per run - avoid --resume/--continue |
| Use bypassPermissions as a general CI convenience | Restrict it to ephemeral, sandboxed, credential-free containers |
Rely on claude login in CI | Use ANTHROPIC_API_KEY from the secret store |