Scope is part of the answer

The problem

A development team discovers an effective prompt instruction — "always run the linter before finishing a file edit" — and places it into the root project CLAUDE.md. Three weeks later, an engineer working on a standalone script without configured linter dependencies watches Claude repeatedly fail while attempting to execute a non-existent linter binary. The instruction itself was sound. The configuration scope was wrong.

This is the most common architectural error in Claude Code configuration: treating every instruction as a global rule that must apply everywhere, at all times. Certification scenarios evaluate this exact judgment — not merely knowing that CLAUDE.md exists, but deciding where an instruction, custom command, or rule should reside.

Four concentric scopes, four distinct architectural answers

Claude Code features a hierarchical configuration architecture with concentric scopes, each answering a distinct organizational question:

• User scope (~/.claude/): "Is this an individual preference that I want active across every project I touch?" Personal shortcuts and developer-specific preferences live here.
• Project scope (.claude/ in the repository, versioned): "Is this a shared team convention that every engineer collaborating on this repository must follow?" Project CLAUDE.md, shared commands, and team Skills belong here.
• Path-scoped rules (Markdown files in .claude/rules/ with a paths glob in YAML frontmatter): "Does this rule apply strictly when modifying a specific subdirectory or file pattern?" The linting rule from the opening scenario belongs in a path rule targeting paths: ["src/api/**"], not as a global instruction in root CLAUDE.md.
• Session/ephemeral scope: Directives relevant only to the active prompt turn that should not persist beyond the immediate task.

The central question in architecture scenarios is rarely "is this prompt instruction useful?" — it usually is. The real question is: "is this instruction valid across every scope where it will be ingested?" A useful rule placed in an overly broad scope constitutes a broken configuration.

Skills: scoped execution and structural contracts

A Skill (.claude/skills/<name>/SKILL.md) formalizes configuration logic into a modular, reusable package. The YAML frontmatter of a Skill defines key architectural properties:

• context: fork: The Skill executes inside an isolated context window, preventing speculative discovery from polluting the primary parent session.
• allowed-tools: The Skill is strictly restricted to explicitly listed tools, regardless of broader permissions granted to the parent session.
• argument-hint: Documents expected parameter formats, reducing input ambiguity.

A frequent antipattern is treating allowed-tools as informal documentation rather than an access control boundary. A code review Skill that lists Bash under allowed-tools without operational necessity inflates the attack surface. Always ask: "what tools does this Skill strictly require to satisfy its contract?", not "what tools might be convenient."

Headless CI: structured outputs over terminal prose

Running Claude Code non-interactively in CI pipelines (-p or --print with --output-format json) fundamentally alters execution parameters: there is no human operator in the loop to interpret subtle terminal output. This implies two core design requirements:

1. Output must be structured as machine-readable JSON so downstream pipeline steps or bot orchestrators can execute automated gating decisions.
2. A headless execution that modifies production code without independent verification introduces severe deployment risk. The mature pattern employs decoupled passes: one pass generating candidate changes, and an independent review pass — in a clean session without generative context bias — evaluating empirical test evidence before approving merges.

A classic scenario distractor proposes that headless CI is self-sufficient without independent review because "--output-format json already ensures quality." Structured formats guarantee that outputs are parseable. They provide zero guarantee that completions are correct.

Put it into practice

In this lesson's lab, you will audit a suite of configuration directives across user, project, and path scopes, reassigning each rule to its correct tier (promoting, demoting, or converting into path-scoped rules).