Why it forgot what you told it

At some point in the last two modules, you told Claude Code how you wanted it to work. Perhaps you said “keep your answers to three lines”, “show me the change before you write it”, or “leave that file alone”. It listened at first. Then, twenty minutes into the same conversation, the instruction seemed to disappear.

The tool is not broken, and your wording may be fine. The real cause sits one layer below the conversation, which is why the fix most people try first does not help.

Everything in a session joins one growing pile of text: your questions, Claude’s answers, every file it opened, every command’s output, and the instruction you gave earlier. Before each reply, the model reads that entire pile and weighs the pieces together. Your sentence is one voice among many. It competes with newer material about the work directly in front of the model.

That pile is the context window, the fixed amount of text the model can hold at once. Your instruction does not stand outside the window and issue orders. It lives inside the window with everything else the model reads.

As the session grows, so does the competition around your sentence. This is the hidden part most people miss, and somebody measured it.

Someone measured which part matters

A controlled study tested the advice people tend to repeat. Damon McMillan’s “Instruction Adherence in Coding Agent Configuration Files: A Factorial Study of Four File-Structure Variables” (submitted 2026-05-11, arxiv.org/abs/2605.10039) covered 1,650 Claude Code sessions and 16,050 function-level observations. The study used two TypeScript codebases, three current top-end models and five tasks. It changed four features of the instruction file: its size, the instruction’s position inside it, the way files were split, and whether a neighbouring file contradicted the instruction.

The abstract reports: “None of the four structural variables or three two-way interactions produces a detectable contrast after multiple-testing correction.” For size and contradiction, the result was evidence of no effect rather than a failure to find one.

One factor did move the number: position within the session. Each additional function the agent generated was associated with roughly 5.6% lower odds of compliance per step.

That finding clashes with common advice, including Anthropic’s own best-practices page, which says “Bloated CLAUDE.md files cause Claude to ignore your actual instructions!” and recommends pruning. You may still want to prune. Shorter files save tokens, which cost real money and take real room in the window. The study says something narrower: pruning is unlikely to be the change that buys you obedience. Keep two limits in view. It measured compliance with one small target annotation, so you cannot conclude that “length never matters,” and this is one study.

Here is the part you can use: when an instruction keeps slipping, better wording is usually the wrong lever. Start a fresh session, and the same sentence works again.

Some things you want held every time

You should still write guidance. It is cheap, and it covers situations you could never list in advance. “Prefer small commits” can shape behavior across cases you would not have known how to encode as a pattern.

Some rules, though, cannot be left to weighing. Never commit to the main branch. Never write to that credentials file. Those need a second mechanism: a program instead of a sentence. A program does not interpret your intent. It runs and either lets the action through or stops it.

Where do you put that program? Start with a folder named .claude at the top of your project. Claude Code looks there whenever it starts in that directory. The leading dot hides the folder from a plain ls, which may be why you have not noticed it. Inside, a file named settings.json stores configuration as JSON, the format built from curly braces and quoted keys.

Before the file makes sense, you need one more piece. Every program returns a single number to the system when it finishes. Zero means it finished cleanly; any other number means it did not. That number is the program’s exit code, and Claude Code reads it. At most of the points where your program can run, exit code 2 stops the action. Exit code 1 stops nothing: Claude Code treats it as a problem in your program and continues with the original action.

Here is the same intent expressed through both mechanisms.

{
"hooks": {
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        { "type": "command", "command": "./scripts/no-main-commit.sh" }
      ]
    }
  ]
}
}

# Project conventions

Do not commit directly to main. Branch first.

The first file persuades; the second decides. Look at the second file again and notice how much more it requires: you must name the moment, the tool, and the script. That specificity is the cost of a guarantee. It is also why you would not build one for “prefer small commits.”

The second mechanism is a hook, a program Claude Code runs at a fixed point in its own loop. You name the hook in settings.json . In Module 9, you will write one and watch it fire.

Every module ahead gives you a place for one mechanism or the other: instruction files, commands, skills, settings, output styles, subagents, hooks, external tool servers, and permissions. For each surface, you will see what it holds and whether that content is guidance the model weighs or a guarantee that runs.

Check yourself

1. You cut your CLAUDE.md from 400 lines to 40, but the instruction still fades an hour into a long session. According to the study, what did the edit likely buy you, and what should you change instead?
2. You put both “Prefer small commits” and “never write to .env.production” in CLAUDE.md. Which instruction belongs somewhere else, and how can you tell?
3. You write the same check as both a PreToolUse hook and a PostToolUse hook. Both exit with code 2. Which one keeps the commit off main?