Intro

Topics: Agentic AI , Prompting, Verification, Steering

60 minute technical round inside CodeSignal. An agentic AI assistant (e.g. Claude Code) runs in the IDE's terminal. You work through a series of tasks inside an existing application code base. Languages: Java, TypeScript/JavaScript, Python, Go. They grade how you complete tasks and problem solve WITH the AI:

• Think aloud, the reasoning matters as much as the solution
• Be open and adaptable to feedback, fix mistakes as they come up Only the AI tool enabled in CodeSignal is allowed.

The AI writes the code, you are graded on managing it:

• understand the requirements
• direct the work
• verify the output
• explain your decisions.

Initial Set Up (7 Minutes)

Nonnegotiables ::9::

9 pieces, about 7 minutes, in the order I do them. The agent works while I talk, review, and read.

1. REPO.md + AGENTTEAM.md (0:00, in parallel): one prompt maps the repo, runs the tests (the baseline), and records the tool. (Todo 1)
2. Clarify in my own words (0:00 to ~2:00, no prompt): restate the task, ask questions, jot notes while step 1 runs. (Todo 1)
3. TASK.md part 1, the story (~2:00): the agent turns my notes into a story (features, testing criteria, or the bug), I review it. (Todo 1)
4. TASK.md part 2, the full TASK.md (~3:00, in parallel): story approved, the agent builds the rest from it and REPO.md (Findings, Plan, Test Plan), while I read REPO.md and AGENTTEAM.md out loud. (Todo 2)
5. SUBTASKLOOP.md (~3:00, queued behind part 2): the loop file with its four gates. (Todo 4)
6. Instruction file (~3:15, queued behind step 5): the session rules in the file AGENTTEAM.md lists, with the conflict list. (Todo 3)
7. Review and approve (~5:00): the full TASK.md, SUBTASKLOOP.md, and the instruction file, by name.
8. Baseline commit (~6:00): the setup files, before any feature change. (Todo 4)
9. During the loop: the Awaiting Approval gate (summary, before and after, files changed, test result), then one commit per approved step with the before and after in the message. (Todo 9)

Negotiables ::7::

7 add-ons, only if there's time and it seems necessary. Each has an "add when" trigger:

1. CHANGELOG.md: add when there are several levels or you're changing rules mid-session.
2. Completed IDs: add only once CHANGELOG.md exists.
3. pr-reviewer agent: add for multi-file or tricky steps.
4. Full Awaiting Approval entry: add once the pr-reviewer exists, since it drafts the entry anyway.
5. subtask-loop skill: add if the tool supports skills and you'll run the loop many times.
6. Generator + checker: add when the tests need many derivable outputs.
7. Hooks: add when one rule is critical enough to enforce.

TEMP Interview Streamlined

Each setup step in order, with the simplest prompt that gets it done.

Each prompt starts with an organizational prefix, a short tag the agent repeats at the start of its reply, so with several prompts queued I can tell which reply answers which, and approve by file name.

• [REPO.md + AGENTTEAM.md] (step 1): the map and the tool, while I clarify
• no tag (step 2): I clarify with the interviewer and take notes, no prompt
• [TASK.md Part 1] (step 3): the story (features, testing criteria) from my notes
• [TASK.md Part 2] (step 4): the full TASK.md (Findings, Plan, Test Plan) from the story + REPO.md
• [SUBTASKLOOP.md] (step 5): the loop draft
• [CLAUDE.md] (step 6): the instruction file draft + conflict list (use the file AGENTTEAM.md lists)
• no tag (steps 7 to 9): my approval names the tags above, then the baseline commit and the loop

1. REPO.md + AGENTTEAM.md While I Clarify (0:00)

Normal mode (not "plan mode" since it can't write files). Send this, then talk to the interviewer while it runs.

Start your reply with [REPO.md + AGENTTEAM.md].
Don't change any existing files, only create REPO.md and AGENTTEAM.md. 
Explore the repo and run the full test suite. 
REPO.md (under 45 lines): what it does, main components, main flow with file:line, layout, 
how tests are organized, the test baseline, anything inconsistent, and a Docs section: the path
of every README or design doc (backend, frontend, system design, CONTRIBUTING, or "none"), one
line on what each covers, and where it disagrees with the code.
AGENTTEAM.md (under 20 lines): tool and model, whether you have plan mode, subagents, and skills,
who fills each role, and an Instructions section: the exact path of every instruction or rule
file you load (CLAUDE.md, AGENTS.md, .claude/rules/, .cursor/rules/, or "none"), whether each
exists yet, and its existing rules in one line each. Mark guesses "unverified".

2. Clarify In My Own Words (0:00 to ~2:00)

No prompt. While step 1 runs:

• restate the task in my own words, ask 2 or 3 clarifying questions
• jot notes: the goal, the interviewer's answers, examples (input -> expected output), what "done" means
• for a bug: what happens, what should happen, how to reproduce it

3. TASK.md Part 1, The Story (~2:00)

Paste my notes, the agent turns them into a story, and I review it before anything else is built on it.

Start your reply with [TASK.md Part 1].
Here are my notes and the interviewer's answers: [notes].
Create TASK.md with only two sections:
- Task: the task, word for word, with Current feature: 1
- Story: who wants it, what, and why (for a bug: what happens, what should happen, how to
  reproduce), the features one line each, testing criteria as input -> expected output
  (edge cases included), and open questions for anything I didn't answer.
Use only what I said, don't add requirements. Save it and wait for my approval.

Review it out loud:

• does it say what the interviewer said, in a form I'd sign off on?
• every example I wrote down is a testing criterion, edge cases included
• anything undecided is an open question, not a guess
• wrong? reply with the fix ("co-op keeps its hyphen"), it updates the story

4. TASK.md Part 2, The Full TASK.md (~3:00)

Once the story is right and REPO.md is done. Read REPO.md and AGENTTEAM.md out loud while it runs.

Start your reply with [TASK.md Part 2].
Story approved. Read REPO.md and build out TASK.md around the Story:
- Requirements and Edge Cases from the testing criteria, Decisions from my answers, Out of scope
- Findings: where the story fits in REPO.md: the files and functions to add, update, or fix,
  what calls them, and the tests that cover them, with file:line
- Plan: small subtasks, one reviewable diff each (if there's a real design choice, two options first)
- Test Plan: the tests for each subtask, from the testing criteria
- Next step, Awaiting Approval, Completed: empty for now
Don't change any code. Wait for my approval.

5. SUBTASKLOOP.md (~3:00)

Send while Part 2 is still running, it queues and runs right after it, while I keep reading.

• safe back to back: Part 2 only edits TASK.md, this only creates SUBTASKLOOP.md
• before the instruction file, since its rules point to SUBTASKLOOP.md
• if the tool doesn't queue messages, send it as soon as Part 2 finishes

Start your reply with [SUBTASKLOOP.md].
Create SUBTASKLOOP.md: Plan (skip if TASK.md already has an approved Plan; otherwise find where
it fits and plan the subtasks, gate), Tests (skip proposing if TASK.md already has an approved
Test Plan; write them as failing tests, gate), then for each Plan step: implement, diff summary
(gate), Awaiting Approval (gate). At each gate, stop and wait for me.
Don't change any other files. Show me before saving.

6. Instruction File (~3:15)

Send right after step 5, it queues behind it.

• the file comes from AGENTTEAM.md's Instructions section (CLAUDE.md, or the tool's equivalent)
• the conflict list is what I read out loud in step 7

Start your reply with [CLAUDE.md].
Create or update the instruction file listed in AGENTTEAM.md (CLAUDE.md if none) with these
rules, keep existing ones that don't conflict, and list any that do:
- Follow SUBTASKLOOP.md for every task and stop at each gate
- Check REPO.md before searching; update it only if an approved change alters the structure
- Run the full suite after every change; never change a test to make it pass
- Keep diffs small and in scope
- When a step is green, write an Awaiting Approval entry in TASK.md (summary, before and
  after, files changed, test result), then stop
- After I approve: commit with the before and after in the message, move the step to
  Completed with the commit hash
Don't change any other files. Show me before saving.

7. Review And Approve The Three Drafts (~5:00)

Three replies are waiting on me. Check each one out loud, then approve each by name.

1. [TASK.md Part 2]: the full TASK.md

   • every testing criterion from the story is in Requirements and the Test Plan
   • the Findings files match what I read in REPO.md
   • the Plan has nothing I didn't ask for, basic version first, edge cases after

2. [SUBTASKLOOP.md]: the loop draft

   • the four gates: after the plan, after the test list, after the diff summary, at Awaiting Approval

3. [CLAUDE.md]: the instruction file draft

   • read the conflict list, say why my rules win

Need a change? Swap that draft's line in the approval (ex: "[CLAUDE.md] keep the existing lint command, then save").

[TASK.md Part 2] approved, set Next step to "Write the failing tests for plan step 1".
[SUBTASKLOOP.md] approved, save SUBTASKLOOP.md.
[CLAUDE.md] approved, save the instruction file.

8. Baseline Commit (~6:00)

Commit everything with the message "Baseline: setup files before changes".

9. The Loop

Every task or level. The first task's Plan and Test Plan are approved in step 7, so it starts by writing the failing tests.

Follow SUBTASKLOOP.md for this task. The Plan and Test Plan are approved, start by writing the failing tests.

Next Plan step.

Approved.

Not approved: [reason].

Interview Todos ::11::

Setup, The Nonnegotiables (about 5 minutes)

Steps 1 to 4 set up the six Nonnegotiables, REPO.md and AGENTTEAM.md included. Add-ons come after, only if the task needs them.

1. Start Exploring, Then Clarify And Write TASK.md

First prompt has the agent map the repo into REPO.md, run the tests, and record the tool in AGENTTEAM.md, so it works while I talk. Then clarify with the interviewer: inputs, edge cases, what "done" means, and write the task down in story format.

Start Exploring Prompt

• normal mode, not plan mode: plan mode can't write files, "don't change any existing files" keeps it just as safe
• writing the files adds maybe 20 to 40 seconds over exploring alone, and it happens while I talk
• REPO.md is the repo-wide map and the baseline, TASK.md Findings is where this task fits
• AGENTTEAM.md, not AGENTS.md: AGENTS.md is a real instruction file other tools load as rules
• the tool answers decide full vs bare, which changes how step 3 works
• its self-report can be wrong (especially the model), check the important parts fast: /help, Shift+Tab once

- I'm in a timed scenario and will narrate, so keep answers short.
- Don't change any existing files. Only create REPO.md and AGENTTEAM.md.
- Explore the repo and run the full test suite, then create REPO.md (under 45 lines): what the
  repo does, the main components, the main flow from entry point to output with file:line, the
  layout, how tests are organized, the test baseline (command, pass/fail counts, anything
  already red), and anything that looks inconsistent. Add a Docs section: the path of every
  README or design doc (backend, frontend, system design, CONTRIBUTING, or "none"), one line on
  what each covers, and anywhere it disagrees with the code.
- Then create AGENTTEAM.md (under 20 lines): tool and model, full-featured or bare, whether you
  have plan mode, subagents, and skills, and how each role is filled (research, plan, reviewer,
  undo, running checks). Add an Instructions section: the exact path of every instruction or rule
  file you load at startup (CLAUDE.md, AGENTS.md, .claude/rules/, .cursor/rules/, or "none"),
  whether each exists yet, and the existing rules in one line each. Mark anything you're unsure
  of as "unverified".
- When done, summarize both in 5 lines.

Clarify

Clarifying: 
  - should slugify keep hyphens that are already in a word
  - what should an empty string return? 

Take notes:
  - The goal is a slugify(text) helper that lowercases, trims, and joins words with single hyphens
  - Done means the new tests and the full suite pass.

Then: paste these notes into the Notes To Story prompt below.

Story

What the agent should turn my notes into (TASK.md part 1), and what I review before part 2.

• user story: who wants it, what, and why (for a bug: what happens, what should happen, how to reproduce)
• features, then testing criteria as input -> output, edge cases included
• Q&A: my clarifying questions with the interviewer's answers, including anything still undecided

Story:
As a content editor, I want titles turned into URL slugs automatically,
so that every article gets a clean, readable link without me formatting it by hand.

Acceptance criteria:
- "Hello World" -> "hello-world"
- "  Hello   World  " -> "hello-world" (trims, collapses spaces)
- "Hello, World!" -> "hello-world" (drops punctuation)
- "" -> "" (empty input)

Q&A:
- Should hyphens already in a word be kept? Yes, "co-op" stays "co-op"
- What about accented letters like "Café"? Not decided yet
- Where should it live? src/text.py, next to the other text helpers

Notes To Story Prompt (TASK.md Part 1)

The agent turns my notes into the story above, in TASK.md, and waits for my approval.

• I review the story before anything is built on it: wrong requirements caught here cost nothing
• "use only what I said" stops it from inventing scope
• the rest of TASK.md comes in step 2, from the approved story + REPO.md

Start your reply with [TASK.md Part 1].
Here are my notes and the interviewer's answers: [notes].
Create TASK.md with only two sections:
- Task: the task, word for word, with Current feature: 1
- Story: who wants it, what, and why (for a bug: what happens, what should happen, how to
  reproduce), the features one line each, testing criteria as input -> expected output
  (edge cases included), and open questions for anything I didn't answer.
Use only what I said, don't add requirements. Save it and wait for my approval.

TASK.md Example

TASK.md is what we're doing right now (task, decisions, plan, progress). CLAUDE.md is how to work. Git commits are what changed.

TASK.md will be updated after every step, so the agent and I can pick back up after a /clear or a new level.

• Task word for word + current feature (which feature or level I'm on), so the requirements never drift
• Next step and Awaiting Approval at the top: opening TASK.md shows what's waiting on me, and which task it's trying to solve
• Awaiting Approval is my review queue, one subtask at a time: summary, before and after, every file changed, and the test result, nothing is committed until I approve it
  • with a pr-reviewer (add-on), the entry also gets Code, Tests, and Reviewer lines
• Before and After: the same input, the old output vs the new one, so I can see the change did what I asked (for a bug: the wrong output, then the right one)
• Requirements become the tests in step 6, Decisions stop the agent from re-guessing answers
• Plan is only what's left: an approved step moves to Completed instead of being ticked
• Test Plan holds the tests from step 6, ticked as they land, and points to the REPO.md baseline
• Completed is what's done, each line points to its commit, so "done" traces to a real diff
  • with CHANGELOG.md (add-on), it points to the entry ID instead
• flow per subtask: Plan -> green -> Awaiting Approval -> I approve -> commit -> Completed
• Instructions section only for a bare agent (no CLAUDE.md being loaded)

# TASK.md

## Task
<the interviewer's task, word for word>
Current feature: 1

## Story (part 1, approved before the rest was built)
As a content editor, I want titles turned into URL slugs automatically, so every article gets a clean link.
- Features: lowercase, trim, words joined by single hyphens, punctuation dropped, existing hyphens kept
- Testing criteria: "Hello World" -> "hello-world", "" -> "", "co-op" -> "co-op", "a  b" -> "a-b"
- Open questions: accented letters ("Café")

## Next step
- Review plan step 3 in Awaiting Approval

## Awaiting Approval (one subtask at a time, not committed until I approve)
- Plan 3: keep existing hyphens, collapse repeated spaces
  - Summary: slugify dropped "-" as punctuation, now kept; runs of spaces become one hyphen
  - Before: "co-op" -> "coop", "a  b" -> "a--b"
  - After: "co-op" -> "co-op", "a  b" -> "a-b"
  - Files changed (git diff --stat): src/text.py, tests/test_slugify.py, all explained above
  - Result: `pytest -q` 48 passed, 1 already red (baseline)

## Requirements (acceptance examples)
- "Hello World" -> "hello-world"
- "" -> ""

## Decisions (questions I asked + answers)
- Keep hyphens already in a word? Yes ("co-op" stays "co-op")
- Empty input? Returns ""

## Edge Cases
- Repeated spaces collapse to one hyphen

## Out of scope
- No changes to other helpers in src/text.py

## Plan (what's left, an approved step moves to Completed)
- [ ] 3. Keep existing hyphens, collapse repeated spaces (in Awaiting Approval)

## Test Plan
- Baseline: in REPO.md (42 passed, 1 already red before any change)
- [x] "Hello World" -> "hello-world" (unit, from Requirements)
- [x] "" -> "" (unit, from Requirements)
- [ ] "co-op" stays "co-op" (unit, from Decisions)
- [ ] repeated spaces collapse to one hyphen (unit, from Edge Cases)
- Gaps: no existing tests cover accented letters (open question in Decisions)

## Findings (file:line, from research)
- Existing helpers: src/text.py:12-40, all use split/join

## Completed (each points to its commit)
- Plan 1: failing tests for the acceptance cases -> commit a1b2c3d
- Plan 2: slugify(text) in src/text.py -> commit e4f5a6b
- When a feature's subtasks are all done: "Feature 1 done -> a1b2c3d..f9e8d7c"

## Instructions (bare agent only)
- Run the full suite after every change; done = tests pass
- Never change a test just to make it pass
- Commands: `pytest -q`

Keep TASK.md Current

It needs a standing instruction: a one-off request gets forgotten after a /clear, the instruction file is loaded every session, so the rule lives there.

• already part of step 3's Ensure CLAUDE.md prompt, use this alone to add it mid-session
• full: CLAUDE.md, or whichever instruction file the tool reads (Cursor: a rule in .cursor/rules/ with alwaysApply: true, or AGENTS.md)
• bare: put the same rule at the top of TASK.md itself, and start key prompts with "Read TASK.md first"
• it's still a suggestion, not a guarantee, so I check TASK.md at every approval

Add this to CLAUDE.md (or the tool's instruction file) under Instructions:
- TASK.md is the source of truth for the current task. Read it before starting any step.
- When a new requirement, edge case, or decision comes up, add it to TASK.md before coding,
  and add a matching test to the Test Plan.
- Submit For Approval: when a subtask's tests are green, write an Awaiting Approval entry:
  summary, before and after (the same input, old output vs new output), every file from
  git diff --stat (flag any the summary doesn't explain), and the test command and result.
  If there's a pr-reviewer agent, have it draft the entry. This applies to changes to CLAUDE.md
  and SUBTASKLOOP.md too. Then stop. Don't commit or start the next subtask until I approve.
- When I approve: commit with the before and after in the message, move the Plan step to
  Completed as "Plan N: ... -> commit <hash>", tick the Test Plan, clear Awaiting Approval,
  and update Next step.
- If I reject: keep the entry, add my reason under it, fix it, and update the entry.
- On a new feature (or level), bump Current feature, add to Requirements and the Test Plan,
  don't start a new file. When all of its subtasks are done, add "Feature N done -> <first>..<last>"
  to Completed.

REPO.md Example

# REPO.md (the agent's working map of this repo, written in step 1, not project docs)

## Purpose
CLI that turns a CSV of usage events into a per-product JSON summary.

## Architecture
- reader: parses the CSV into Event records, owns input validation
- report: groups events by product and builds the summary, owns all money math
- cli: wires reader -> report -> JSON output, owns arguments and exit codes
- External: none (no DB, no network), reads files from samples/

## Main flow
cli.py:main -> reader.load(path) (reader.py:18) -> report.summarize(events) (report.py:40) -> json.dump

## Layout
- src/reader.py, src/report.py, src/cli.py: the three components above
- src/text.py: small text helpers
- samples/: input CSVs, fixtures/: expected JSON outputs
- tests/: pytest, one file per module

## Docs
- README.md (root): how to run the CLI and the input CSV format
- docs/design.md: data flow and money rules, says "cents everywhere"  <- reader.py:31 uses float, disagrees
- no frontend or API docs

## Testing
- Framework: pytest, command in CLAUDE.md
- Organization: one test file per module, fixtures compared in tests/test_cli.py
- Baseline: 42 passed, 1 failed (test_report.py::test_rounding, already red before any change)
- Current: 46 passed, 1 failed (after Plan 2)
- Gaps: no tests for empty CSV or malformed rows

## Conventions
- Helpers return None on bad input, they don't raise
- Money is integer cents everywhere after reader.py

## Quirks and risks
- Money converted with float in reader.py:31 (looks wrong, flagged)
- report.py mixes formatting and logic

AGENTTEAM.md Example

# AGENTTEAM.md (written in step 1, update if anything changes)

Tool: Claude Code, model: Opus 5.5 (from the tool's UI, not the agent's self-report)
Mode: full-featured

## Instructions (where the rules live, step 3 edits these)
- CLAUDE.md (repo root): exists, loaded every session
  - "Short commit messages are fine (wip, update)"
  - "CI runs the suite on every push, no need to run it locally"  <- conflicts, step 3 replaces it
  - "cents = int(float(value) * 100)"  <- looks wrong, flagged
- .claude/rules/: none
- AGENTS.md: none (not read by this tool)

## Roles (how each is filled in this session)
- Instructions: CLAUDE.md, plus TASK.md for the current task
- Research: Explore subagent
- Plan: plan mode (Shift+Tab)
- Reviewer: .claude/agents/pr-reviewer.md (drafts each Awaiting Approval entry), or /code-review
- Undo: checkpoints (/rewind) + commit after each approved step
- Running checks: agent runs them and shows output

## Added this session (name | file | what it does | role)
- pr-reviewer agent | .claude/agents/pr-reviewer.md | reviews the diff, drafts Awaiting Approval entries | Reviewer
- subtask-loop skill | .claude/skills/subtask-loop/SKILL.md | runs SUBTASKLOOP.md | Plan, Running checks
- SUBTASKLOOP.md | repo root | steps 5 to 9 with the gates | Instructions

## Available but not using
- Skills: none of the existing ones fit this task
- Hooks: not worth the setup in 60 minutes

## Gotchas
- Tests need the DB container running

Bare agent version of the same file:

• Mode: bare, Instruction file: none loaded, so the commands go here instead of CLAUDE.md
• Roles: TASK.md for instructions, narrow prompts for research, "don't edit yet" for plan, a fresh conversation for review, git commits for undo, I run the checks if it can't

2. Build The Full TASK.md From The Story And REPO.md, Read While It Runs

TASK.md part 2. Once the story is approved and REPO.md is done, the agent builds the rest of TASK.md: Requirements, Decisions, Edge Cases, Out of scope, Findings, Plan, and Test Plan. While it works, I read REPO.md and AGENTTEAM.md and narrate: what the repo does, the main flow, the baseline, and whether the tool is full or bare.

• part 1 is only what the interviewer said, part 2 is how it maps onto this repo
• Findings is the zoom-in on this task, REPO.md is the whole map
• this is me understanding the repo, not just the agent: open the files on the main flow myself, then check the plan's files against what I just read
• the baseline matters most: if something is red later, it was already red before I touched it
• check the important tool claims fast: /help, Shift+Tab once, fix AGENTTEAM.md if it's wrong
• the first task's Plan and Test Plan are approved here, so the loop starts at writing the tests

Full TASK.md Prompt (TASK.md Part 2)

Start your reply with [TASK.md Part 2].
Story approved. Read REPO.md and build out TASK.md around the Story:
- Requirements and Edge Cases from the testing criteria, Decisions from my answers, Out of scope
- Findings: where the story fits in REPO.md: the files and functions to add, update, or fix,
  what calls them, and the tests that cover them, with file:line
- Plan: small subtasks, one reviewable diff each (if there's a real design choice, two options first)
- Test Plan: the tests for each subtask, from the testing criteria
- Next step, Awaiting Approval, Completed: empty for now
Don't change any code. Wait for my approval.

Queue Steps 4 And 3 Behind It

While the plan prompt is running, send step 4's Create SUBTASKLOOP.md prompt, then step 3's Ensure CLAUDE.md prompt. They queue and run right after the plan, while I'm still reading.

• SUBTASKLOOP.md first, since the CLAUDE.md rules point to it
• safe back to back: the plan only edits TASK.md, these only touch SUBTASKLOOP.md and CLAUDE.md
• if the tool doesn't queue messages, send them as soon as the plan finishes
• approve the full TASK.md, SUBTASKLOOP.md, and CLAUDE.md together, by name, once I have read all three

3. Set The Session Rules In CLAUDE.md, Every Time

Always run this, whether CLAUDE.md exists or not. I don't audit the old file line by line, I generate the rules this session needs and have the agent merge them in.

• full: CLAUDE.md loads every session automatically
• bare: nothing loads on its own, so CLAUDE.md is the one place the rules live, and a boot prompt makes the agent read it in every new conversation
• existing file: the agent keeps its commands and any rule that doesn't conflict, and lists the ones that do, so a planted bad rule (ex: "CI will catch it, don't run tests locally") still gets caught without me reading the whole file
• say each conflict out loud and why the session rule wins, that's the fix-it-at-the-root signal
• full: /init first is fine if there's no file, this prompt then reshapes it
• "Files" points to the other docs instead of copying them in, keeps CLAUDE.md short
• which file to edit comes from AGENTTEAM.md's Instructions section: CLAUDE.md, or the tool's equivalent (AGENTS.md, .cursor/rules/), and the existing rules listed there are what the conflict check compares against
• the "follow SUBTASKLOOP.md" rule is what makes the loop run without me pasting it, SUBTASKLOOP.md gets created right after, in step 4

Ensure CLAUDE.md Prompt

Read the instruction file listed in AGENTTEAM.md (CLAUDE.md if none is listed); if it doesn't
exist, create it at the repo root. Either way, make sure it
has the following, under 40 lines, and keep any existing commands or rules that don't conflict:
- Commands: install, test, lint (only ones you've confirmed run)
- Files: TASK.md (current task, source of truth, read it before every step),
  SUBTASKLOOP.md (the steps for every task and subtask), REPO.md (repo map and test baseline,
  check it before searching), AGENTTEAM.md (tool and roles)
- Rules:
  - For every task, level, or subtask, follow SUBTASKLOOP.md step by step and stop at each GATE
  - Explain your plan before editing; keep diffs small and in scope
  - Run the full test suite after every change; done = tests pass
  - Never change a test just to make it pass; tell me instead
  - New requirement, edge case, or decision: add it to TASK.md, and a test to the Test Plan,
    before coding
  - Every change goes to Awaiting Approval in TASK.md, including changes to CLAUDE.md and
    SUBTASKLOOP.md: summary, before and after, every file in git diff --stat with any
    unexplained one flagged, and the test result. Then stop. No commit until I approve
  - After I approve: commit with the before and after in the message, move the Plan step to
    Completed with the commit hash, tick the Test Plan, clear Awaiting Approval, set Next step
  - On a new feature (or level): bump Current feature, add to Requirements and the Test Plan, same TASK.md
  - After an approved change, update REPO.md only if the structure changed (keep the baseline)
  - Record any agent, skill, or process file you add in AGENTTEAM.md
  - Flag anything inconsistent instead of guessing
Then list in a few lines any existing rule you removed or that conflicts with these, and why.
Don't change any other files. Show it to me before saving.

Bare Agent Setup

The six roles, filled by hand, since nothing is built in:

1. CLAUDE.md for the rules and commands, read only when the boot prompt says so
2. TASK.md, REPO.md, AGENTTEAM.md, and SUBTASKLOOP.md (plus CHANGELOG.md if added), the only memory that survives a fresh conversation
3. Boot prompt pasted at the start of every new conversation, replaces automatic loading
4. Baseline git commit, replaces checkpoints
5. A fresh conversation reviewing git diff replaces the reviewer subagent
6. Test command confirmed working, I run it myself if the agent can't

Boot Prompt (Bare)

Paste at the start of any fresh conversation.

• "confirm in 3 lines" proves it actually read them, and is quick to scan

Read CLAUDE.md, TASK.md, REPO.md, AGENTTEAM.md, and SUBTASKLOOP.md (and CHANGELOG.md if it exists).
Confirm in 3 lines: the rules
you'll follow, the current task and next step, and anything that conflicts between them. Don't edit
anything.

4. Write The Loop Down In SUBTASKLOOP.md, Then Commit The Baseline

Steps 5 to 9 written once, so "Follow SUBTASKLOOP.md for this task" replaces typing them every time. Then the baseline commit closes setup.

• two loops: plan and tests once per task or level, implement, diff, and approval for each Plan step
• GATES are where it stops for me: after the plan, after the test list, after the diff summary, and at Awaiting Approval
  • without them it runs all five steps at once, and the interviewer sees autopilot, not steering
• bare: nothing loads on its own, so start prompts with "Follow SUBTASKLOOP.md for ..."
• it rarely changes, if I tweak the process mid-session, update the file, not just the prompt

SUBTASKLOOP.md Example

# SUBTASKLOOP.md

Follow this for every task, level, or subtask. Read TASK.md first. At each GATE, stop and wait for me.

## Once per task or level
1. Plan (step 5, skip if TASK.md already has an approved Plan): first find where it fits (the files, what calls them, the tests that cover
   them, with file:line) and save it to Findings in TASK.md. Then give two approaches with
   tradeoffs, and a step-by-step plan for the one you'd pick, each step one reviewable diff.
   GATE: wait for my approval, then save it to the Plan in TASK.md and set Next step.
2. Tests (step 6, skip proposing if TASK.md already has an approved Test Plan): propose the tests (cases from Requirements, edge cases this approach adds,
   unit or generator). GATE: wait for my approval, then save them as the Test Plan. Write them as
   failing tests, run them, and show they fail for the right reason. Don't implement anything.

## For each Plan step
3. Implement (step 7): only this Plan step, only the files it names, following the patterns in
   REPO.md. Run the full suite.
4. Diff (step 8): summarize the diff: every file in git diff --stat and why it changed, any test
   added, changed, or deleted, anything outside the step. GATE: wait for my questions.
5. Approval (step 9): when green, write the Awaiting Approval entry (the pr-reviewer drafts it if
   there is one). GATE: stop.
   - "Approved": commit with the before and after in the message, move the Plan step to Completed
     with the commit hash, tick the Test Plan, clear Awaiting Approval, set Next step.
   - "Not approved: [reason]": add the reason under the entry, fix it, rerun, update the entry.

Create SUBTASKLOOP.md Prompt

Create SUBTASKLOOP.md at the repo root with the steps I follow for every task and subtask:
- Once per task or level: Plan (skip if TASK.md already has an approved Plan; find where it fits: files, callers, and tests, saved to TASK.md
  Findings; two approaches, then small steps; GATE for my approval, save to the TASK.md Plan), Tests (propose, GATE, save as the Test Plan, write them failing, show the failure)
- For each Plan step: Implement (only that step, full suite), Diff (every file in git diff
  --stat and why, GATE for my questions), Approval (write the Awaiting Approval entry, GATE;
  on "Approved" commit with the before and after in the message, move the Plan step to Completed
  with the hash, tick the Test Plan, set Next step; on "Not approved" add the reason, fix, update
  the entry)
At each GATE, stop and wait for me. Don't change any other files. Show it to me before saving.

Using The Loop

• new task or level: plan gate first
• each Plan step after that: implement through approval
• at the approval gate: "Approved", or "Not approved: [reason]"

Follow SUBTASKLOOP.md for this task.

Follow SUBTASKLOOP.md for this task. The Plan is approved, start at Tests.

Next Plan step.

Not approved: no test for a leading hyphen.

Baseline Commit

git add -A && git commit -m "Baseline: setup files before changes"

Add-Ons, The Negotiables (only if the task needs them)

Each one is added after setup, when its trigger shows up. Each comes with the CLAUDE.md rule that keeps it current, and anything added goes through Awaiting Approval like any other change.

CHANGELOG.md

Add when: several levels, or I'm changing rules mid-session and want them tracked. One append-only log for every approved change, code and process, in its own file.

• own file: the agent edits TASK.md all the time, a separate append-only file can't get "tidied" by accident, and it outlasts tasks and levels
• IDs (C1, C2, ...): Completed in TASK.md points to an ID, the ID points to a commit
• [Code] is a change to the repo, [Process] is a change to CLAUDE.md, SUBTASKLOOP.md, an agent, a skill, or REPO.md's structure
• not logged: bookkeeping (Next step, ticks, test counts), git has it

# CHANGELOG.md (append only, newest last, one entry per approved change)

- C1 [Code] Plan 1: added failing tests for slugify | tests/test_slugify.py | 4 new, red as expected | commit a1b2c3d
  - Before: no tests for slugify
  - After: 4 tests, all red because slugify doesn't exist yet
  - REPO.md: no change
- C2 [Code] Plan 2: added slugify(text) | src/text.py | 4/4 new green, full suite 46 passed, 1 already red | commit e4f5a6b
  - Before: "Hello World" -> AttributeError (no slugify in src/text.py)
  - After: "Hello World" -> "hello-world", "" -> ""
  - REPO.md: added slugify to Layout (src/text.py), Current 46 passed
- C3 [Process] SUBTASKLOOP.md: diff step lists every file from git diff --stat | SUBTASKLOOP.md | no tests affected | commit c7d8e9f
  - Before: the diff summary listed only the files the agent chose to mention
  - After: every changed file is listed, unexplained ones are flagged
  - REPO.md: no change

Create CHANGELOG.md with only its header, and add this to CLAUDE.md:
- After I approve a change and you commit, append an entry to CHANGELOG.md: next ID, [Code] or
  [Process], plan step, what changed, files, test result, commit hash, and the before and after.
  Completed lines in TASK.md point to the ID instead of the hash.
- CHANGELOG.md is append only. Never edit or delete earlier entries. Log a revert as a new entry.
- Don't log bookkeeping (Next step, ticks, test counts).

pr-reviewer Agent

Add when: steps touch several files or tricky logic, about 2 minutes to create. Otherwise /code-review if bundled, or I read the diff myself.

• read-only: it reviews and drafts the Awaiting Approval entry, the main agent writes and commits
• it didn't write the code, so it won't defend it
• "flag only issues that affect correctness or the requirements" keeps it from burying me in nits

<!-- File: .claude/agents/pr-reviewer.md -->
---
name: pr-reviewer
description: Reviews the current diff and drafts its Awaiting Approval entry. Use after every green subtask, before committing.
tools: Read, Grep, Glob, Bash
---
You review code you did not write. Read TASK.md for the task, run git diff, git diff --stat,
and the full test suite. Flag only issues that affect correctness or the requirements: edge
cases, weakened or deleted tests, scope creep, and any changed file the summary can't explain.
Never edit files.
End with a draft Awaiting Approval entry:
- Plan N: <what the subtask does>
  - Summary: <what changed, one line>
  - Before: <an input and its old output>
  - After: <the same input and its new output>
  - Code: <file:line to read>
  - Tests: <file:line and test names>
  - Files changed (git diff --stat): <every file, and "all explained" or which aren't>
  - Result: <exact test command and pass/fail counts>
  - Reviewer: <issues, or "no correctness issues">

Create .claude/agents/pr-reviewer.md: a read-only reviewer (tools Read, Grep, Glob, Bash) that
reads TASK.md, runs git diff, git diff --stat, and the full suite, flags only issues that affect
correctness or the requirements plus any changed file it can't explain, never edits files, and
ends with a draft Awaiting Approval entry in the TASK.md format. Show it to me before saving.

subtask-loop Skill

Add when: the tool supports skills and I'll run the loop many times. Started with /subtask-loop.

• it only points at SUBTASKLOOP.md, so there's still one copy of the loop

Create a skill at .claude/skills/subtask-loop/SKILL.md, name subtask-loop, description "The steps
for every task or subtask: plan, tests, implement, diff, approval. Use for every task." Its
instructions: read and follow SUBTASKLOOP.md. Don't change any other files.

Every task or level, repeat

New level or changed requirement? Go back to clarify and restate (step 1) before step 5.

Steps 5 to 9 are what SUBTASKLOOP.md runs. The prompts below are the manual version, for a bare agent or when it skips a gate.

5. Plan Before Editing, Ask For Options On Design Choices

Use plan mode to prepare before starting on given tasks. Consider different approaches and their tradeoffs, then agree on one plan in small steps.

• the first task is planned in step 2, this step is for each later task or level

Before any code: give me two ways to implement slugify with the tradeoffs for likely
follow-ups, which files each touches, and a step-by-step plan for the one you'd pick.
Keep each step small enough to review in one diff. Wait for my approval.

6. Build The Testing Suite For The Plan

Design the tests for the chosen plan, approve them, then write them, ensure they fail as we have not started the feature implementation.

• cases come from step 1 (requirements) + edge cases the chosen approach adds
• a handful of cases -> unit tests, many derivable outputs -> build the factory (generator + checker)
• regression tests after any fix
• the approved list is saved as the Test Plan in TASK.md, so it survives a /clear

For the plan we chose, propose the test suite: the cases from the requirements, edge cases
this approach adds, and whether each is a unit test or should come from a generator.
Wait for my approval, then save it as the Test Plan section in TASK.md.

Write the approved tests from the Test Plan in TASK.md as failing tests in tests/test_slugify.py.
Don't implement slugify. Run them and show me they fail for the right reason.

Optional, only when the test list shows many derivable outputs:

For the fixture cases, write a generator that builds expected outputs from samples/ and a
checker that diffs current output against them and exits non-zero on any difference. Show me
the generator and a few outputs before I trust it.

7. Turn The Requirements Into Ticket Style Prompts, In Small Steps

Implement one step of the plan at a time, with a prompt written like a ticket for another engineer. The tests from step 6 are the done criteria.

• context, named files, constraints, examples, done criteria, what not to touch
• never one-shot the whole task, a small diff is one I can actually review

In src/text.py, add slugify(text): lowercase, trim, collapse whitespace to single hyphens,
drop punctuation. Follow the style of the existing helpers in that file. The tests in
tests/test_slugify.py define done; run the full suite when finished. Don't change other files.

8. Read Every Diff And Ask The Agent Why

Read the diff myself before accepting anything, and question the choices that look off. Owning the code means I can explain every line that goes in under my name.

• challenge weak choices, and name the principle when I correct one
• catch fake fixes: edited tests, broad try/except, special-cased inputs

Summarize the diff: each file changed and why, and call out any test you added, changed,
or deleted. Then: why did you use a regex here instead of the split/join pattern the other
helpers use? What happens with input that's already hyphenated, like "co-op"?

9. Close The Loop: Full Suite Green, My Approval, Then Commit

"Done" means proven, not the agent saying so: the full suite green, a summary in Awaiting Approval, my review, then a commit as my checkpoint.

• evidence: the exact command and its output, not "it works"
• one subtask in Awaiting Approval at a time, so its uncommitted diff is only that change
• before and after: the same input, old output vs new output, proves it fixed the right thing (for a bug, the Before should match the reported wrong output)
• files changed: every file in git diff --stat is listed, any the summary doesn't explain is flagged, so nothing slips in outside the step
• commit only after I approve, the Plan step moves to Completed with the hash, so any change can be reverted by itself
• pr-reviewer (add-on): it drafts the entry for multi-file or tricky steps, bare tool: one fresh-conversation review at the end

Submit For Approval (A Rule, Not A Prompt)

The Keep TASK.md Current rule in CLAUDE.md does this after every green subtask: the agent writes the Awaiting Approval entry and stops.

• only prompt it if the agent skipped it, or to check the rule is working

Submit this subtask for approval, following the rule in CLAUDE.md.

Approve Prompt

Approved. Commit with a message that says what changed and why, with the before and after in the
body. Then in TASK.md: move the Plan step to Completed with the commit hash, tick the Test Plan,
clear Awaiting Approval, and set Next step.

Reject Prompt

Not approved: [reason, e.g. no test for a leading hyphen]. Add that reason under the entry in
Awaiting Approval, fix it, rerun the full suite, and update the entry. Don't commit.

All hour

10. Think Out Loud And Adapt

Narrate decisions, not keystrokes, the whole hour. The interviewer grades the reasoning as much as the result, and silence hides it.

• never go silent while the agent works, use the time to solve it by hand out loud
• take a nudge, change course, and explain why

Say out loud, not a prompt:

"I'm keeping this prompt to one function so I can review the diff in one pass."
"While it runs: I'd split on whitespace and join with hyphens, let's see if it agrees."
"It says done, but I want to see the test output before I believe it."
"Good point, that changes the plan. I'll restate the requirement and re-plan step 2."

Bonus, Not Required

11. Use Existing Skills

Use a skill if the tool already has one that fits, like reviewing a diff or writing tests. Building one from scratch in 60 minutes reads as bogged down.

• check what exists in step 1's exploring prompt, use it here only if it saves time

List the skills available here. Is there one for reviewing a diff or writing tests that
fits this task? If so, use it on the current changes.

Section 1. Setup and Understand New Repo

Topics: Orientation, Check the Tool, Instructions File, Conventions Audit, Agent Roles, Checkpoints

Intro

You're dropped into an unfamiliar repo with a task file. Before any feature or bug work, understand what the code does, how it's tested, and what the agent is being told (CLAUDE.md, README, conventions). The tool may be full-featured (subagents, skills, hooks, plan mode) or bare (it can read, edit, and maybe run commands, nothing else). "Check the tool" decides which way each step goes. Either way, setup ends with the same six roles in place, so scenarios 2 and 3 run the same. Budget: about 10 minutes.

Abstraction

Understand before building: check the tool, map the repo, baseline the tests, treat the instructions file as a suspect, then set up the six roles with whatever the tool supports.

The six roles (same job either way, only the tool feature changes):

• Instructions the agent follows every time
  • full: CLAUDE.md, or whichever file the tool reads (AGENTS.md, .cursor/rules)
  • bare: TASK.md, and "Read TASK.md first" at the start of key prompts
• Research without cluttering my context
  • full: the built-in Explore agent
  • bare: narrow "file:line references only" prompts, findings saved to TASK.md, then a fresh conversation so the findings in TASK.md carry over and the noise doesn't
• Plan before editing
  • full: plan mode
  • bare: "Don't edit any files yet. Read and propose a plan." then I approve it
• Reviewer that didn't write the code
  • full: a pr-reviewer subagent, or the bundled /code-review
  • bare: a fresh conversation given git diff and a reviewer prompt, or my own read out loud
• Undo and enforcement
  • full: checkpoints (/rewind), hooks if worth the setup
  • bare: commit after every green step (git is my checkpoint), and I run the checks myself
    • say it: "Normally a hook would do this, here I'm the hook"
• Running checks (tests, git)
  • full: the agent runs them and shows the output
  • bare and it can't run commands: I run them in the terminal and paste the output back, and I make the commits myself

The solutions are steps, not alternatives: do 1, then 2, then 3 (about 10 to 15 minutes total). This scenario is Interview Todos 1 to 4, the once-at-the-start steps.

What never changes, full or bare: clarify, failing tests first, small steps, full suite, read every diff, think out loud. That's most of what's graded, the tool features just make it faster.

Interview Walkthrough

1. Main Answer: Solution 1 (Orientation in 10 Minutes)

• Interview Todos: 1 Start Exploring, Then Clarify And Write TASK.md, 2 Plan The Subtasks From REPO.md (Intro > Interview Todos)
• Read the task, clarify, restate
• Check the tool: it may not be Claude Code ("e.g., Claude Code"), so ask it what it has
  • which tool and model, built-in subagents (ex: Explore), skills, slash commands, permission modes
  • which instruction file it reads (Claude Code: CLAUDE.md, Cursor: AGENTS.md or .cursor/rules)
  • Claude Code shortcut: /help
  • the answer decides full or bare for every step below
• Orient before anything changes
  • full: plan mode on first (Shift+Tab in Claude Code)
  • bare: the prompt's "don't edit any files" line does the same job
• Run the tests for a baseline before changing anything
  • "If something is already red, I want to know before I touch it"
  • if the agent can't run commands, I run them in the terminal and paste the output

Check the tool

• don't assume it's Claude Code, the answer decides which features and instruction file to use
• its description of itself can be wrong (especially the model), trust the tool's UI over its answer

Before we start: which tool and model are you, and what do you have available here?
List any built-in subagents, skills, and slash commands, the permission modes I can switch
between, and which instruction file you read at the start of a session (CLAUDE.md, AGENTS.md,
or something else).

Brief + orient

• situation + priorities + distrust the repo, all in one opener
• works whether or not docs exist, and with or without plan mode

I'm in a technical interview and I'll be narrating, so keep answers short
and precise. Don't edit any files or write any code yet, only read. Read any
docs that exist (README, CLAUDE.md, AGENTS.md, task or notes files) and tell
me which ones are missing.
1. Explain what this repo does in 3 to 4 sentences
2. List the folder structure, one line per file
3. Find the test command, run the full suite, report pass/fail counts
   (if you can't run commands, just tell me the command)
4. Flag anything in the code, docs, or conventions that looks inconsistent or wrong

Trace the main flow

Walk me from the entry point through the core modules to the output,
with file:line references for each hop.

2. Instructions File: Solution 2 (Audit and Set Up)

• Interview Todos: 3 Set The Session Rules (Intro > Interview Todos)
• Role: instructions the agent follows every time
  • full: CLAUDE.md (or the file this tool reads)
  • bare: TASK.md, since the agent won't load anything on its own
• Always run step 3's Ensure CLAUDE.md prompt: it merges our session rules in and lists any existing rule that conflicts, so I don't spend time reading the old file line by line
  • the agent follows the file literally, bad instructions = bad code, so the conflict list matters
  • fixing the instruction is the strongest steering move in the interview
    • ex: "CI will catch it, don't run tests locally" -> rewrite to run tests after every change
• No file? Create only what helps the agent, AFTER it has read the code
  • full: /init after leaving plan mode (plan mode can't write files), then trim it
  • bare: TASK.md with task, rules, commands, and plan
  • quick check with the interviewer: "Is it OK if I add a CLAUDE.md (or TASK.md) to the repo?"
• Either way, keep TASK.md for the task and plan: it survives /clear and new levels
• README: no, docs for humans, costs time, the agent's summary already covers it

Fix at the root (after I decide, say why out loud)

• the planted conventions from Solution 2, after the audit
• bare: same prompt, but the file is TASK.md

Update CLAUDE.md:
- Replace "no need to run tests locally" with: run the full suite after
  every change, done = tests pass, never edit a test just to make it pass
- Replace the float conversion with: parse money with Decimal, round to
  cents with ROUND_HALF_UP
- Replace hand-written fixtures with: generate fixtures with a script, plus a checker
- Commit messages describe what changed and why
Only edit CLAUDE.md, then show me its diff.

Full: no instruction file -> create one from what we found (out of plan mode)

• /init scans the repo itself, then I cut it down to what I want enforced
• only what it can't figure out from the code: commands, dependencies, gotchas

/init
Now trim CLAUDE.md to under 50 lines with sections: Commands (install, test, lint),
Layout (a few lines), Dependencies (databases, APIs, env vars, config the code needs),
and Instructions:
- 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
- Flag anything in the repo or task that looks inconsistent
- No refactors outside the task's scope
Show me the draft before saving.

Create TASK.md (task + plan, and in bare mode the rules too)

• full: keep only the Task and Plan sections, the rules live in CLAUDE.md
• bare: keep all four, TASK.md is the instructions file

Create TASK.md with four sections:
- Task: [paste the interviewer's task exactly], plus open questions and answers so far
- Rules: explain the plan before editing; keep diffs small; never change a test just to
  make it pass, tell me instead; flag anything inconsistent; no refactors outside the task
- Commands: the test command and anything else needed to run the project
- Plan: a checklist we update as we finish each step
Show it to me before saving.

Bare: start every key prompt with it

Read TASK.md first, then [the next step].

3. Agent Roles: Solution 3 (Research, Reviewer, Checkpoints)

• Interview Todos: sets up the helpers for 3 Orient Before Changing Anything, 5 Plan Before Editing, 8 Read Every Diff And Ask Why, 9 Close The Loop, and checks for 11 Use Existing Skills (Intro > Interview Todos)
• Set up the remaining roles in 2 to 3 minutes, don't build infrastructure for 15 (that reads as bogged down)
• Main session = where I steer and code, either way
• Research
  • full: the built-in Explore agent, no setup
  • bare: narrow prompts, save findings to TASK.md, fresh conversation when context gets noisy
• Reviewer
  • full: a read-only pr-reviewer subagent, or /code-review if bundled
  • bare: the fresh-conversation review prompt below
• Undo and enforcement
  • full: checkpoints are automatic, still commit after each green step
  • bare: commit after every green step, and I run tests + read git diff every time

Clean baseline commit (both)

• known starting point, so every later change is a reviewable diff

git add -A && git commit -m "Baseline before changes"

Full: create the reviewer

• prompt: Interview Todos > Add-Ons > pr-reviewer Agent
• full agent files: Solution 3 below

Bare: fresh-conversation review (instead of a reviewer subagent)

• new conversation or terminal, so it has no attachment to the code it's reviewing
• point it at the diff, it reports and doesn't edit

You're reviewing code you didn't write. Read TASK.md for the task, then review the output
of `git diff`. Report blocking issues first: correctness, edge cases, any test that was
edited, loosened, or deleted, and changes outside the task. Don't edit any files.

4. If Asked: Follow-ups

• Interview Todos: 10 Think Out Loud And Adapt (Intro > Interview Todos)
• "Why subagents?": separate context windows, research noise doesn't pollute the coding session, and a reviewer that didn't write the code doesn't defend it
• "What if the tool has none of that?": same roles, filled by hand, TASK.md for instructions, fresh conversations for research and review, git commits for checkpoints
• "Why not just read the code yourself?": I do read the key files, the agent gets me the map faster, then I verify the map against the code
• "How do you know the tests actually ran?": I ran them myself, or I asked for the command and its full output, not a summary
• "What if the agent flags a convention as wrong?": don't wave it off, ask why, decide deliberately, say the reasoning out loud

When the agent objects to a convention

You flagged the conversion rule as risky. Explain exactly what goes wrong,
with a concrete input and output, and what you'd replace it with.

Solution 1: [Orientation] First 10 Minutes - Setup/Understanding

Always do this first. Understand the task, the tool, the repo, and the tests before the agent changes anything.

• Output: I know full or bare, and I can explain what the repo does, where the task fits, and what's already broken

Step 1: Clarify (out loud, before touching the keyboard)

• inputs, outputs, edge cases, what "done" means
• ex: "When an account doesn't exist, return false or raise?"

Step 2: Check the tool

• the guide says "e.g., Claude Code", so don't assume, ask the tool what's available
• the answer decides full or bare, which features I can use, and which instruction file to write
• Claude Code shortcut: /help
• prompt: "Check the tool" in walkthrough 1

Step 3: Brief the agent

• full: plan mode on first (Shift+Tab until "plan mode")
• bare: no plan mode, the "don't edit any files" line in the prompt does the job
• prompt: "Brief + orient" in walkthrough 1

Step 4: Map the repo

• one line per file, so I know where changes belong

Show the folder structure with one line per file describing what it does.

Step 5: Trace the main flow

Walk me from the entry point through the core modules to the output,
with file and line references.

Step 6: Baseline the tests

• known red before I start != red I caused
• bare and can't run commands: I run it in the terminal and paste the output

Find the test command and run the full suite. Report pass/fail counts.

Step 7: History and style

git log --oneline -10

Step 8: Summarize out loud

• "This repo does X, the task touches Y, the risks I see are Z, and the tool is full / bare"

Solution 2: [Instructions] Audit and Set Up the Instructions File - Setup/Steering

Do this right after orienting. Read what the agent is being told, fix bad instructions at the root before they turn into bad code, and make sure there's one file the agent follows every time.

• Output: an instructions file I trust (CLAUDE.md, or TASK.md if bare), with the reasoning for each change said out loud
• Below: an example of planted conventions (BEFORE) and the fixed file (AFTER), then the bare steps

<!-- BEFORE: planted / tired-team conventions, each one wrong -->
<!--   - agent follows these literally, so each one becomes a bug or a red flag -->

- Short commit messages are fine (wip, update). This repo squash-merges anyway.
- CI runs the suite on every push, no need to run it locally.
- Keep expected-output fixtures hand-written and checked in.
- Revenue is integer cents: cents = int(float(value) * 100). No need for Decimal.

<!-- AFTER: fixed at the root, say WHY for each change out loud -->

## Conventions
<!-- Commits: real messages, wip hides what changed and signals nobody is reading -->
- Commit messages describe what changed and why.

<!-- Testing: "CI will catch it" means the agent never verifies its own work -->
<!--   - interlocks with the money bug: bad conversion + no tests = silent bug -->
- Run the full test suite after every change. Done = tests pass.
- Never edit a test just to make it pass; report it instead.

<!-- Fixtures: derivable outputs should come from a generator + checker -->
<!--   - "build the factory" instead of hand-typing 30 JSON files -->
- Generate expected-output fixtures with a script; review the script and a sample of outputs.

<!-- Money: int(float("1.15") * 100) == 114, float is imprecise and int() truncates -->
- Money: parse with Decimal, convert to cents with ROUND_HALF_UP. Never float.

## Working rules
- Explain the plan before editing; keep diffs small and in scope.
- Flag anything inconsistent instead of guessing.

Bare: Step 1, create TASK.md

• the "Create TASK.md" prompt from walkthrough 2, all four sections

Bare: Step 2, audit any instruction file the tool doesn't load

• same questions as the CLAUDE.md Validation Prompt, then copy what's correct into TASK.md

Bare: Step 3, re-anchor after every fresh conversation

• first prompt in any new conversation: "Read TASK.md first"

Solution 3: [Roles] Research, Reviewer, Checkpoints - Setup/Multi Agent

Do this last, in 2 to 3 minutes. Set up the helpers and habits I'll use for every task in the hour.

• Output: a research path, a reviewer, and a baseline commit
• Below: the full-featured agent files and how I use them, then the bare manual loop

Full: agent files

• Explore is built in, so the custom researcher is optional
• create with the tool, or write the files directly

<!-- File: .claude/agents/researcher.md (optional, Explore does the same job) -->
---
name: researcher
description: Read-only codebase research. Use to find where something lives, how a pattern is used, or what calls a function. Reports findings with file and line references.
tools: Read, Grep, Glob
---
You are a read-only researcher. Never edit files.
Answer the question asked with file:line references.
Say when you are unsure instead of guessing.
Keep the report short: findings first, then evidence.

<!-- File: .claude/agents/pr-reviewer.md -->
---
name: pr-reviewer
description: Reviews the current diff like a strict PR reviewer. 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.
Check, in order:
1. Correctness and edge cases (empty, null, duplicates, boundaries)
2. Tests: were any weakened, deleted, or special-cased to pass?
3. Scope: changes outside the task
4. Consistency with existing patterns and CLAUDE.md
Report blocking issues first, then nits. Do not edit files.

Full: research during a task

• research runs in its own context, main session stays clean

Use the Explore agent: where is this function defined, and what calls it?
Return file:line references only.

Full: review before commit

• after the main session finishes a change, before commit

Use the pr-reviewer agent to review the current diff.

Bare: the manual loop for every task

• prompt -> I read git diff -> I run the full test suite -> I check no test was weakened -> fresh-conversation review (walkthrough 3) -> commit with a real message
• the commit is my checkpoint: git checkout -- <file> or git stash to undo

Say why out loud

• full: "I'm sending research to a subagent so it doesn't fill up my main context"
• full: "The reviewer didn't write this code, so it's more likely to catch problems"
• bare: "No reviewer agent here, so I'm using a fresh conversation that didn't write the code"
• bare: "Normally a hook would run the tests, here I'm the hook"

Section 2. Build New Feature

Topics: Requirements, Planning, Tests First, Prompting, Code Review

Intro

Implement new behavior on top of existing code. Often incremental (CodeSignal levels): Level 1 basic operations, Level 2 adds a query, Level 3 adds history or time, Level 4 adds undo/rollback. Each level builds on your earlier code, so design and tests from Level 1 pay off later. Uses the six roles from 1. Setup (instructions, research, plan, reviewer, undo, running checks), full or bare. Any prompt that says "run" or "commit": if the agent can't, I do it and paste the output.

Abstraction

Turn the requirement into acceptance examples, find where similar code already lives, agree on a plan, write failing tests, then implement in small ticket-style prompts with a review and full test run after each.

The solutions are layers of one process, not alternatives: Solution 1 is the order of steps, and Solutions 2, 3, and 4 zoom in on the moments where judgment shows (prompting, design, review). This scenario is Interview Todos 5 to 9, the every-task loop.

Interview Walkthrough

1. Main Answer: Solution 1 (Requirements -> Tests -> Small Steps)

• Interview Todos: 1 Start Exploring, Then Clarify And Write TASK.md, 5 Plan Before Editing, 6 Build The Testing Suite For The Plan (Intro > Interview Todos)
• Restate, clarify, write acceptance examples out loud (input -> expected output)
  • these become the tests, and prove I understood the ask
• Research where similar functionality lives, follow existing patterns
• Map the blast radius: which files change, what calls them
• Tests first, then implement one step at a time, full suite after each

Research + blast radius (plan role, no code)

• full: in plan mode, or send it to the Explore agent
• bare: this prompt as is (it says no code), then save the findings to TASK.md

I need to add withdraw(account, amount) that rejects overdrafts and
non-positive amounts. Before we plan: where does similar functionality
(deposit, transfer) live, what patterns should this follow, and which files
would change? File:line references, no code yet.

Plan

Propose a step-by-step plan for withdraw based on that. Keep each step
small enough to review in one diff. Wait for my approval.

Tests first (todo 6: propose, approve, then write)

• acceptance examples become the done criteria, plus edge cases the chosen plan adds

For the plan we chose, propose the test suite: the acceptance cases below, edge cases this
approach adds, and whether each is a unit test or should come from a generator.
Wait for my approval.

Write the approved tests as failing tests in tests/test_account.py, including these cases:
- withdraw(1, 50) on balance 100 -> True, balance 50
- withdraw(1, 150) on balance 100 -> False, balance unchanged
- withdraw(1, 0) and withdraw(1, -5) -> False
- withdraw(99, 10) on a missing account -> False
Don't implement anything. Run them and show me they fail for the right reason.

2. Prompting: Solution 2 (Ticket-Style Prompts)

• Interview Todos: 7 Ticket Style Prompts, 8 Read Every Diff And Ask Why (Intro > Interview Todos)
• Below: ticket-style, tweak, and challenge prompts applied to this feature

Implement one step (ticket style)

• context + scope + constraints + done criteria + boundaries

In account.py, add withdraw(amount) to Account. Reject non-positive amounts
and overdrafts by returning False without changing the balance. Use Decimal,
matching deposit. The new tests in tests/test_account.py define done; run
the full suite when finished. Don't change any other files.

Tweak when it misses

• name the problem + the principle + the exact fix

It converted with int(float(x) * 100). That truncates: 1.15 becomes 114
cents because 1.15 isn't exact in binary float. Parse with Decimal and
quantize with ROUND_HALF_UP instead, then rerun the full suite.

Challenge a choice

Why did you raise an exception here instead of returning False like
deposit does? What happens to callers that expect a bool?

3. Design Choice: Solution 3 (Ask for Two Approaches)

• Interview Todos: 5 Plan Before Editing (Intro > Interview Todos)
• Have the agent propose two options with tradeoffs, I pick and say why
• Shows judgment, and the next level usually rewards the extensible option
  • ex: transaction history -> a list of records beats patching balance fields

Options before code

Before coding, give me two ways to add transaction history, with tradeoffs
for likely follow-ups: filtering by time and undoing a transaction.
Keep each option to a few lines. Don't implement either yet.

Commit to one (after choosing out loud)

Go with option B, a list of Transaction records. Plan it in small steps
with tests first, and wait for my approval.

4. Review: Solution 4 (Diff Checklist + Reviewer)

• Interview Todos: 8 Read Every Diff And Ask Why, 9 Close The Loop (Intro > Interview Todos)
• Read every line: patterns, scope, edge cases, names, tests not weakened
• Reviewer role as a second opinion, then commit (the commit is also my checkpoint)
  • full: pr-reviewer subagent or /code-review, bare: fresh conversation + git diff

Diff summary before I read it

Summarize the current diff: every file changed and why. Call out anything
outside the task's scope and any test you added, changed, or deleted.

Second opinion + full suite

• bare: run the tests myself, and paste the review prompt from 1. Setup into a fresh conversation

Use the pr-reviewer agent on the current diff, then run the full test suite.

Commit

Commit with a message that says what changed and why.

5. If Asked: Follow-ups

• Interview Todos: 10 Think Out Loud And Adapt, new level -> back to 1 Start Exploring, Then Clarify And Write TASK.md (Intro > Interview Todos)
• "Why tests first?": done criteria the agent can't argue with, catches it changing behavior I didn't ask for
• "Why not one prompt for the whole feature?": small diffs are reviewable, big ones get rubber-stamped
• "Next level changes the requirement?": restate, update the plan, rerun the whole suite, the earlier tests protect the earlier levels

Next level / changed requirement

New requirement: [paste]. Restate it in your own words, list which existing
behavior and tests it affects, and update the plan. Don't code until I agree.

Solution 1: [Feature] Requirements -> Tests -> Small Steps - Feature/Planning

The full process, in order: requirements -> acceptance examples -> plan -> failing tests -> small steps.

• Output: the feature, its tests, a green suite, a reviewed diff

Step 1: Restate and clarify (out loud)

• "So withdraw takes an account id and an amount, returns true on success"
• Questions: missing account? zero amount? negative? partial withdraw?

Step 2: Acceptance examples (these become the tests)

• withdraw(1, 50) on balance 100 -> true, balance 50
• withdraw(1, 150) on balance 100 -> false, balance unchanged
• withdraw(1, 0) / withdraw(1, -5) -> false
• withdraw(99, 10) missing account -> false

Step 3: Find existing patterns (plan role, or the research role)

Where does similar functionality live (deposit, transfer)? What patterns,
error handling, and types should withdraw follow? File and line references.

Step 4: Blast radius

Which files would change for withdraw, and what calls them?

Step 5: Plan, agree, break into steps

• push back until I agree, but keep it brisk

Step 6: Tests first

Write failing tests in tests/test_account.py for these cases: [paste examples].
Don't implement anything yet. Run them and show me they fail.

Step 7: Implement one step (Solution 2 prompt), review diff, run full suite

Step 8: Reviewer role, commit, update the instructions file (CLAUDE.md or TASK.md) if something was learned

While it runs

• "Here's how I'd write it by hand: look up the account, validate, subtract..."

Solution 2: [Prompting] Ticket-Style Prompts and Tweaks - Feature/Prompting

Zooms in on Solution 1's implement step: how the prompt for each small step is written.

• Output: a weak vs strong prompt for this feature

Weak

• no files, no constraints, no done criteria, agent guesses everything

Add withdrawals.

Strong

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

In account.py, add withdraw(amount) to Account. Reject non-positive amounts
and overdrafts by returning False without changing the balance. Use Decimal,
matching deposit. The tests in tests/test_account.py define done; run the
full suite when finished. Don't change any other files.

Tweak and challenge prompts for this feature: walkthrough 2 above

Solution 3: [Design] Two Approaches With Tradeoffs - Feature/Design

Zooms in on Solution 1's plan step: get options before code when the design choice matters.

• Output: two approaches, my pick, and why (usually the one the next level builds on)

Ask for options instead of accepting the first design

• shows judgment, sets up the next incremental level

Before coding, give me two ways to add transaction history, with tradeoffs
for later features like filtering by time and undo.

Example answer to reason about out loud

• Option A: append a counter / last_transaction field on Account
  • simplest, but can't filter or undo, next level forces a rewrite
• Option B: list of Transaction records (type, amount, timestamp, ids)
  • slightly more code now, filter = scan records, undo = reverse a record
• -> "I'll take B, the levels in this format usually build on history"

Solution 4: [Review] Diff Checklist + Reviewer - Feature/Verification

Zooms in on Solution 1's last step: how I review before anything is committed.

• Output: a diff I've read, a full green suite, a second opinion, a real commit

Read every line of the diff myself (git diff), narrate as I go

1. Does it follow the existing patterns? (types, return style, naming)
2. In scope? (no surprise refactors in other files -> revert them)
3. Edge cases? (empty, zero, negative, missing id, same account)
4. Tests: added, not weakened, not deleted, not special-cased
5. Complexity: any nested loop where a dict lookup would do?

Full suite, not just the new tests (regressions in earlier levels)

Run the full test suite and report the results.

Second opinion

• full: the prompt below, bare: fresh-conversation review from 1. Setup

Use the pr-reviewer agent on the current diff.

Commit

• "Add Account.withdraw with overdraft and non-positive checks"

Section 3. Find and Remediate Bug

Topics: Reproduction, Tracing, Root Cause, Regression Tests, Verification

Intro

Something produces the wrong output, or a test is red. Find the root cause (not just the symptom), fix it minimally, and prove the fix with a test. The agent will happily make the symptom disappear (edit the test, add a try/except, special-case the input). Your job is to make sure the real bug is gone. Uses the six roles from 1. Setup (instructions, research, plan, reviewer, undo, running checks), full or bare. Any prompt that says "run" or "commit": if the agent can't, I do it and paste the output.

Abstraction

Reproduce with a failing test, say hypotheses out loud, trace the data path to where the value goes wrong, confirm the root cause explains every symptom, fix at the root, then prove it with the test and the full suite.

The solutions are layers of one process, not alternatives: Solution 1 is the order of steps, Solution 2 is a worked example of that process, and Solution 3 is what to watch for at the fix step. This scenario is Interview Todos 5 to 9 applied to a bug: the failing test reproduces it.

Interview Walkthrough

1. Main Answer: Solution 1 (Reproduce -> Trace -> Root Cause -> Fix -> Prove)

• Interview Todos: 1 Start Exploring, Then Clarify And Write TASK.md (pin the symptom), 6 Build The Testing Suite For The Plan (the reproducing test), 10 Think Out Loud And Adapt (hypotheses out loud) (Intro > Interview Todos)
• Pin the symptom: exact input, expected, actual, error message
• Failing test first, don't fix what you can't reproduce
• Hypotheses out loud BEFORE asking the agent, so they hear my reasoning
• Trace the data path with file:line references, read those spots myself
• Confirm the root cause explains every symptom, then fix minimally

Reproduce first, no fixing

Write a failing test: summing "1.15" and "0.58" should be 173 cents.
Run it and show me the actual output. Don't fix anything yet.

Trace the data path (after saying my hypotheses out loud)

Follow "1.15" from the CSV reader to the summary output. Show each value
it becomes and the file:line where it changes.

Confirm the root cause

Explain exactly why that line turns "1.15" into 114. Does that fully
explain the 2 cent difference in the test, or is there a second cause?

2. Worked Example: Solution 2 (Float Money Bug)

• Interview Todos: 7 Ticket Style Prompts (the fix), 3 Set The Session Rules (fix the instruction that caused it) (Intro > Interview Todos)
• int(float("1.15") * 100) -> 114
  • float can't represent 1.15 exactly (it's 1.149999...), int() truncates toward zero
• Fix: Decimal + quantize with ROUND_HALF_UP
• Look for siblings: every other place money is converted
• Fix the instruction: if the instructions file (CLAUDE.md or TASK.md) told it to convert this way, fix it too

Find siblings before fixing

• research role: full: send it to the Explore agent, bare: this prompt (or grep)

Where else in the repo is money converted the same way, or with float at all?

Minimal fix at the root

Fix to_cents to parse with Decimal and quantize to 0.01 with ROUND_HALF_UP.
Update the sibling call sites to use it. Don't touch the tests. Run the new
test, then the full suite.

Fix the instruction that caused it

CLAUDE.md told you to convert with int(float(value) * 100). Replace that rule
with the Decimal + ROUND_HALF_UP rule so this can't come back.

3. Watch for Cheats: Solution 3 (Agent Making the Symptom Disappear)

• Interview Todos: 8 Read Every Diff And Ask Why (catch fake fixes) (Intro > Interview Todos)
• Edited or loosened the test, broad try/except, special-cased the failing input
• Read test diffs extra carefully
• Reviewer role on the fix diff before committing (full: pr-reviewer, bare: fresh conversation)

When it fakes the fix

• name the cheat + the principle, not just "wrong"

Revert your change to the test. The test is correct; the conversion is the
bug. Floats can't represent 1.15 exactly and int() truncates. Fix the
conversion with Decimal and ROUND_HALF_UP, keep the test as is, and run
the full suite.

4. Regression Tests

• Interview Todos: 6 Build The Testing Suite For The Plan (regression tests), 9 Close The Loop (Intro > Interview Todos)
• Add tests for nearby edge cases, then full suite green
• A fix isn't proven until the test can fail without it
• The reported case, known float troublemakers, rounding boundaries, negatives

Regression tests

Add tests next to the new one for: "0.29", the rounding boundary "1.005"
(expect 101), a negative "-2.50", and surrounding whitespace " 3.10 ".
Run the full suite and report the results.

5. If Asked: Follow-ups

• Interview Todos: 10 Think Out Loud And Adapt (Intro > Interview Todos)
• "How do you know it's the root cause?": the explanation predicts every symptom, and the minimal fix at that spot turns the failing test green without other changes
• "Recent regression?": git log on the file, or git bisect with the failing test
• "Can't reproduce?": add logging at the boundaries, compare inputs from the report with my test inputs, ask the interviewer for the exact input

Recent regression

Show the recent commits that touched this file and what each changed.
Which one introduced the float conversion?

Solution 1: [Debug] Reproduce -> Trace -> Root Cause -> Fix -> Prove - Bug/Process

The full process, in order: reproduce -> hypothesize -> trace -> confirm root cause -> fix -> prove.

• Output: a failing test that now passes, the root cause named, regression tests added

Step 1: Pin the symptom

• input: amounts ["1.15", "0.58"], expected 173 cents, actual 171

Step 2: Reproduce with a failing test

• can't prove a fix for a bug I can't reproduce

Write a failing test: summing "1.15" and "0.58" should be 173 cents.
Run it and show me the failure. Don't fix anything yet.

Step 3: Hypotheses out loud (before the agent answers)

• "Off by a couple of cents smells like float precision or truncation in conversion, could also be rounding at the sum step, I'll check conversion first"

Step 4: Trace the data path

Follow "1.15" from the CSV reader to the summary output. Show each value
it becomes and the file:line where it changes.

Step 5: Narrow down

• check intermediate values (print, small test) at the suspicious line
• recent regression? git log -p on the file / git bisect

Step 6: Confirm root cause

Explain why this line produces 114 for "1.15". Does that explain the whole
2 cent difference in the test?

Step 7: Siblings

Where else is money converted the same way?

Step 8: Minimal fix at the root (Solution 2), never special-case "1.15"

Step 9: Prove it

• failing test now passes, full suite green

Run the new test and then the full suite.

Step 10: Regression tests, fix the instructions file if a convention caused it, commit

Solution 2: [Debug] Worked Example, Float Money Bug - Bug/Precision

Solution 1 applied to one real bug, with the code before and after.

• Output: the buggy line, why it's wrong, the fix, and the regression tests

from decimal import Decimal, ROUND_HALF_UP

# BEFORE (bug):
#   - float("1.15") is really 1.149999999999999911...
#   - * 100 -> 114.99999999999999
#   - int() truncates toward zero -> 114, one cent lost
#   - ex: 1.15 + 0.58 -> 114 + 57 = 171, expected 173
def to_cents_buggy(value: str) -> int:
    return int(float(value) * 100)

# AFTER (fix):
#   - Decimal parses the string exactly, no binary float in between
#   - quantize to 2 places with ROUND_HALF_UP (explicit rounding rule, not truncation)
#   - * 100 on an exact Decimal is exact, int() is now safe
# tc: O(1)
def to_cents(value: str) -> int:

    # Parse exactly from the string, never from a float
    amount = Decimal(value.strip())

    # Round to the cent with an explicit rule
    #   - ex: "1.155" -> 1.16, "1.15" -> 1.15
    amount = amount.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)

    # Exact conversion to integer cents
    return int(amount * 100)

# Regression tests:
#   - the reported case, a few known float troublemakers, rounding boundary, negatives
def test_to_cents():
    assert to_cents("1.15") == 115
    assert to_cents("0.58") == 58
    assert to_cents("1.15") + to_cents("0.58") == 173
    assert to_cents("0.29") == 29
    assert to_cents("1.005") == 101
    assert to_cents("-2.50") == -250

Solution 3: [Debug] Catching the Agent's Fake Fixes - Bug/Verification

Zooms in on Solution 1's fix step: the ways the agent makes the symptom disappear without fixing the bug.

• Output: recognize each fake fix, revert it, and re-prompt with the principle

Fake fix 1: test edited to match the wrong output

• diff shows assert ... == 173 changed to == 171
• "It changed the expectation, not the code, reverting that"

Fake fix 2: broad try/except

• wraps the conversion and returns 0 on error, hides the bug and creates new ones
• "Swallowing errors turns a loud bug into silent bad data"

Fake fix 3: special case

• if value == "1.15": return 115
• "That only fixes the input in the test, every other amount is still wrong"

Fake fix 4: round(float(x) * 100)

• passes this test, but still float based, and round() uses banker's rounding
• "Closer, but still float and the wrong rounding rule, Decimal is the real fix"

Re-prompt with the principle, not just "wrong"

Don't modify the tests. The root cause is converting through float, which
can't represent 1.15 exactly, and int() truncating. Fix the conversion with
Decimal and ROUND_HALF_UP, keep the test as is, and run the full suite.