D3 — Claude Code configuration and workflows (20 %)

Open Claude Code in a repository it has never seen and it starts from nothing: it must rediscover the build command, the test runner, where handlers live, what was tried last month. CLAUDE.md is the file that stops the rediscovery. It is Markdown, Claude Code reads it at the start of every session, and its contents are appended to your prompt.

Which file, though. The guide tests three levels, and they differ on exactly one axis: who receives them.

That third column is the entire task statement. A user-level file lives in a home directory. Committing the repository does not carry it; cloning the repository does not produce it. It reaches a second machine only if something copies it there.

Keeping the file modular

Two mechanisms, and the guide names both.

@import. A path preceded by @, anywhere in the file, pulls another file in. Relative paths resolve against the file containing the import, not the working directory, and imports may nest to a maximum depth of four hops.

# packages/api/CLAUDE.md

This package owns the public REST surface.

@../../standards/http-errors.md
@../../standards/database-migrations.md

This is the guide's own skill: a monorepo maintainer imports into each package's CLAUDE.md the standards that package actually needs, instead of loading every standard everywhere.

.claude/rules/. Instead of one growing file, one file per topic:

.claude/
├── CLAUDE.md            # what is true of the whole project
└── rules/
    ├── testing.md
    ├── api-conventions.md
    └── deployment.md

Rules without path scoping load at launch, with the same standing as .claude/CLAUDE.md. Adding a paths field to a rule makes it conditional. That is TS 3.3, below, and it is the only thing that actually shrinks what gets loaded.

Why the file stops working

CLAUDE.md is guidance, not enforced configuration. Every line competes with every other line for attention, so the longer the file grows the less reliably any single rule is followed. That is not a defect to work around; it is the property that dictates how you write.

Three habits follow from it, and they are worth knowing because they are also the shape of the wrong answers:

• Specific and checkable. "Put new API routes in src/api/handlers, one per file", not "follow best practices for API routes". If you cannot verify whether a rule was followed, neither can Claude.
• Name the replacement. "Use named exports, not default exports" closes the question; "don't use default exports" leaves it open.
• Emphasis is a budget. IMPORTANT and YOU MUST raise a rule's priority only relative to the quieter rules around them. If every line shouts, none does.

And the rule that does not belong in the file at all: anything that must never happen. "Never push to main" written in CLAUDE.md is a hope. A hook is code that runs at a fixed point and can refuse the action. The mechanism is D1's TS 1.5; where a given rule belongs is 3.2, below.

When you have typed the same multi-step instruction twice, it should stop being something you type. The guide keeps two mechanisms for that, and treats them as distinct.

Both come in two scopes, and the split is the same one as 3.1:

The frontmatter the guide tests

A skill is a directory holding a SKILL.md: YAML frontmatter, then the procedure.

---
name: dependency-audit
description: Audits third-party dependencies for unused, outdated and duplicated
  packages. Use when reviewing dependencies or before a release.
context: fork
allowed-tools: Read, Grep, Glob, Bash
argument-hint: "[package-manager] — npm, pnpm or cargo"
---

1. Read the lockfile and list every direct dependency.
2. Grep the source for each one and flag those with no import.
3. Report unused, outdated and duplicated packages in three tables.

The description is the field everything hinges on: Claude loads only names and descriptions at startup and matches your request against them semantically. A skill that never fires almost always has a description that does not overlap the way you actually phrase requests.

Three optional fields carry the task statement.

context: fork runs the skill in an isolated subagent context. The skill's own content becomes the prompt driving that subagent; it does not inherit your conversation, and what comes back to the main session is the result rather than the whole trace. That is the answer whenever a skill's output volume is the problem: codebase-wide analysis that prints every path it inspected, brainstorming that explores five options you did not keep.

allowed-tools restricts tool access during skill execution, for example limiting a skill to file-write operations so it cannot do anything destructive. That is the guide's wording and the one to answer with. Field nuance, for your own machine: the current documentation describes the field as pre-approving the listed tools for the invoking turn, so Claude may use them without asking, rather than removing the others; the field that actually removes a tool from the pool is disallowed-tools.

argument-hint is the hint shown at autocomplete time, so a developer who invokes the skill without arguments is told which parameter it expects.

Personal variants, and why the name matters

Skills with the same name are resolved by source, and a personal skill wins over a project skill. Clone a repository that ships .claude/skills/review/, keep your own ~/.claude/skills/review/, and /review runs yours, silently, on your machine only.

Which surface owns which rule

The guide's last skill on this task statement is choosing between a skill and CLAUDE.md. The full picture is worth holding, because the wrong answers on this topic are always another real mechanism:

The line between the first two is the guide's: always-loaded universal standards versus on-demand task-specific workflows. Detailed procedures placed in CLAUDE.md pay their token cost in every conversation, including the ones they have nothing to do with.

The line to the hook is different in kind. CLAUDE.md and skills are instructions Claude follows; a hook is code that runs. If skipping the rule is unacceptable, it does not belong to instruction-following at all.

The events, and PreToolUse as the enforcement primitive, are D1's TS 1.5 and are not re-taught here. What differs on this side of the line is how a hook says no. A Claude Code hook is a command declared in settings, so it answers with an exit code: 2 blocks, and what it wrote on standard error is fed back to Claude as the reason. An Agent SDK hook is a callback in your process and answers with a JSON permissionDecision. Same event, same intent, two conventions. And exit 1 is the trap on the Claude Code side: it looks like failure and blocks nothing.

# .claude/hooks/protect-main.sh — refuse a push to main, every time.
# A PreToolUse hook receives the tool name and its input as JSON on stdin.
if grep -qE 'git +push.*\bmain\b'; then
  echo "Pushing to main is not allowed; open a pull request instead." >&2
  exit 2          # 2 blocks and explains. 0 allows. 1 does neither.
fi

Subagents are the other neighbour. They are defined as Markdown files with YAML frontmatter under .claude/agents/, and /agents creates one interactively. Two facts belong to this task statement rather than to D1: a subagent does not inherit your skills, and a custom subagent loads only the skills its skills frontmatter field names.

---
name: accessibility-reviewer
description: Reviews frontend changes for accessibility regressions.
tools: Read, Grep, Glob
skills: accessibility-audit, contrast-check
---

Review the diff for WCAG violations. Report findings; never edit files.

The rest — why a subagent's isolated context is the point, and what must travel in the prompt because of it — is D1's TS 1.2 and 1.3.

Splitting CLAUDE.md into .claude/rules/ files makes the instructions maintainable, and loads exactly as many tokens as before: that is the problem 3.1 left open. Adding a paths field to a rule is what makes the loading conditional.

---
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
---

# Test conventions

- One `describe` per exported symbol, `it` sentences in the present tense.
- Build fixtures with the factories in `test/factories`; never inline literals.
- Never mock the database — use the test database from `test/db.ts`.

paths takes a list of glob patterns. The rule's body enters context only when Claude is working with a file that matches one of them; the rest of the time it costs nothing. A rule file with no paths field loads unconditionally, like the project CLAUDE.md.

The globs are ordinary:

Why not a CLAUDE.md in the subdirectory

Both mechanisms scope instructions. They scope them by different things, and the guide tests the difference.

A subdirectory CLAUDE.md is attached to a place. It is the right answer when the convention really is local: everything under terraform/ obeys these tagging rules, and nothing outside does.

A path-scoped rule is attached to a pattern. It is the right answer when the files sharing a convention do not share a directory. The canonical case is test files, colocated with the code they cover and therefore scattered through the whole tree. Writing a CLAUDE.md in each of forty directories to say the same three things about tests is unmaintainable, and a single root CLAUDE.md saying them costs every session that never opens a test.

Plan mode is a permission mode in which Claude reads, searches and runs read-only commands, asks its clarifying questions, and returns a plan, without editing anything. Direct execution is the ordinary mode: you describe the change and Claude makes it.

# Enter it for a whole session…
claude --permission-mode plan "Restructure the billing monolith into services"

# …or press Shift+Tab to cycle into it mid-session, /plan for a single prompt.

The choice is not about caution, it is about where the decisions are.

Plan mode earns its keep for one reason: iterating on a plan is far cheaper than letting a run happen and cleaning up after it. The place to course-correct is before a line is written. And when the plan comes back, read it rather than skim it: an unread plan is an approval you did not actually give.

The Explore subagent

A subagent runs in its own context window and returns a summary; the reads, the searches and the dead ends stay with it. That isolation is D1's subject (TS 1.2 and 1.3). What belongs here is what the guide asks of it in this task statement.

Explore is the built-in read-only subagent for discovery. Claude delegates to it to search or understand a codebase without changing it, and only its summary reaches the main conversation. That is the answer whenever a multi-phase task is running out of window during its discovery phase: the exploration cost is paid in a context you are going to throw away, and the main window stays available for planning and then implementing.

It is not tied to plan mode. You can ask for exploration through the subagent outside plan mode when all you want is a summary of how something works.

The combination the guide asks about

Plan mode and direct execution are not a permanent allegiance. The common shape is both, in order: plan the library migration, approve the plan, then execute it directly. The approved plan becomes the scope of the writing phase. The arbitration happened before any file changed.

The four techniques in this task statement come from the guide's own list. They answer four different failures, and the exam question is always which failure is this.

Concrete input/output examples

The failure: the same prose instruction produces a different result each run. The remedy the guide calls most effective is not more prose. It is two or three concrete pairs showing the transformation.

Normalise these customer records.

  "Dupont,  Marie-Claire"  →  { first: "Marie-Claire", last: "Dupont" }
  "jean pierre MARTIN"     →  { first: "Jean Pierre", last: "Martin" }
  "O'Brien, Sean (Jr.)"    →  { first: "Sean", last: "O'Brien", suffix: "Jr." }

Three pairs settle what a paragraph of definition left open: where the comma goes, what happens to casing, that a suffix gets its own field. An example shows the result instead of describing it, and the boundary cases you choose to include are the ones you were worried about.

Test-driven iteration

The failure: you cannot tell whether the code is right, so neither can Claude. Write the test suite first — expected behaviour, edge cases, performance requirements — then have the implementation written against it, then iterate by handing back the failures.

$ pytest tests/test_migration.py
FAILED test_null_effective_date - AssertionError: expected None, got '1970-01-01'
FAILED test_duplicate_account_ids - KeyError: 'legacy_id'

Two conditions make this work rather than merely feel rigorous. The tests must be a reliable source of truth: a suite that passes on broken code turns iteration into false confidence. And "done" has to be the gates having run and been observed, not a summary that says they passed.

The guide's sharpest version of this is for edge cases. Rather than describing the problem, supply the specific case: this input, this expected output, for instance the null value your migration script mishandles.

The interview pattern

The failure: the specification is incomplete and nobody knows it yet. Ask Claude to interview you before implementing.

Before implementing the cache for the pricing API, ask me whatever you need to
settle the design. Don't write code until I've answered.

  1. Invalidation by TTL, or on write events?
  2. Is stale data acceptable while the cache is unreachable?
  3. Per-tenant or global?
  4. What read volume should this hold at?

Its value is question 2. You had not thought about the cache being unreachable, and you would have found out in production. Reach for it in unfamiliar domains, where the implications are not obvious — cache invalidation strategies, failure modes — and where several approaches are valid and the right one depends on context you have not stated.

One message, or one at a time

The failure: several problems at once, and the fixes fight each other.

Error handling that is missing and input validation that is wrong are one message: a unified answer has to place them together. Renaming a variable and changing a return type are two conversations.

Claude Code is interactive by default. Invoked in a pipeline with no one to answer a prompt, it waits, and the runner eventually kills it at the step timeout. Everything in this task statement follows from that.

-p, and the shape of the output

-p, spelled out --print, runs Claude Code as a one-shot command: it processes the prompt, writes the result to standard output, and exits. It reads stdin and writes stdout, so it pipes like any other shell tool.

That gets the job to finish. Getting something the next step can act on takes two more flags: --output-format json makes the reply a JSON envelope, and --json-schema constrains the payload to a schema you supply. The conforming object lands in the envelope's structured_output field, at a fixed place, so nothing downstream has to parse prose.

- name: Review the diff
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    claude -p "Review $(git diff origin/main...HEAD) for security issues and bugs." \
      --output-format json \
      --json-schema '{
        "type": "object",
        "properties": {
          "issues": {"type": "array", "items": {
            "type": "object",
            "properties": {
              "severity": {"enum": ["critical", "major", "minor"]},
              "file": {"type": "string"},
              "line": {"type": "integer"},
              "message": {"type": "string"}
            },
            "required": ["severity", "file", "message"]
          }}
        }
      }' \
      | jq '.structured_output.issues' > findings.json

findings.json is now a list a later step can post as inline pull-request comments through the GitHub API. The API key comes from the repository secrets, never from the workflow file.

What the CI instance knows

A CI-invoked Claude Code has no session history and nobody to ask. The guide's answer to that is CLAUDE.md: the committed project file is the mechanism that carries testing standards, fixture conventions and review criteria to the instance running in the pipeline. Document which fixtures exist and what makes a test worth writing, and test generation stops producing low-value tests that re-cover ground the suite already holds, which is also why you put the existing test files in context when you ask for new ones.

Reviewing is a second instance's job

The session that wrote the code is the worst reviewer of it. It carries the reasoning that produced the code and questions its own decisions least, the same bias as an author proof-reading their own text. Review runs in an independent instance: a separate session, or a subagent with no memory of how the code was built. Fresh eyes catch what the original run talked itself past.

Two operational rules complete the picture, and both are guide skills:

• Re-running a review after new commits, pass the previous findings in and instruct Claude to report only what is new or still unaddressed. Otherwise every push re-raises the same issues, the pull request fills with duplicate comments, and developers stop reading them.
• Pass the existing test files when generating tests, so the new ones do not duplicate scenarios already covered.