When an agent makes a mistake, fixing the code fixes this run. Fixing the agent's environment fixes the next one too. So ask what let the mistake happen, and change that.
The environment is everything around the agent: the instruction files it loads (such as the repo's CLAUDE.md), the automated checks, the coding standards the reviewer enforces, and its tools.
Mechanical or a judgement call?
Sort each mistake first.
A mechanical mistake follows a fixed pattern: a banned API, a wrong import, a file in the wrong place. It gets a deterministic check, one that gives the same answer every time: a lint rule, a pre-commit hook (a check that runs before each commit), or a CI job.
A judgement call, like "does this match the surrounding style?", can't be checked by code. It becomes a written coding standard in CODING_STANDARDS.md, which the reviewer reads.
A mechanical mistake
A judgement call
follows a fixed pattern
can't be checked by code
a banned API, a wrong import, a file in the wrong place
"does this match the surrounding style?"
gets a deterministic check
becomes a written coding standard in CODING_STANDARDS.md, which the reviewer reads
a lint rule, a pre-commit hook (a check that runs before each commit), or a CI job
Sort each mistake first.
When in doubt, build the check rather than write the standard.
Look before you build
Read the repo's own check commands first, like the lint script in package.json or the CI workflow. A check that already exists but isn't wired up, or is quietly broken, is the finding. Don't build a second one.
A repo with no guardrail at all (no pre-commit hook, and no CI job running lint, typecheck and tests) is a finding in itself. It's a missed chance that keeps costing you, not a neutral default.
Keep instruction files small
A repo's CLAUDE.md (or AGENTS.md) is loaded into the context window of every agent that works in the repo. Use it sparingly, mostly for navigation pointers: short notes that say where to find something.
Where it shows up
setup-matt-pocock-skills is the first environment fix, made once before your first Flow. It records where Issues live, the triage labels and the doc layout, and adds a short ## Agent skills block to CLAUDE.md or AGENTS.md that points to those files. Without it, Skills like to-spec tell you to run setup first.
retro closes the main Flow. After a build, especially one that went sideways, it looks back over the session and suggests changes to the environment, not the code. After a diagnosing-bugs fix is in, run retro in the same session to ask what would have prevented the bug.
Going deeper
4 min read · Going deeper not read
Why it exists
Matt put the idea plainly in an interview published 2026-09-17, on The Pragmatic Engineer: "your code is the environment the agent operates in." And "you should always be thinking about improving that environment". Later in the same talk he described the engineer's new job: "we are our agents platform team." And: "We are trying to build the environment for them to succeed."
In his v1.3 release notes (updated 2026-10-05), he lists what that job meant in practice: "keep AGENTS.md lean, keep the skills sharp, add good lint rules, keep the code easy to navigate." He was doing it by hand, and that is the work this Principle names.
How it works underneath
A name for it. One name for this idea is "harness engineering". Mitchell Hashimoto used it in a post on 2026-02-05. He is careful about the word: "I don't know if there is a broad industry-accepted term for this yet". His definition: "anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again." It comes in two forms for him: "Better implicit prompting (AGENTS.md)", and "Actual, programmed tools", such as scripts that run filtered tests.
Where Matt and Mitchell differ. They agree on the main fix. Mitchell: "The most sure-fire way to achieve this is to give the agent fast, high quality tools to automatically tell it when it is wrong."
From snapshot/skills/ask-matt/SKILL.md, line 34: “/retro closes the loop. After a build, and especially one that went sideways, it looks back over the session and suggests changes to the agent's environment, not the code: navigation pointers, automated checks, the coding standards /code-review enforces, steering files, tooling. Mechanical mistakes become deterministic checks; judgement calls become coding standards. The next build then starts from a better environment.”
From snapshot/skills/retro/SKILL.md, line 19: “Classify the violation first: a mechanical one (a fixed syntactic pattern, a banned API, an import shape, a file-location rule) gets a deterministic check, full stop: a custom rule in the repo's own linter, a new pre-commit hook, or a new CI job”
They differ on where a simple repeat mistake goes. For things like "the agent repeatedly running the wrong commands or finding the wrong APIs", Mitchell updates AGENTS.md. Of Ghostty's file he writes: "Each line in that file is based on a bad agent behavior, and it almost completely resolved them all."
Matt's advice is newer. Asked whether to add a line to CLAUDE.md for a repeat mistake, he says "Usually not". His goal: "Your AGENTS.md gets shorter over time, not longer."
Mitchell Hashimoto, 2026-02-05
Matt Pocock, updated 2026-10-05
a simple repeat mistake
updates AGENTS.md
Usually not
AGENTS.md
Each line in that file is based on a bad agent behavior
gets shorter over time, not longer
Where Matt and Mitchell differ.
When the two disagree, the current retro SKILL.md decides, and it sides with Matt. So this Course does too.
Why a check beats a sentence. Matt's short version: "A check can fail. A sentence in a Markdown file cannot."
A real example
On 2026-09-15, Matt opened and merged pull request #1083. It changed retro's own instructions, adding one default: "build the check over writing the rule".
The same pull request shows the limit of that default. Matt's repo bans em-dashes, but only through a sentence: "No em-dashes, per this repo's prose rule in CLAUDE.md." The rule was checked by hand: "Read the diff aloud against CLAUDE.md's em-dash rule". And the pull request notes "No automated test surface for SKILL.md prose in this repo".
Where it goes wrong
Letting the environment drift. Matt warns that "agents are producing software entropy at a higher rates than ever." And: "it's very easy for the garden to itself just to suffer entropy, right? to gather weeds and to do all that stuff."
For failures of the retro Skill itself, see retro.
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't), pick a mistake an agent made more than once.
Write down how Mitchell would fix it: a line in AGENTS.md, a tool, or both.
Now sort it the Course's way. If it's mechanical, add a check where the repo's CI already runs (.github/workflows/ci.yml), for api/ or web/. If it's a judgement call, add one line to CODING_STANDARDS.md.
Open a pull request, and watch the check fail on the old mistake.
Going deeper's Check questions are asked in Next up.
“Default to building the check over writing the rule. Reserve CODING_STANDARDS.md for genuine judgement calls”
From snapshot/skills/retro/SKILL.md, line 18: “A repo with no guardrail (no pre-commit hook and no CI job running its lint/typecheck/test command) is itself a finding: an un-linted repo is a standing missed opportunity, not a neutral default.”
From snapshot/skills/retro/SKILL.md, line 18: “Read the repo's own check command first (its package.json/build-tool lint/check scripts, its CI workflow), so a check that already exists but sits unwired or silently broken is the finding, not a reinvention.”
From snapshot/skills/retro/SKILL.md, line 41: “these files are pushed to the context window of any agent working in this repo. They should be used incredibly sparingly, usually only for navigation pointers to other files.”
From snapshot/skills/setup-matt-pocock-skills/SKILL.md, lines 9–13: “Scaffold the per-repo configuration that the engineering skills assume: - Issue tracker: where issues live (GitHub by default; local markdown is also supported out of the box) - Triage labels: the strings used for the five canonical triage roles - Domain docs: where GLOSSARY.md and ADRs live, and the consumer rules for reading them”
From snapshot/skills/to-spec/SKILL.md, line 9: “The issue tracker and triage label vocabulary should have been provided to you. If not, tell the user to run /setup-matt-pocock-skills.”
From snapshot/web/mitchellh.com/writing-my-ai-adoption-journey.md, lines 216–219: “I don't know if there is a broad industry-accepted term for this yet, but I've grown to calling this "harness engineering." It is the idea that anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again.”
From snapshot/web/youtube.com/watch-v-4dhcspkebwi.md, line 993: “And that gardener metaphor is nice because, you know, um it's very easy for the garden to itself just to suffer entropy, right? to gather weeds and to do all that stuff.”