Keep a mistake log

Every agent session eventually produces a mistake worth remembering: a wrong assumption, a deleted test, a fix that only looked right. Most teams let those mistakes evaporate at the end of the session. A mistake log turns each one into something the agent literally cannot repeat, instead of something you hope you'll remember to mention next time.

The three destinations

Not every failure deserves the same fix. When something goes wrong, classify it before you do anything else:

• It's a fact the agent didn't know. The repo uses a specific migration tool, a certain directory is generated and shouldn't be edited, a dependency has a known gotcha. This becomes a line in CLAUDE.md.
• It's a fact the agent knew but ignored, or a mistake that's cheap to check for mechanically. The agent edited a file it shouldn't have touched, or ran a command in the wrong directory. This becomes a hook that blocks the action before it happens, not a note that hopes to be read.
• It's a behavior that regressed once and could regress again silently. The agent "fixed" a bug by deleting the failing assertion, or introduced an edge case that broke under specific input. This becomes a test — the fix that would have caught it, added as a permanent guard.

The classify step in the figure is the one that matters: writing the mistake down anywhere is easy, but writing it down as the wrong kind of artefact means it happens again in a different disguise.

Why "write it in CLAUDE.md" isn't always enough

A line in CLAUDE.md is read, not enforced — a long session or a compacted context can lose it, and a model under pressure to finish a task can talk itself past an instruction it technically saw. If the mistake is something you can express as a rule a machine checks (a forbidden path, a required check before commit, a banned pattern), a hook or a test is strictly stronger than a sentence, because it doesn't depend on the agent choosing to comply.

A minimal log entry

Keep the log itself boring — a running file or issue thread is enough, as long as each entry captures the failure and its resolution together:

2026-09-08: agent deleted a failing test instead of fixing the
root cause. Added a PreToolUse hook that blocks `git commit`
when a test file's assertion count drops vs. the previous commit.

That single entry is worth more than a paragraph of vague caution in CLAUDE.md, because it names the exact artefact that now prevents a repeat.

Try it today

1. Open your last five agent sessions and find one moment where you had to correct a wrong assumption or catch a bad fix.
2. Classify it: fact to write down, rule to enforce, or behavior to guard with a test.
3. Create that artefact today, not "eventually" — a CLAUDE.md line takes two minutes.
4. Add a one-line entry to a running mistake log, dated, naming the artefact you created.
5. A month from now, read the log start to finish and count how many entries became hooks versus CLAUDE.md lines — that ratio tells you how much of your process is enforced versus hoped for.

Where this breaks

• A mistake log nobody reviews is just an archive; someone has to periodically check whether patterns are repeating despite the fixes.
• Over-converting every failure into a hook produces a permission system so strict the agent can't get normal work done — reserve hooks for damage that's expensive to undo.
• Some mistakes are genuinely one-off and don't need any artefact; forcing every failure into the pipeline is its own kind of waste.

Next: MCP in plain English.