Agentic Coding Dive

Topics: Agentic Loop, Context Window, CLAUDE.md, Rules, Skills, Subagents, Hooks, Permissions, MCP, Plugins

Intro

An agentic coding tool is a model (reasons) inside a harness (tools + context management). Every feature is an answer to one of three questions:

• What does the agent KNOW? (CLAUDE.md, rules, memory, skills)
• Where does the work HAPPEN? (main session, subagents, worktrees)
• What is GUARANTEED? (hooks, permissions, checkpoints, tests) Knowing which feature answers which question is the "2026 approach" interviewers look for.

The agentic loop is what the agent does. We give it a task and it repeats the following 3 steps until it decides it finished:

1. gather context
2. take action
3. verify results
4. repeat

The agentic look runs within the context window which is everything the agent can see. The context window is a resource with every iteration adds to it (file reads, command output) Eventually when it fills up and older stuff gets summarized or dropped, so the model can "forget" earlier instructions, or the model can get "incorrect" instructions, causing it to act incorrectly, so each of the individuals in Know, Happen, and Guarantee aim to provide a healthy context window so the agent can perform optimally.

Model + Harness + Steering = Coding Agent

Running An Agent With Steering

What actually happens when we run an agent? Say we write a prompt to "run the tests"

Legend:

• every Harness: line is built-in, the harness does it on its own with no setup
• [Steering]: where I change what happens (tagged with its section and how: add, set, choose, do)

1. Harness: builds the context: system prompt + CLAUDE.md + skill descriptions + "run the tests"
            [Steering] (Know, add) ./CLAUDE.md: says the test command is pytest -q
2. Model:   "call Bash: pytest -q"
3. Harness: PreToolUse hooks -> permission check -> runs pytest -> captures output
            [Steering] (Guarantees, add) .claude/settings.json (hooks): a PreToolUse hook that blocks risky commands
            [Steering] (Guarantees, set) .claude/settings.json (permissions): allow pytest without asking
4. Harness: adds the output to the context, sends it back
5. Model:   "use the Explore agent (built in) to find every caller of slugify"
            [Steering] (Happen, choose) my prompt: delegating research instead of doing it here
6. Model:   "call Read: src/text.py", then "call Edit: src/text.py"
7. Harness: loads matching rules -> snapshots the file (checkpoint) -> applies the edit -> PostToolUse hooks
            [Steering] (Know, add) .claude/rules/source.md: a rule with paths: src/** that loads when that file is read
            [Steering] (Guarantees, add) .claude/settings.json (hooks): a PostToolUse hook that formats the file
   ... repeat ...
8. Model:   "fixed, all tests pass"
            [Steering] (Output Verification, add) .claude/settings.json (hooks): a Stop hook that reruns pytest, blocks "done" if red
            [Steering] (Output Verification, add) .claude/agents/pr-reviewer.md: a subagent that reviews the diff
            [Steering] (Output Verification, do) my prompt: I ask for the test output as evidence
9. Harness: shows it to me

• Built-in alone: the loop runs, but the model guesses the test command, research fills my main context, nothing stops a risky command, and "done" is just the model's word
• With steering: every step above has something I added that informs, isolates, blocks, or checks it

Model

The large language model doing the reasoning: whichever model the session is using (ex: Opus, Sonnet, Haiku), check or switch it with /model

• The model can only read input (text, and images) and write text out
• It reasons over what it reads and decides what to write next, including requests for tools (ex: "run pytest -q"), which the harness carries out
• It can't open files, run commands, or remember anything between sessions on its own
• Each time it's asked to respond, it's handed the context window, and that's all it can see

Harness

The program running on the machine around the model (ex: Claude Code, other tools like Cursor have their own harness, the bullets below describe Claude Code)

• Gives the model tools: read and edit files, search, run shell commands, fetch web pages
• Runs the tools: the model only asks, the harness does the work and captures the output
• Runs the agentic loop: provide context window -> send request -> get reply -> run any tool it asked for -> add the result to the context window -> send request -> repeat until the model replies with just text
• Builds the context window every turn: system prompt + CLAUDE.md + my messages + tool output, and summarizes old stuff when it fills up (compaction)
• Enforces the guardrails: permission checks, hooks, checkpoints before edits
• Saves sessions, starts subagents, loads skills and rules

Steering

Everything I do to steer the agent: extensions I add (CLAUDE.md, rules, skills, subagents, hooks, MCP), harness settings (permissions), built-in features I choose to use (checkpoints, Explore, sessions), and my own practices (tests, evidence)

• What the harness loads into the agent's context window (Know)
• Which agent does the harness pick to do the work (Happen)
• What the harness enforces on the agent's actions (Guarantees)
• How the agent's output is checked before I accept "done" (Output Verification)

What I Steer

Everything I add, set, choose, or do

• Know
  • Extensions (files I add): CLAUDE.md, rules, skills, MCP
  • Other (I set, choose, or do): my prompts, @ files
• Happen
  • Extensions (files I add): custom subagents
  • Other (I set, choose, or do): choosing to use Explore, parallel sessions, headless
• Guarantees
  • Extensions (files I add): hooks
  • Other (I set, choose, or do): permission mode, allow/deny settings
• Output Verification
  • Extensions (files I add): Stop hook, reviewer subagent
  • Other (I set, choose, or do): test suite, failing test first, generator + checker, asking for evidence

What The Built-in Does To Make It Work

The harness's default machinery: same for everyone, no setup. On its own it steers nothing, but every piece of steering above only works because the built-in carries it out.

• Know

  • Built-in: loads CLAUDE.md, rules without paths, and skill descriptions into the context window at session start, loads path-scoped rules and skill bodies when they're needed, compacts the context when it fills up, keeps auto memory notes
  • Enables: my CLAUDE.md, rules, and skills only matter because the harness puts them in front of the model

• Happen

  • Built-in: ships Explore, Plan, and general-purpose agents, runs each subagent in its own context window, returns only its summary to my session
  • Enables: my choice to delegate, and my custom subagent files, both run on this machinery

• Guarantees

  • Built-in: checks every tool call against the permission mode and allow/deny rules, runs hooks at each lifecycle event, snapshots files before every edit
  • Enables: my settings and hooks only hold because the harness checks and runs them every time, and I can only rewind because it took the snapshot

• Output Verification

  • Built-in: runs the test command when asked and returns the output, runs the Stop hook when the agent tries to finish, runs the reviewer subagent, ships /code-review
  • Enables: my test suite, Stop hook gate, reviewer, and evidence requests all depend on the harness running them and putting the results back in context

• Every extension is steering, but not all steering is an extension (settings, choices, practices)

• Built-in features become steering the moment I choose to use them

  • ex: Explore exists either way (built-in), sending research to it is steering
  • ex: checkpoints always happen (built-in), rewinding to one when it goes off the rails is steering

1. Know

Features set up ahead of time to put knowledge into each individual agent's context window. (cost: context tokens, risk: wrong or forgotten)

1.1 CLAUDE.md

Lives in repo: ./CLAUDE.md (shared with the team via git) Lives in home: ~/.claude/CLAUDE.md (just me, every project)

• Onboarding note the agent reads at the start of every session
• Holds: commands (how to run tests), layout (where things live), rules (what to always do)

Init Prompt

Prompt: create CLAUDE.md on an empty repo

• /init works best once there's code to read, on an empty repo just ask for it
• keep it short: commands, layout, rules

Create a CLAUDE.md at the repo root for a Python project. Keep it under 30 lines with three sections:
- Commands: tests run with `pytest -q`
- Layout: source in src/, tests in tests/
- Rules: explain the plan before editing, keep diffs small, run the full test suite after
  every change, never edit a test just to make it pass, no refactors outside the task

Validation Prompt

CLAUDE.md is loaded into every session and the agent follows it literally, so before starting, validate that its instructions are correct and check for key missing ones

• works on a CLAUDE.md I just created, or one already in the repo (could be planted or stale)
• I make the final call on each change, the agent supplies the reasoning
• a wrong test command quietly breaks every "run the tests" step after it

Review CLAUDE.md instruction by instruction. For each one: is it correct for this repo, what
could go wrong if you follow it literally, and would you keep, change, or remove it? Then list
important instructions that are missing (testing, scope, error handling, commit messages).
Check that the test command actually runs. Don't edit anything yet.

1.2 Rules

Lives in repo: .claude/rules/*.md Lives in home: ~/.claude/rules/*.md

• Topic files that split up a growing CLAUDE.md (ex: testing.md, api.md)
• Can be scoped to file paths, so they only load when the agent touches matching files

Init Prompt

Prompt: create a path-scoped rule

• paths frontmatter = only loads when the agent touches matching files

Create .claude/rules/testing.md with frontmatter `paths: ["tests/**/*.py"]` and these rules:
one behavior per test, name tests after the behavior they check, never delete or loosen an
existing assertion to make a test pass.

Validation Prompt

Make sure the rule loads when it should, and doesn't conflict with CLAUDE.md

• two contradicting instructions = the agent may pick either one

Read a file under src/ and tell me which rules from .claude/rules/ are now loaded. Then check
every rule file against CLAUDE.md and list any instructions that conflict or repeat.

1.3 Auto Memory

Lives in home: ~/.claude/projects/<project>/memory/MEMORY.md (one per repo, managed by the tool)

• Notes the agent writes itself from my corrections and preferences
• CLAUDE.md = what I tell it, auto memory = what it learned

Usage

Nothing to set up, it's on by default and fills itself from my corrections

• view, edit, or toggle it

/memory

1.4 Skills

Lives in repo: .claude/skills/<name>/SKILL.md Lives in home: ~/.claude/skills/<name>/SKILL.md Accessible via slash commands: .claude/skills/review/SKILL.md -> /review

• Reusable procedures or reference material, loaded only when needed

Init Prompt

Prompt: create a skill (becomes /review-diff)

• the description is what the agent matches on to decide when to use it, make it specific

Create a skill at .claude/skills/review-diff/SKILL.md. Description: "Reviews uncommitted
changes for bugs, weakened tests, and scope creep. Use before committing." Steps: list each
changed file and why, flag any edited or deleted test, flag changes outside the task, check
edge cases (empty, zero, negative, missing ids), report blocking issues first.

Validation Prompt

Make sure it shows up, and that the agent would pick it for the right tasks

• vague or overlapping descriptions = the agent loads the wrong skill or misses it

List the skills you can see and their descriptions. For the request "review my changes before
I commit", which skill would you use and why? Then run /review-diff on the current changes.

1.5 MCP

Lives in repo root: .mcp.json (shared with the team) Lives in home: ~/.claude.json (just me, added with claude mcp add)

• Connects the agent to tools and data outside the repo (databases, Jira, docs)

Init Command

Command: add a server, run in my terminal, not as a prompt

• --scope project writes .mcp.json for the whole team
• --scope user stores it in ~/.claude.json, just for me

claude mcp add --transport http --scope project <name> <url>

Validation Command

Check that it connected

/mcp

2. Happen

Features that decide where the work runs, and which context window it fills (cost: coordination, risk: bloated context or collisions)

2.1 Main Session

Lives in: the terminal I'm typing in

• Where I steer and make decisions, keep it clean

Usage

Nothing to set up, keep it clean instead

• /clear: fresh start between unrelated tasks
• /compact focus on ...: summarize now, keeping what matters
• /context: see what's taking up space

/compact focus on the current feature, the decisions so far, and the remaining tasks

2.2 Subagents

Lives in repo: .claude/agents/*.md Lives in home: ~/.claude/agents/*.md Built-ins: Explore, Plan, general-purpose

• Separate context window (its own desk) for delegated work, only a summary comes back
• ex: research the repo, review a diff

Init Prompt

Prompt: create a read-only reviewer subagent

• read-only on purpose, it reports and the main session fixes

Create a subagent at .claude/agents/pr-reviewer.md. Description: "Strict read-only review of
the current diff. Use after every change, before committing." Tools: Read, Grep, Glob, Bash.
It runs git diff and the test suite, reports blocking issues first (correctness, edge cases,
weakened tests, scope creep), and never edits files.

Usage

Prompt: use a built-in one, no setup

• Explore and Plan don't load CLAUDE.md, so put any constraints in the prompt itself

Use the Explore agent to find every place this function is called. Return file:line references only.

Validation Prompt

Make sure it's read-only and actually runs as a separate agent

Use the pr-reviewer agent on the current diff. Confirm which tools it has, and that it
didn't edit any files.

2.3 Sessions

Accessible via: claude --continue (latest), claude --resume (pick one)

• Resume or fork a past conversation, or run several in parallel
• Parallel sessions each get their own git worktree (separate copy of the repo), so edits don't collide

Usage

Command: parallel work, one worktree (separate copy of the repo) per task

• claude --continue to pick up where I left off

git worktree add ../task-a -b task-a
cd ../task-a && claude

2.4 Headless

Accessible via: claude -p "..."

• Run the agent with no one watching, from scripts and CI

Usage

Command: one-off run with no one watching (scripts, CI)

• add --output-format json for output a script can parse

claude -p "Run the test suite and summarize any failures"

3. Guarantees

Features that run outside the agent's context window, so they can't be skipped or forgotten (cost: setup time, risk: none at runtime)

3.1 Hooks

Lives in repo: .claude/settings.json Lives in home: ~/.claude/settings.json

• Shell commands that ALWAYS run at lifecycle events (ex: after every edit)
• Can block an action (ex: never edit .env)

Init Prompt

Prompt: have the agent write the hooks

• the docs suggest exactly this, it knows the format

Add hooks to .claude/settings.json:
1. After every Edit or Write to a .py file, run `ruff format` on that file
2. Before any Edit or Write, block changes to .env files with the message "Blocked: .env is off limits"
Then show me the settings file and explain how each hook works.

Validation Prompt

Prove the hook fires, don't trust that it's configured

• /hooks lists what's configured

Try to add a comment to .env and show me what happens. Then edit a .py file with messy
formatting and show me the file after, so I can see the formatter ran.

3.2 Permission Modes

Accessible via: Shift+Tab to cycle

• How much the agent may do without asking (Manual, Accept edits, Plan, Auto)

Usage

Nothing to set up, pick one per task

• Shift+Tab cycles: Manual -> Accept edits -> Plan -> Auto
• or start a session in a mode

claude --permission-mode plan

3.3 Settings

Lives in repo: .claude/settings.json Lives in home: ~/.claude/settings.json

• Allow/deny lists for commands (ex: always allow pytest), hooks, defaults

Init Prompt

Prompt: pre-approve safe commands, deny dangerous ones

• or browse and edit interactively with /permissions

Update .claude/settings.json permissions: allow `pytest`, `git status`, and `git diff`
without asking, and deny reading or editing .env files. Show me the file after.

Validation Prompt

Make sure the rules do what I think they do

Run pytest, then try to read .env. Tell me which one asked for permission, which ran
without asking, and which was denied.

3.4 Checkpoints

Accessible via: Esc Esc or /rewind

• Snapshot before every edit, rewind file changes if it goes wrong

Usage

Nothing to set up, every edit is snapshotted automatically

• /rewind opens the menu: restore code, conversation, or both
• only covers the agent's file edits, not changes made by shell commands, so still use git

Undo that last change.

4. Output Verification

Checks on the agent's output, instead of trusting "done": they give the agent a pass/fail signal to iterate on, giving us a metric to accept the work off of. (cost: writing the checks, risk: a weak or edited test)

4.1 Test Suite

Lives in repo: the test folder, with the test command written in CLAUDE.md

• Run after every change, done = green

Init Prompt

Prompt: set up testing on an empty repo

Set up pytest: create tests/ with one passing smoke test, add pytest to the dev
dependencies, run `pytest -q`, and show me the output. Add the test command to CLAUDE.md.

Validation Prompt

Prove the tests can actually fail

• a test that can't fail proves nothing

Temporarily break the smoke test's assertion, run pytest and show me it fails, then
restore it and show me it passes again.

4.2 Failing Test First

Lives in repo: a new test next to the code

• Reproduce the bug, or define the feature, as a failing test before any fix

Usage

Prompt: define done before any code

Write failing tests in tests/test_slugify.py for slugify(text):
- "Hello World" -> "hello-world"
- "  Hello   World  " -> "hello-world" (trims and collapses spaces)
- "Hello, World!" -> "hello-world" (drops punctuation)
- "" -> "" (empty input)
Don't implement anything. Run them and show me they fail for the right reason.

4.3 Generator + Checker

Lives in repo: a script

• A script builds expected outputs and diffs them, instead of hand-writing fixtures

Usage

Prompt: build the factory, not 30 hand-written files

• review the generator and spot check a few outputs, the checker is only as good as the fixtures

Write scripts/gen_fixtures.py that runs the summary on every file in samples/ and writes the
expected output to fixtures/, plus scripts/check_fixtures.py that diffs current output against
fixtures/ and exits non-zero on any difference. Run the checker and show me the result.

4.4 Reviewer Subagent

Lives in repo: .claude/agents/pr-reviewer.md Accessible via: the bundled /code-review

• Fresh context reviews the diff, didn't write it so it won't defend it

Usage

Prompt: no setup, use the bundled reviewer, or my own (see Subagents)

• reviewers always find something, so tell it to flag only real gaps

Use the pr-reviewer agent to review the current diff against TASK.md. Flag only gaps that
affect correctness or the stated requirements, not style preferences.

4.5 Stop Hook Gate

Lives in repo: .claude/settings.json

• Runs the check and blocks the agent from finishing until it passes

Init Prompt

Prompt: the agent can't finish until tests pass

• must check stop_hook_active, or it can loop forever

Add a Stop hook to .claude/settings.json that runs `pytest -q`. If the tests fail, block
stopping and send the failure output back to you. If stop_hook_active is true in the hook
input, exit without blocking so it can't loop. Show me the hook and explain it.

Validation Prompt

Prove it blocks on red

Temporarily make one test fail, then tell me you're done. Show me what the Stop hook did,
then fix the test.

4.6 Evidence

Lives in: the conversation

• The agent shows the test output or the command it ran, not just "it works"

Usage

Prompt: proof, not "it works"

Show me the exact command you ran and its full output, not a summary.

Agents and Context Windows

Every running agent has its own context window (its own desk), so the first question is always: which agent is doing this work, and whose desk does it fill?

   PARALLEL SESSION A (worktree ../task-a)        PARALLEL SESSION B (worktree ../task-b)
   +-----------------------------------+          +-----------------------------------+
   | MAIN SESSION (desk 1)             |          | MAIN SESSION (desk 3)             |
   | I type here, I steer              |          | I type here too, separately       |
   |   |  "use Explore to find X"  ^   |          |                                   |
   |   v                summary   |   |          |                                   |
   | +-----------------------------+   |          |                                   |
   | | SUBAGENT (desk 2)           |   |          |                                   |
   | | reads 30 files, stays here  |   |          |                                   |
   | +-----------------------------+   |          |                                   |
   +-----------------------------------+          +-----------------------------------+
            \                                                /
             +------ share only through files + git --------+
                     (CLAUDE.md, TASK.md, the code, commits)

Main Session

Accessible via: claude in a terminal

• The conversation I type into and steer, my main desk
• Gets everything from Know: CLAUDE.md, rules, auto memory, skills
• Keep it for decisions and steering, push noisy work (searching, reading many files) elsewhere

Subagents

Accessible via: the main session starts them ("use the Explore agent to...", @"pr-reviewer (agent)")

• A helper the main session starts for one task, with its own fresh context window
• I don't talk to it directly: the main session gives it a prompt, it works, and only its summary comes back to my desk
• Its own instructions and tools, ex: a read-only reviewer that can't edit files
• Doesn't see my conversation, so everything it needs goes in the prompt
  • custom subagents load CLAUDE.md, the built-in Explore and Plan agents don't
• Lives inside one session, ends when its task is done
• Use for: research, reviewing a diff, anything that would clutter my main desk

Forks

Accessible via: the main session starts them, or /subtask <task>

• A subagent that starts with a copy of my conversation so far, instead of a blank desk
• Its own tool calls still stay off my desk, only the result comes back
• Use for: a side task that needs everything we've discussed

Parallel Sessions

Accessible via: a second claude in another terminal, ideally in its own git worktree

• A completely separate main session: its own desk, its own conversation, I steer it myself
• Knows nothing about my other session unless it's in files or git
• Two sessions editing the same folder can collide, so each gets its own worktree (separate copy of the repo on its own branch)
• Use for: independent tasks at the same time, or a writer/reviewer pair (one session writes, a fresh one reviews without being biased toward its own code)

git worktree add ../task-b -b task-b
cd ../task-b && claude

Side by Side

Interview Angle

• 60 minute round: one main session + subagents (Explore for research, a reviewer for diffs)
  • parallel sessions and worktrees: good to know, but too much setup for a one hour round
• "I'm sending this to a subagent so the 30 files it reads don't fill my main context"
• "The reviewer didn't write this code, so it won't defend it"

Prompting

How I talk to the agent (cost: a few extra seconds per prompt, risk: vague prompts = the agent guesses)

Claude can infer intent, but it can't read my mind: reference specific files, name constraints, point to example patterns, and say what "done" looks like. The more precise the prompt, the fewer corrections I'll need.

Context: @ Files, URLs, Pipes

Accessible via: @ in the prompt

• @path/to/file makes the agent read that file before answering, instead of me describing where code lives
• @"pr-reviewer (agent)" guarantees a specific subagent runs
• URLs: give it the docs or API reference page to read
• Pipes (headless): cat error.log | claude -p "explain this error"
• Or let it fetch what it needs: "read the tests first", "check git log for this file"

Look at @src/report.py and @tests/test_report.py. Add a --format option that supports json
and csv, following the pattern the existing --output option uses.

Saved Prompts: / Commands and Skills

Accessible via: / in the prompt

• Built-in commands control the session: /clear, /compact, /context, /rewind, /init, /code-review
• A skill is a saved prompt: if I keep typing the same prompt to start a task, save it as a skill
• Skills take arguments: /fix-issue 1234 passes 1234 in as $ARGUMENTS

/review-diff

Be Specific

Four upgrades, each turns a guess into an instruction

• Scope the task: which file, which scenario, any preferences
• Point to sources: tell it where the answer lives
• Reference existing patterns: name a file to copy the style from
• Describe the symptom: what happens, where to look, what "fixed" means

Before: add tests for foo.py
After:  write a test for foo.py covering the edge case where the user is logged out. avoid mocks.

Before: why does ExecutionFactory have such a weird api?
After:  look through ExecutionFactory's git history and summarize how its api came to be

Before: add a calendar widget
After:  look at how existing widgets are implemented on the home page. HotDogWidget.php is a
        good example. follow that pattern to build a calendar widget

Before: fix the login bug
After:  users report that login fails after session timeout. check the auth flow in src/auth/,
        especially token refresh. write a failing test that reproduces the issue, then fix it

Ticket Style Prompts

Write the prompt like a ticket for another engineer: no loose ends

• context + scope + named files + constraints + examples + done criteria + boundaries

Weak:
Add slugify.

Strong:
In src/text.py, add slugify(text) that lowercases, trims, collapses spaces to single hyphens,
and drops punctuation. Follow the style of the other helpers in that file. The tests in
tests/test_slugify.py define done; run the full suite when finished. Don't change other files.

Verify and Fix Root Causes

Give it a check it can run, and ask for the root cause, not a hidden symptom

• without a check, "looks done" is the only signal it has, and I become the test suite
• "don't suppress the error" stops the try/except and edited-test fake fixes

The build fails with this error: [paste error]. Fix it and verify the build succeeds.
Address the root cause, don't suppress the error.

Plan or Skip

Explore -> plan -> implement -> commit, but only when it's worth it

• plan when unsure of the approach, the change spans several files, or the code is unfamiliar
• if I could describe the diff in one sentence, skip the plan (avoids getting bogged down)
• Shift+Tab into plan mode, Ctrl+G opens the plan in my editor to change it

I want to add rate limiting to the API. What files need to change, and what are two ways
to do it with tradeoffs? Create a plan, don't write code yet.

Tweak and Challenge

When it misses, name what was wrong + the principle + the exact fix

• "that's wrong, fix it" teaches it nothing, the principle is what shows I understand it
• challenge choices that look off, ask why before accepting

Tweak:
It stripped the hyphens from "co-op" too. Only drop characters that aren't letters, digits,
spaces, or hyphens, then collapse repeated hyphens. Rerun the tests.

Challenge:
Why did you raise an exception here instead of returning None like the other helpers do?
What happens to callers that don't expect it to raise?

Course Correct

Correct early, and start over when the thread gets muddy

• Esc: stop it now, context is kept so I can redirect
• typing while it works: queues a correction for its next step
• /rewind or "undo that": roll back code, conversation, or both
• after two failed corrections on the same issue: /clear and write a better prompt with what I learned, a clean session beats a long one full of failed attempts
• /btw: ask a side question without adding it to the conversation history

/clear
In src/text.py, slugify must keep hyphens that are already in words ("co-op" -> "co-op") and
collapse repeated hyphens. Previous attempts stripped them. Tests in tests/test_slugify.py
define done.

Evidence

Ask for proof, not "it works"

• reviewing output is faster than rerunning the check myself

Show me the exact command you ran and its full output, not a summary.

Do and Don't

Abstraction

Context is the scarce resource and instructions are suggestions, so put facts in CLAUDE.md, file-specific facts in rules, procedures in skills, noisy or parallel work in subagents, and anything that MUST happen in hooks or tests.

How They Interact

                         +---------------------------------------------+
                         |        MAIN SESSION (context window)        |
   ALWAYS LOADED  -----> |  system prompt                              |
   (costs context        |  CLAUDE.md files (root -> cwd, concatenated)|
    every session)       |  rules without paths:                       |
                         |  auto memory (first 200 lines / 25KB)       |
                         |  skill DESCRIPTIONS + MCP tool NAMES        |
                         |                                             |
   LOADED ON DEMAND ---> |  path-scoped rules (when a matching file    |
   (cheap until used)    |    is read or edited)                       |
                         |  nested subdir CLAUDE.md                    |
                         |  skill BODY (when invoked)                  |
                         |  MCP tool schema (when used)                |
                         +---------------------------------------------+
                            |  delegate                    ^  summary only
                            v                              |
                         +---------------------------------------------+
   SEPARATE CONTEXT ---> |  SUBAGENTS: Explore, Plan, general-purpose, |
   (noise stays out)     |  your .claude/agents/*.md, forks            |
                         +---------------------------------------------+

   OUTSIDE THE MODEL (deterministic, the model can't talk its way past these)
   +------------------+  +---------------------+  +-------------------+  +-------------+
   | HOOKS            |  | PERMISSIONS         |  | CHECKPOINTS       |  | TESTS       |
   | run every time,  |  | mode + allow/deny   |  | undo file edits   |  | the oracle  |
   | exit 2 = block   |  | rules in settings   |  | (Esc Esc)         |  | for "done"  |
   +------------------+  +---------------------+  +-------------------+  +-------------+

The Three Questions (KNOW, HAPPEN, GUARANTEED)

A mental model for sorting every feature, not official Claude Code terminology. When you reach for a feature, first ask which question you're answering, then pick the cheapest feature that answers it.

              KNOW                      HAPPEN                     GUARANTEED
      (what's in its head)       (where the work runs)        (what can't be skipped)
   +----------------------+   +----------------------+   +----------------------+
   | CLAUDE.md            |   | Main session         |   | Tests                |
   | Rules                |   | Subagents            |   | Hooks                |
   | Auto memory          |   | Forks                |   | Permissions          |
   | Skills               |   | Worktrees + parallel |   | Checkpoints + git    |
   | Prompt + TASK.md     |   |   sessions           |   |                      |
   | MCP (outside data)   |   | Headless (CI)        |   |                      |
   +----------------------+   +----------------------+   +----------------------+
     cost: context tokens       cost: coordination         cost: setup time
     risk: ignored or stale     risk: lost context,        risk: none at runtime,
           instructions               merge conflicts            it just runs

1. What Does the Agent KNOW? (Context)

• Everything that shapes its decisions is text in its context window
  • if it isn't in context, the agent doesn't know it, if it IS, the agent may follow it literally (good or bad)
• Members, cheapest to most persistent:
  • Prompt: this turn only, gone after /clear or compaction
  • TASK.md / task file: survives /clear, but only if it's told to re-read it
  • CLAUDE.md: loaded every session, facts and rules
  • Rules: loaded every session, or only for matching paths
  • Skills: description always, body only when used
  • Auto memory: the agent's own learnings
  • MCP: lets it fetch knowledge from outside the repo
• Tradeoff: always-loaded = always paid for in tokens, and more text = lower adherence
• Failure mode: it knows something WRONG (planted or stale instruction) or forgets something (lost in compaction)
• Decision:
  • needed every time -> CLAUDE.md
  • needed for some files -> path-scoped rule
  • needed as a procedure -> skill
  • needed once -> prompt
• Interview line: "I'm putting this in CLAUDE.md so it applies every turn, not just this prompt"

# Prompt: audit what it knows
What instructions are you currently following from CLAUDE.md or other loaded
files? List any that conflict with each other or with the task.

2. Where Does the Work HAPPEN? (Execution)

• Every piece of work runs in some context, and that context fills up with whatever the work produced (file reads, logs, search results)
• Members:
  • Main session: where you steer, keep it clean for decisions
  • Subagents: fresh context, do the noisy work, return only a summary
    • Explore for search, a reviewer for diffs, general-purpose for multi-step
  • Forks: subagent that starts with a copy of the current conversation
  • Worktrees + parallel sessions: separate copies of the repo, separate agents, no file collisions
  • Headless (claude -p): runs with no one watching, in scripts or CI
• Tradeoff: more isolation = cleaner context, but more coordination and things to merge
• Failure mode: the main context bloats and forgets, or parallel agents edit the same files
• Decision:
  • noisy or exploratory -> subagent
  • needs fresh eyes -> subagent that didn't write the code
  • independent tasks, lots of time -> worktrees in parallel
  • judgment calls and steering -> main session
• Interview line: "I'm sending the search to a subagent so my main session only gets the answer"

# Prompt: move noisy work out of the main session
Use the Explore agent to find every place money is parsed or converted.
Return file:line references only.

3. What Is GUARANTEED? (Enforcement)

• Instructions are suggestions: the model usually follows them, but nothing forces it
• Guarantees live outside the model, so it can't decide to skip them
• Members:
  • Tests: the oracle for "done", green or red, no opinion involved
  • Hooks: run at every lifecycle event, PreToolUse with exit 2 BLOCKS the action
    • ex: always format after edits, never touch .env, always run tests before stop
  • Permissions: the mode (Manual, Accept edits, Plan, Auto) + allow/deny rules
  • Checkpoints + git: whatever happens to files can be undone
• Tradeoff: takes setup time, but costs nothing at runtime and never "forgets"
• Failure mode: treating a KNOW feature as a GUARANTEE
  • ex: "CLAUDE.md says run tests" does NOT mean tests ran, check the output yourself
• Decision: if breaking it would be bad (money, secrets, deleted data, shipping red tests), move it from KNOW to GUARANTEED
• Interview line: "CLAUDE.md asks it to run tests, but I'm verifying the output myself, in a real repo this would be a hook or a CI gate"

# Prompt: turn a rule into a guarantee
Add a PreToolUse hook in .claude/settings.json that blocks any Edit or Write
to files under tests/ unless I approve it, and explain how it works.

Interview Walkthrough

1. Agentic Loop

• The agent works in a loop: gather context -> take action -> verify results, repeat
  • ex: "fix the failing tests" = run tests, read errors, search, read files, edit, rerun tests
• Model = reasons, harness = the tools and context management around it
• You are part of the loop: interrupt any time
  • Esc stops it immediately, typing while it works queues a correction for its next step
• Interview angle: "My job is to make the verify phase real, tests and a reviewer, not just the agent's opinion of its own work"

2. Context Window

• Everything the model sees right now: conversation, file contents, command output, CLAUDE.md, loaded skills, system instructions
• It fills up, then auto-compacts (old tool output cleared, conversation summarized)
  • instructions from early in the chat can get lost -> persistent rules go in CLAUDE.md
• Commands:
  • /context: see what's using space
  • /compact focus on X: summarize now, keeping what I care about
  • /clear: fresh start between unrelated tasks
• Interview angle: "I clear between tasks and keep rules in CLAUDE.md, so a long session doesn't quietly forget my constraints"

# Prompt: check what's loaded (also confirms CLAUDE.md was picked up)
/context

# Prompt: compact before a new level, keeping what matters
/compact focus on the Account API, the money rules, and the remaining tasks

3. CLAUDE.md (Memory You Write)

• Onboarding note the agent reads at the start of every session: commands, layout, rules, gotchas
• Locations, all concatenated (not overriding), closest to your cwd read last:
  • ~/.claude/CLAUDE.md: you, every project
  • ./CLAUDE.md or ./.claude/CLAUDE.md: the project, shared via git
  • ./CLAUDE.local.md: you, this project, gitignored
  • subdirectory CLAUDE.md files load on demand when the agent works in that folder
• @path/to/file imports another file (still loads at launch, so no context savings)
• Keep it under ~200 lines, longer = more context and LOWER adherence
• It is context, not enforcement: the agent usually follows it, but can't be forced to
  • "must always happen" -> hook or test
• /init generates a starter, /memory to edit, AGENTS.md is read if there's no CLAUDE.md
• Interview angle: the planted-instructions trap lives here, fixing it = steering at the root

<!-- Interview-sized CLAUDE.md: commands, layout, rules -->
## Commands
- Tests: pytest -q

## Layout
- src/ledger.py: balances and transfers
- src/report.py: CSV -> per-product JSON summary

## Rules
- Explain your plan before editing; keep diffs small and focused
- Run the full test suite after every change; done = tests pass
- Never change a test just to make it pass; tell me instead
- Money: Decimal or integer cents with explicit rounding, never float

4. Rules (.claude/rules/)

• Split a growing CLAUDE.md into topic files: testing.md, api-design.md, money.md
• Without paths: frontmatter -> loads every session, same as CLAUDE.md
• With paths: -> loads only when the agent reads or edits a matching file
  • saves context, keeps instructions relevant
• ~/.claude/rules/ for personal rules across all projects
• Interview angle: rarely needed in 60 minutes, but naming it shows you know how instructions scale

<!-- File: .claude/rules/money.md -->
<!--   - only loads when the agent touches ledger or report code -->
---
paths:
  - "src/ledger/**/*.py"
  - "src/report/**/*.py"
---
# Money rules
- Parse amounts with Decimal from the original string, never float
- Round to cents with ROUND_HALF_UP
- Store and compare integer cents

5. Auto Memory (Memory the Agent Writes)

• The agent saves its own notes from your corrections and preferences, per repo
• Loaded every session (first 200 lines or 25KB)
• CLAUDE.md = your instructions, auto memory = its learnings
• Interview angle: mostly irrelevant in a fresh CodeSignal environment, know it exists

6. Skills (Reusable Procedures)

• A folder with SKILL.md: frontmatter + instructions, plus optional scripts and reference files
• Progressive disclosure: the DESCRIPTION is always loaded, the BODY only when invoked
  • long reference material costs almost nothing until needed
• Invoked by the agent automatically (description matches the task) or by you with /skill-name
• Custom slash commands were merged into skills (.claude/commands/x.md still works as /x)
• Useful frontmatter:
  • description: when to use it, this is what the agent matches on
  • disable-model-invocation: true: only you can run it (side effects like deploys)
  • context: fork: run it in a subagent with its own context
• !`git diff HEAD` in the body runs the command and injects its output first
• When to make one: you keep pasting the same checklist, or a CLAUDE.md section became a procedure
• Interview angle: check what exists with /help, use one if it fits, don't build from scratch in 60 minutes

<!-- File: .claude/skills/review-diff/SKILL.md -->
<!--   - /review-diff, or the agent loads it when I ask for a review -->
---
description: Reviews uncommitted changes for bugs, weakened tests, and scope creep. Use before committing.
---
## Current changes
!`git diff HEAD`

## Instructions
1. List each file changed and why
2. Flag any test that was edited, loosened, or deleted
3. Flag changes outside the task's scope
4. Check edge cases: empty, zero, negative, missing ids
5. Blocking issues first, then nits

7. Subagents (Separate Context Windows)

• A delegated worker with its own context window, system prompt, tools, and permissions
  • only its summary comes back, its file reads and logs never fill your context
• Built-ins:
  • Explore: fast, read-only codebase search
  • Plan: read-only research behind plan mode
  • general-purpose: multi-step tasks that need to read and act
• Custom: .claude/agents/<name>.md (project) or ~/.claude/agents/ (you), only name + description required, plus tools, model, permissionMode, isolation: worktree, etc.
• Invoked automatically from its description, by asking ("use the pr-reviewer agent"), or guaranteed with @"pr-reviewer (agent)"
• Forks: a subagent that starts with a copy of the conversation so far
• Subagents can spawn subagents (limited depth), so orchestrator -> workers is possible
• Interview angle: research and review are the two best delegations
  • "The reviewer didn't write this code, so it won't defend it"

<!-- File: .claude/agents/pr-reviewer.md -->
---
name: pr-reviewer
description: Strict read-only review of the current diff. Use after every change, before committing.
tools: Read, Grep, Glob, Bash
---
You review code you did not write. Run git diff and the test suite.
Report blocking issues first: correctness, edge cases, weakened tests,
scope creep, money handling. Never edit files.

8. Hooks (Guarantees, Not Suggestions)

• Shell commands the harness runs at lifecycle events, every time, no model choice involved
• Configured in .claude/settings.json (view with /hooks)
• Common events:
  • PreToolUse: before a tool runs, can BLOCK it (exit code 2, reason on stderr)
  • PostToolUse: after a tool succeeds, ex: format or lint the edited file
  • UserPromptSubmit, Stop, SubagentStop, SessionStart, PreCompact, Notification
• A PreToolUse deny blocks even in the most permissive mode
• CLAUDE.md "please don't edit .env" = a request, a PreToolUse hook = a wall
• Interview angle: "If this rule were critical I'd make it a hook, CLAUDE.md is context, hooks are enforcement" (one of the clearest 2026 signals)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

9. Permission Modes and Settings

• Shift+Tab cycles the modes:
  • Manual: asks before edits and shell commands
  • Accept edits: edits files without asking, still asks for other commands
  • Plan: explores and proposes a plan, no source edits
  • Auto: a classifier approves safe actions and blocks risky ones
• Allow/deny specific commands in .claude/settings.json (ex: allow pytest, git status)
• Interview angle: say which mode and why
  • plan for orientation, manual or accept edits for small reviewed steps, auto only for well-scoped work you'll review afterward

10. Checkpoints and Rewind

• Before every edit the harness snapshots the file
• Esc Esc to rewind to an earlier point, or ask it to undo
• Separate from git, covers file edits only (not databases, APIs, deploys)
• Interview angle: "It went off the rails, I'm rewinding to before that change and re-prompting narrower" beats arguing with it for five minutes

11. MCP (Model Context Protocol)

• Open standard for connecting external tools and data: databases, issue trackers, docs, browsers
• Configured per project in .mcp.json (or user/local scope)
• Tool definitions are deferred and loaded on demand, so many servers stay cheap
• Interview angle: likely not available in CodeSignal, but "in a real setup I'd connect the issue tracker so it reads the ticket directly" shows the bigger picture

12. Plugins

• One installable bundle of skills, subagents, hooks, MCP servers, and commands
• Plugin skills are namespaced: /my-plugin:review
• How teams share a working setup (ex: a "superpowers"-style workflow plugin)
• Interview angle: don't depend on installing one in the interview

13. Sessions, Worktrees, and Headless

• Sessions are saved: claude --continue (latest) or --resume (pick one), /branch to fork
• Parallel work: one git worktree per task, one session per worktree, no file collisions
• Headless: claude -p "..." runs non-interactively for scripts and CI
• Interview angle: know they exist, but not needed in a 60 minute round

14. Concepts You May Be Missing

• Verification is the bottleneck: the agent writes fast, so the tests, scripts, and reviewers that check it ARE the engineering (tests are the oracle for "done")
• Context engineering > prompt engineering: what's loaded (and what isn't) shapes output more than clever wording
• Determinism ladder: prompt < CLAUDE.md < skill < hook/test
  • the more it must happen, the further right it goes
• Non-determinism: same prompt, different result, so never trust one run, verify each time
• Orchestrator -> workers: a lead session plans and delegates, workers execute in isolation, the lead reviews and merges
• Build the factory: have the agent write generators, checkers, and scripts, not 30 outputs
• Blast radius: small scoped diffs, read-only agents for research, checkpoints and git to undo, permissions to fence off dangerous actions
• Hallucination: invented APIs, flags, file paths, check unfamiliar ones against code or docs
• Prompt injection: the agent follows instructions from ANY text it reads (repo files, web pages, issues), a planted CLAUDE.md is exactly this, read what it's being told
• Model and effort choice: /model to switch, bigger model for hard reasoning, faster model for simple or high-volume subagent work
• Cost and tokens: everything always-loaded is paid on every turn, keep it lean
• AGENTS.md: cross-tool instruction file, Claude Code reads it when there's no CLAUDE.md

15. If Asked: Follow-ups

• "What's the difference between CLAUDE.md and a skill?": CLAUDE.md is facts loaded every time, a skill is a procedure loaded only when needed
• "Why a subagent instead of just asking in the main chat?": its search output and file reads stay out of my context, and a reviewer that didn't write the code is more critical
• "How would you make sure tests always run?": a hook (or CI gate), because instructions are suggestions and hooks are guarantees
• "How do you keep a long session on track?": rules in CLAUDE.md, /clear between tasks, /compact with a focus, TASK.md for the task and plan

Sources

• How Claude Code works
• Memory: CLAUDE.md, rules, auto memory
• Skills
• Subagents
• Hooks guide
• MCP
• Plugins