Keep Claude on the job you gave it

Why Claude drifts

Drift is when Claude leaves the job you gave it. It is not random. It has four plain causes, and each one has a fix.

Louder words are not the fix. A small system is. The picture shows its parts.

The task card

Every prompt you send is a task card. It has the same parts every time. Copy this one and fill in the blanks.

GOAL: <one outcome, one sentence>
READ FIRST: <files, addresses, docs>
FENCE: Edit only <paths>. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `<command>`. Done means <exact result>.
BUDGET: Stop after <N> failed tries, or when you have made no progress for <M> minutes.
IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

Seven parts tell Claude what to do. The last line tells it how to answer. Each part stops one kind of trouble.

A filled-in card

This card asks for one matched function. The address and the file names are made up. Use your own.

GOAL: Make func_80045A10 match the original, byte for byte.
READ FIRST: `SCOPE.md`, `asm/func_80045A10.s`, `src/player.c`, `notes/findings.md`
FENCE: Edit only `src/player.c` and `include/player.h`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `./tools/check.sh func_80045A10`. Done means it prints "func_80045A10: MATCH 100%" and "full build: hash OK".
BUDGET: Stop after 5 failed tries, or when you have made no progress for 20 minutes.
IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

A good answer: the first word is DONE, PARTIAL or BLOCKED. The check output is pasted under it. Only the two fenced files changed.

The CHECK line names the function score and the full build. One project's rule file says the full build "is the only verdict".

The Scope Contract

A task card lasts one session. The Scope Contract lasts the whole project. It is one page, saved as SCOPE.md in the top folder.

It holds six things:

• The goal: a game that plays on a PC, or a full decomp.
• The game version and its hash. A hash is a short code that names one exact file.
• The technique you picked.
• The current milestone and its check.
• What is out of scope.
• What Claude must never edit.

# Scope Contract
Owner: <your name>. Only the owner changes this file.

Goal: <Goal A: the game plays on a PC. Or Goal B: a full decomp.>
Game: <title>, <region and revision>
Hash: <hash of your own dump>
Technique: <the one technique this project uses>

Milestone now: <one sentence>
Check: `<command>`. Done means <exact result>.

Out of scope: <work Claude must not start>, <more work Claude must not start>

Never edit: `SCOPE.md`, <original assembly folder>, <expected hashes>, <check script>,
<machine-made code folder>

Outside this page: stop, report BLOCKED, and ask the owner for a scope change.

Who may change it

Only you. Claude may ask for a change. You say yes or no, and you make the change yourself.

Make Claude read it

CLAUDE.md is the note file that Claude Code loads at the start of each session. Add these lines to it.

@SCOPE.md

## Rules for every session
- Follow `SCOPE.md`, loaded above. Only the owner edits it. If a task needs a change to it, stop and ask.
- The check command is `<command>`. Run it before every report.
- Start every report with one word: DONE, PARTIAL or BLOCKED. Then paste the check output.
- Edit only the paths named in the task card.
- Write side ideas and other problems in `notes/parking-lot.md`. Do not act on them.

The @ line pulls SCOPE.md into every session along with CLAUDE.md. That uses space each time, so keep the contract to one page. Anthropic's target for CLAUDE.md is under 200 lines.

Three honest outcomes

Every report starts with one word. There are only three words to pick from.

"Should work" is not on the list. No proof means not done.

Anthropic's guide says to ask for evidence: "the command it ran and its output". It adds that "All tests pass" alone "tells you very little".

Real projects agree. One author rebuilt the same game four times. He found the models "very eager to say that something is the same". Only a check that compared every pixel gave real feedback.

The report format

A report has five parts, in the order the card gives. Here are two examples.

DONE
Proof:
  $ ./tools/check.sh func_80045A10
  func_80045A10: MATCH 100%
  full build: hash OK
Files changed: src/player.c, include/player.h
What is left: nothing for this unit.
Parking lot: 1 new item (odd padding in src/camera.c).

BLOCKED
Proof:
  $ ./tools/check.sh func_80045A10
  func_80045A10: 94% (best of 5 tries)
  full build: hash OK
What blocked me: two loads at offset 0x48 come out in the wrong order.
What I tried: 1) swapped the two reads. 2) used a temp variable.
  3) changed the loop to a while loop.
What I need from you: pick one. A) More tries. B) Move it to the hard job.
  C) Skip it for now.
Files changed: none. I put src/player.c back as it was.
Parking lot: no new items.

When the proof is missing

Do not argue with a report that has no proof. Send this.

Your report has no proof. Run `<command>` now. Paste the command and all of its output. Then give me one word: DONE, PARTIAL or BLOCKED.

The parking lot

While it works, Claude will spot other things: a bug in another file, a faster way, a messy name. None of them is today's job.

They go into one file, notes/parking-lot.md. Claude writes them down and goes back to the goal. Claude never acts on them. You read the list and decide.

# Parking lot
Claude adds to this file. Claude never acts on it. The owner decides.

## <date> - <short title>
Seen while working on: <task>
What: <one or two sentences>
Where: <file and line, or address>
Why it may matter: <one sentence>

Pick a set time to read the list, such as the end of each day. Each item gets one of three ends. It becomes a task card. It goes under "Out of scope" in SCOPE.md. Or you delete it.

A check Claude cannot cheat

A check only helps if Claude cannot bend it. Real projects caught agents doing just that.

Words did not stop these. Tools did. Anthropic's rule: "If something has to happen every time, make it a hook, a deny rule, or a managed setting".

1. Block edits to protected files

A hook is a small script that Claude Code runs by itself at set moments. A PreToolUse hook runs before Claude uses a tool, and it can block the tool. A deny rule is a settings line that names an action Claude Code always refuses.

Protect five kinds of file: the Scope Contract, the original assembly, the expected hashes, the check script, and machine-made code. Add the .claude folder, or Claude could edit the guard itself.

Save this as .claude/settings.json. Change the folder names to match your project. The box scrolls, and Copy takes the whole file.

{
  "permissions": {
    "deny": [
      "Edit(./SCOPE.md)", "Edit(./.claude/**/*)", "Edit(./tools/check.sh)",
      "Edit(./asm/**/*)", "Edit(./expected/**/*)", "Edit(./generated/**/*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"${CLAUDE_PROJECT_DIR}/.claude/hooks/block-protected.sh\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash \"${CLAUDE_PROJECT_DIR}/tools/check.sh\" 1>&2 || exit 2"
          }
        ]
      }
    ]
  }
}

Then save this script as .claude/hooks/block-protected.sh. It needs jq, a small tool that picks the file name out of the hook's input. It is written for WSL and Linux paths.

#!/bin/bash
# Blocks edits to files Claude must never change.
root=$(cd "$(dirname "$0")/../.." && pwd)
f=$(jq -r '.tool_input.file_path')
rel=${f#"$root"/}
if echo "$rel" | grep -Eq '^(SCOPE\.md|\.claude/|asm/|expected/|generated/|tools/check\.sh)'; then
  echo "Blocked: $rel is protected. If the task needs it changed, stop and report BLOCKED." 1>&2
  exit 2
fi
exit 0

Claude Code tells the hook which file Claude wants to change. If the file is protected, the script ends with exit code 2. An exit code is the number a script gives back when it ends. Code 2 means "block". The message goes back to Claude and says what to do next.

A real N64 project uses hooks like this. Two are named block-sha1-edits.sh and block-asm-edits.sh.

2. Run the check when Claude tries to stop

The Stop part of that file runs your check each time Claude ends a reply. If the check fails, exit code 2 keeps Claude from stopping. The output goes back to Claude.

Give this hook a check that was green before the session began, such as "the full build still passes". Do not give it today's goal. Claude must stay free to stop and report BLOCKED.

The hook runs on every reply, so keep that check fast.

3. Keep the checker out of reach

Hooks are not airtight. The author of those N64 hooks saw Claude write a script to edit a protected file. The hook above watches the edit tools only, so a shell command can still change a file. Add a layer Claude cannot touch.

• The PC shooter team keeps a secret hash of its check script on its build server. A changed script fails.
• At home, run the check yourself, in your own terminal, before you accept DONE.

4. Break something on purpose

A check can lie. An old build can print OK when nothing was rebuilt. One project's rule is to test the check "by breaking a source file and checking it fails".

GOAL: Prove that the check can fail and can pass.
READ FIRST: `SCOPE.md`, <the check script>
FENCE: Edit only <one source file that passes today>. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Step 1: change one line in that file and run `<command>`. It must fail. Step 2: put the line back and run `<command>` again. It must pass. Done means both outputs are pasted and the file is back as it was.
BUDGET: Stop after 2 failed tries, or when you have made no progress for 15 minutes.
IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste both check outputs. 3) Files changed. 4) What is left. 5) New parking-lot items.

A good answer: DONE, with one failing output and one passing output. If step 1 passed, fix the check before any other work.

5. Never edit machine-made code

Some code is written by a tool, such as the C from a recompiler. If it is wrong, fix the tool and run it again. A Switch project puts it this way: "Generated C is never edited by hand: change the generator". A PS1 author gave Claude the same rule.

Small sessions and fresh starts

A short session has less to forget. Give each session one unit of work, then end it.

• One unit per session. A unit is one function to match, one crash, or one missing call.
• Type /clear between tasks. It starts a clean chat. The old one is saved, and /resume brings it back.
• Give paths, not pasted walls. Name the file and the address. One author learned this the hard way: "don't provide unasked-for context".
• Send big reads to a helper. A subagent is a helper Claude with its own memory. It reads the big file and sends back a short answer. It does not see your chat, so have Claude pass the fence along.

A fresh start works because the state is in files. Anthropic says its latest models are "extremely effective at discovering state from the local filesystem". The files are listed in Ledgers, not memory.

Plan first, then build

For any job longer than about an hour, get a plan before any code changes.

Plan mode is a setting where Claude reads and proposes. It makes no source edits until you approve the plan. Press Shift+Tab to switch modes, or type /plan and your request.

1. Ask for the plan. Use the card below.
2. Read it. Cut every step that is not in SCOPE.md.
3. Approve it. Have Claude save it as notes/plan.md. Then type /clear.
4. Build one step per session. Each step gets its own task card.
5. If the plan must change, Claude stops and asks. A changed plan needs a new yes from you.

GOAL: Write a plan for <the job>. Do not change any code.
READ FIRST: `SCOPE.md`, `PROGRESS.md`, <files for this job>
FENCE: Edit only `notes/plan.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Done means `notes/plan.md` has numbered steps. Each step names its files, its check command, and what done means. No step is outside `SCOPE.md`.
BUDGET: Stop when the plan is written. Do not start step 1.
IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the list of steps. 3) Files changed. 4) What is left. 5) New parking-lot items.

Do not send "continue"

A bare "continue" lets Claude pick what comes next. Anthropic's advice is to "say exactly what you want".

Ledgers, not memory

A chat ends. A file stays. Keep the state of the project in files, so any new session can pick it up.

Write down dead ends

A dead end is something you tried that did not work. If nobody writes it down, a later session will try it again.

A real Xbox 360 project has this in its rule file: "Negative results count too". It records them "so the next investigation does not repeat it".

# Findings

## <date> - <short title>
Fact: <one sentence>
How we know: <check output, trace or test>
How sure: <confirmed | probable | guess>

## <date> - DEAD END: <what was tried>
Tried: <one sentence>
Result: <what happened, with the check output>
Do not retry unless: <what would have to change>

The handoff rule

No session ends until the files are true. Test it with one question: could a new session start from the files alone?

GOAL: Update the ledgers so a new session can start from the files alone.
READ FIRST: `PROGRESS.md`, <the function ledger>, `notes/findings.md`, `notes/parking-lot.md`
FENCE: Edit only those four files. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `<command>`. Done means the counts in `PROGRESS.md` match the check output and the ledger. Every dead end from this session is in `notes/findings.md`.
BUDGET: Stop after 2 failed tries, or when you have made no progress for 10 minutes.
IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left: the next unit to start, in one line. 5) New parking-lot items.

Then commit, which saves the work in git. Real projects commit after every proven unit and undo every failed one.

A second pair of eyes

The session that did the work is a poor judge of it. Give the judging to a fresh one.

Open a new session with no memory of the work. It runs the check again and reads the diff, which is the list of changed lines. Anthropic says a fresh reviewer helps "because it hasn't seen your reasoning".

Reading alone is not enough. The PC shooter team first used a reviewer agent with no check to run. A month of code had wrong logic in it and was thrown away.

GOAL: Confirm or reject the claim in the report pasted below. Do not fix anything.
READ FIRST: `SCOPE.md`, the task card and the report pasted below, and the output of `git diff`.
FENCE: Edit nothing. Everything is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `<command>` yourself and compare it with the pasted proof. Then read the whole diff. Look for five things: 1) changes outside the fence, 2) edits to expected hashes, the check script or tests, 3) stubbed or empty functions, 4) disabled tests, 5) inline assembly or other tricks that force a match.
BUDGET: One pass. Stop after one full read of the diff.
IF BLOCKED: Stop. Do not work around it. Tell me what you could not check and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste your own check output. 3) Each problem that changes whether the work is correct, with file and line. Skip style. 4) If you found nothing wrong, say so. That is a fine answer. 5) New parking-lot items.

TASK CARD:
<paste the card>

REPORT TO CHECK:
<paste the report>

A good answer: its own check output, then real problems or the words "nothing wrong". No fixes.

For the model and effort, use the verify row of the table in Same job, same way.

When Claude cannot deliver

Some units will not get done today. You need to hear that early, in plain words.

Cap the tries

One test ran 60 real functions three times each. Almost half of the wins came on the first try. A function that still failed after try three matched only about one time in four.

So real projects set a cap: 5 tries in one, 12 in another. A cap does not say the unit is hopeless. In one N64 project, the slowest wins took 28 tries or more. The cap says: stop, report, and let the owner choose.

A cap that lives only in words can be ignored. That N64 author saw Claude skip a ten-try cap. His build script now tells Claude when to stop.

What a stop report must say

That project's rule file asks for four things: the best score, what was tried, what still differs, and whether it looks solvable. If a report is vague, send this.

Stop working. Do not try again.
Answer these four things, in this order:
1) What exactly can you not deliver? One sentence.
2) Proof: paste the last check output. Name the exact lines or instructions that still differ.
3) What did you try? One line for each try.
4) What are my choices? For each one, say what you need from me.
Do not call it impossible unless the proof shows it. Do not suggest any change to the check, the expected results, or files outside the fence.

"It is impossible" needs a second look

In one GameCube project, a helper worked for 16 minutes and called 97% "the honest ceiling". The author searched the code that already matched. He found 20 functions with the same "impossible" shape.

So a BLOCKED report must name the exact lines that differ. A vague reason does not count.

Sometimes the fault is upstream. If a function was split at the wrong place, an agent can only fail or cheat. Fix the split first.

Try again, or move it up?

Ask one question first: did Claude lack a file or a fact? If so, fix the card and try again.

If it had what it needed and still failed, do not just try again. Anthropic calls that "a signal to pick a larger model". On this site, the unit moves from the bulk job to the hard job.

In one test, a stronger model matched 5 functions that the smaller one always failed. It cost 3.5 to 4.6 times more.

Some units need a person. In one finished N64 project, about 5 matches in 100 needed an expert.

Same job, same way

Results stay steady when the job stays the same. Change one thing at a time, or you will not know what helped.

• Same card. Every prompt uses the task card.
• Same check. One command decides.
• Same model and effort for the same kind of job. The table gives both for each plan.
• Same tools. Write each tool's version in the repo. Do not update in the middle of a milestone.

A fixed setup works. One test ran the same 60 functions three times. 53 of them ended the same way every time.

When results change, check two things

Type /model to see the model. Type /effort status to see the effort level.

Claude Code can switch models by itself. Safety checks can move a session from Fable 5.2 or Opus 5.5 to an older model when content looks like security work. /model switches back. No official page says how often decomp work sets this off.

Effort also changes how Claude acts. In Anthropic's tests, a higher level checked more of its own work but also "made more choices on its own". Pick the level by job and leave it there.

Speed can change too. In that 60-function test, a slow day at the service made many runs time out. That is not drift.

Drift first aid

Claude has left the job. Do these in order.

1. Press Esc

   Do it the moment Claude leaves the job. Anthropic's guide says to watch the first minute.

2. Name the broken line

   Say which part of the card was broken. Then point back at the goal.

   Prompt for Claude: back to the cardCopy

   Stop. You left the task card. The FENCE line says: edit only <paths>. You changed <file>. Undo that change. Then go on with the GOAL only.

3. Park the side idea

   The idea may be good. It is still not today's job.

   Prompt for Claude: park itCopy

   Write that idea in `notes/parking-lot.md` in two lines. Do not act on it. Go back to the GOAL.

4. Take back stray edits

   Type /rewind, or press Esc twice on an empty prompt. You can restore the code, the chat, or both. It does not cover files that only a shell command changed. Use git for those.

5. After two failed fixes, start over

   You corrected Claude twice and it still drifts. Stop correcting. Type /clear and write a better card.

6. Make the fix stick

   If you had to correct the same thing twice, add one line to CLAUDE.md. If Claude still misses that line, turn it into a hook.

Sources

Anthropic pages:

• Claude Code best practices
• Hooks reference
• Permissions
• Permission modes and plan mode
• CLAUDE.md and memory
• Model, effort and model switching
• Subagents
• Context window and summaries
• Checkpoints and rewind
• Commands list
• Prompting best practices
• Prompting Claude Fable 5.2
• Model and effort level in Claude Code

Projects and write-ups:

• Chris Lewis: the long tail
• Chris Lewis: one-shot decompilation
• Chris Lewis: coding agents and N64 games
• Chris Lewis: an N64 game in 84 days
• Snowboard Kids 2: hook scripts
• Snowboard Kids 2: rule file
• Snowboard Kids 2: build script
• Maurice Heumann: a PC shooter decomp
• Macabeus: 60 functions tested
• Macabeus: a stronger model, same test
• Macabeus: a GBA decomp from zero
• Klonoa decomp: rule file
• Klonoa decomp: agent command
• Jack Price-Burns: teaching a model
• Matthew Stanley: a PS1 recompiler
• psxrecomp: rule file
• Piotr Migdal: Chromatron recompiled
• Melee decomp skill
• pinyon-shift: rule file
• totk-pc-recomp: rule file
• Game Developer: Claude Code and game remakes