Claude Code configuration hierarchy — Labs

Labs · Lab 6 of 10

90–120 minutes active15–30 minutes setupTask 3.1: Configure CLAUDE.md files with appropriate hierarchy, scoping, and organization Task 3.2: Create and configure custom slash commands and skills Task 3.3: Apply path-specific rules for conditional convention loading Task 3.4: Determine when to use plan mode vs direct execution Task 3.5: Apply iterative refinement techniques for progressive improvement

The brief

Your assignment

Create a disposable course repository with TypeScript, Python, tests, and shared conventions. Add concise project instructions, one path-scoped rule, one reusable skill, one read-only agent, one harmless enforcement hook, and project/local settings with a precedence example. Compare plan and direct execution from identical repository states.

Before you build

Set up a safe workspace

Create a disposable mixed-language repository with tests.
Name the skill directory and use the same name in SKILL.md frontmatter.
Choose one harmless rule that a hook can enforce.

Build in checkpoints

One observable behavior at a time

01Map each instruction to its intended scope.
02Add project guidance and one path-scoped rule.
03Add the named skill and a read-only agent.
04Configure the hook and settings precedence example.
05Run the plan/direct comparison and refine from a failing test.

What you'll practice

Choose scope based on when and where guidance should load.
Separate behavioral guidance from client-enforced policy.
Build a portable skill with valid metadata.
Refine one implementation from a real failing test.

Your lab files

Four files for each lab

01
decision.md
State the requirement, chosen pattern, rejected alternatives, and the reason for the tradeoff.
02
implementation/
Keep the smallest working example, configuration, diagram, or synthetic-trace analysis.
03
evidence.md
Record test cases, observed results, failure behavior, limitations, and evidence locations.
04
review.md
Explain what must be deterministic, what may remain model-directed, and where a human is required.

Download starter templates

What to save

A configuration hierarchy map and loading table.
A valid SKILL.md whose name matches its directory.
Path-rule, read-only agent, hook, and settings examples.
An A/B execution record and test-driven refinement note.

Test bench

What good work includes

Matching and nonmatching files demonstrate scoped-rule behavior.
A clean clone receives project guidance without personal configuration.
The skill is discoverable and its name is valid.
The hook still enforces its rule after prompt guidance is removed.
Plan and direct runs begin from identical baselines.
A failing test you add before the change drives one refinement cycle.

Review questions

Why does each instruction belong where you placed it?
Which content always uses context space, even when it is not relevant?
When does planning reduce expected rework?

Strong solutions tend to

A concise, additive hierarchy.
Safe enforcement with no secrets.
A fair comparison based on the same task and baseline.

These are common strengths, not one required design.

Partial example

What useful evidence can look like

This is one small example, not a complete solution or a template you must copy. Use the notes to see why the evidence is useful.

Open annotated example from decision.md / loading table row

Rule: run Python checks for package files
Mechanism: .claude/rules/python.md
Paths: packages/**/*.py
Why here: applies by file path across several packages

Paths: Uses a recursive pattern so nested package files actually match.
Why here: Connects the mechanism to its scope instead of choosing it by habit.

Review your work

Use evidence from your work—not confidence alone. For each area, run the check and choose the strongest stage your work fully demonstrates.

If you're between two stages, use the earlier one and treat the next stage as your revision goal. There is no total score.

Scope and loading

Each instruction is stored at the narrowest scope that still reaches the intended files and collaborators.

How to check

Open matching and nonmatching files in a clean clone, then record which project, local, and path-scoped instructions load in each case.

Needs another pass

Rules are copied across levels, personal preferences are committed, or path rules load for the wrong files.

Partly demonstrated

The main scopes work, but at least one rule duplicates inherited guidance or lacks proof for a matching and nonmatching file.

Demonstrated

Root guidance is concise, lower scopes add only differences, personal settings remain local, and the loading table proves each rule appears only where intended.

Skill and agent boundaries

The reusable skill is discoverable and valid, while the read-only agent has one objective and no write capability.

How to check

Validate the SKILL.md name against its directory, invoke it directly and by relevance, then attempt a write through the read-only agent.

Needs another pass

Skill metadata is invalid or vague, or the read-only agent still receives write tools.

Partly demonstrated

The skill loads and the agent is mostly bounded, but discovery guidance, input handling, or the denied-write evidence is incomplete.

Demonstrated

The skill has valid matching metadata, clear use conditions and inputs, and the agent has a focused contract whose tool list makes an attempted write impossible.

Enforcement and settings

A harmless hook enforces one clear rule independently of prompt wording, and the settings example demonstrates precedence without exposing secrets.

How to check

Remove the matching prompt guidance, violate the rule, and show the hook still blocks or reports it. Then trace one setting through each precedence level.

Needs another pass

The required rule exists only in instructions, the hook performs unsafe side effects, or settings contain secrets.

Partly demonstrated

The hook works in the common case, but bypass behavior, failure messaging, or the settings-precedence result is unclear.

Demonstrated

The hook still enforces the documented rule after the prompt instruction is removed, fails safely with a clear message, and the settings trace shows the value used at every level.

Fair comparison and refinement

Plan and direct execution start from identical repository states, and a real failing test guides one documented improvement.

How to check

Compare the baseline commit, task, allowed tools, and success test for both runs. Then show the failing test before and after the refinement.

Needs another pass

The two approaches use different starting states or success criteria, or the refinement is based only on preference.

Partly demonstrated

The baseline is shared, but timing, results, rework, or the test-driven change is not recorded consistently.

Demonstrated

Both runs use the same baseline and criteria, their observed work and rework are recorded, and one failing test directly leads to a verified refinement.

Loading completion status…

Your assignment

Four files for each lab

decision.md

State the requirement, chosen pattern, rejected alternatives, and the reason for the tradeoff.

implementation/

Keep the smallest working example, configuration, diagram, or synthetic-trace analysis.

evidence.md

Record test cases, observed results, failure behavior, limitations, and evidence locations.

review.md

Explain what must be deterministic, what may remain model-directed, and where a human is required.

What to save

A configuration hierarchy map and loading table.

A valid SKILL.md whose name matches its directory.

Path-rule, read-only agent, hook, and settings examples.

An A/B execution record and test-driven refinement note.

What good work includes

Matching and nonmatching files demonstrate scoped-rule behavior.

A clean clone receives project guidance without personal configuration.

The skill is discoverable and its name is valid.

The hook still enforces its rule after prompt guidance is removed.

Plan and direct runs begin from identical baselines.

A failing test you add before the change drives one refinement cycle.

What useful evidence can look like

This is one small example, not a complete solution or a template you must copy. Use the notes to see why the evidence is useful.

Open annotated example from decision.md / loading table row

Rule: run Python checks for package files
Mechanism: .claude/rules/python.md
Paths: packages/**/*.py
Why here: applies by file path across several packages

Paths: Uses a recursive pattern so nested package files actually match.
Why here: Connects the mechanism to its scope instead of choosing it by habit.

Review your work

Use evidence from your work—not confidence alone. For each area, run the check and choose the strongest stage your work fully demonstrates.

If you're between two stages, use the earlier one and treat the next stage as your revision goal. There is no total score.

Scope and loading

Each instruction is stored at the narrowest scope that still reaches the intended files and collaborators.

How to check

Open matching and nonmatching files in a clean clone, then record which project, local, and path-scoped instructions load in each case.

Needs another pass

Rules are copied across levels, personal preferences are committed, or path rules load for the wrong files.

Partly demonstrated

The main scopes work, but at least one rule duplicates inherited guidance or lacks proof for a matching and nonmatching file.

Demonstrated

Root guidance is concise, lower scopes add only differences, personal settings remain local, and the loading table proves each rule appears only where intended.

Skill and agent boundaries

The reusable skill is discoverable and valid, while the read-only agent has one objective and no write capability.

How to check

Validate the SKILL.md name against its directory, invoke it directly and by relevance, then attempt a write through the read-only agent.

Needs another pass

Skill metadata is invalid or vague, or the read-only agent still receives write tools.

Partly demonstrated

The skill loads and the agent is mostly bounded, but discovery guidance, input handling, or the denied-write evidence is incomplete.

Demonstrated

The skill has valid matching metadata, clear use conditions and inputs, and the agent has a focused contract whose tool list makes an attempted write impossible.

Enforcement and settings

A harmless hook enforces one clear rule independently of prompt wording, and the settings example demonstrates precedence without exposing secrets.

How to check

Remove the matching prompt guidance, violate the rule, and show the hook still blocks or reports it. Then trace one setting through each precedence level.

Needs another pass

The required rule exists only in instructions, the hook performs unsafe side effects, or settings contain secrets.

Partly demonstrated

The hook works in the common case, but bypass behavior, failure messaging, or the settings-precedence result is unclear.

Demonstrated

The hook still enforces the documented rule after the prompt instruction is removed, fails safely with a clear message, and the settings trace shows the value used at every level.

Fair comparison and refinement

Plan and direct execution start from identical repository states, and a real failing test guides one documented improvement.

How to check

Compare the baseline commit, task, allowed tools, and success test for both runs. Then show the failing test before and after the refinement.

Needs another pass

The two approaches use different starting states or success criteria, or the refinement is based only on preference.

Partly demonstrated

The baseline is shared, but timing, results, rework, or the test-driven change is not recorded consistently.

Demonstrated

Both runs use the same baseline and criteria, their observed work and rework are recorded, and one failing test directly leads to a verified refinement.