C² Method8 min read
The gotchas folder: the cheapest context your agent reads
One short file per trap, named after the trap, pointed at from the router by symptom. How I stop agents repeating the same mistakes, with real gotchas from my repos.
An AI agent repeats a mistake because the fix lived somewhere the next session can't see: a chat, a closed terminal, someone's memory. The way to stop it is to write each trap down once, as one short file, in a folder the agent checks before it works in that area. In the C² Method that folder is docs/03-knowledge/gotchas/. Each file holds one trap: the symptom, the cause, the fix, and a check. It's named after the trap, and the router file points at it by symptom.
How to stop your agent forgetting covers the broad problem: why agents forget, and why learning has to live in the repo. This article is narrower and more practical. It's just the gotchas folder: what goes in a file, how to name it, when to write one, how the router finds it, and real examples from my repos.
Why a gotcha is the cheapest context
Everything in CLAUDE.md costs context in every session. Claude Code's memory docs recommend keeping each CLAUDE.md under 200 lines, because longer files cost more context and reduce adherence. They also note that @path imports help organise a long file but don't reduce its cost, because imported files load with the file that imports them.
My main repo's gotchas folder holds 217 files, about 12,500 lines in all. Loading that into every session would be absurd. Most sessions need none of it.
A gotcha file costs nothing until it's needed. The agent pays for one file, roughly 40 lines, at the moment it works in the area where the trap lives. That's the trade: a large, growing body of knowledge with a near-zero standing cost.
What a gotcha file looks like
Here's a real one from the repo for this site, written on 17 November 2026, in full:
# next/font/google can fail a Host deploy
**Symptom:** a production deploy fails in `NextFontGoogleFontFileReplacer` /
`resolve_internal` and nothing in the commit is wrong. It happened on 2026-11-09 and again on
2026-11-17 (the article-table fix, commit 8bf68f5). A re-push may pass, because the cause is
the build fetching font files from Google at build time.
**Fix (2026-11-17):** IBM Plex is self-hosted from `app/fonts/` with `next/font/local`
(`app/layout.tsx`). The Sans file is Google's Latin variable font (one file, weights 400-700);
Mono is three static weights. Licence: SIL Open Font License.
**Rule:** don't reintroduce `next/font/google`. To add a weight or face, download the woff2 from
the Google Fonts CSS API (Latin block) into `app/fonts/` and add it to the `localFont` src list.
Thirteen lines. The symptom quotes the actual error text, which is what an agent will be looking at when it needs this file. The cause explains why a re-push sometimes "fixes" it, which is the misleading part. The rule says what not to do and how to do the legitimate thing instead (add a font weight), so the agent isn't left with only a prohibition.
The other gotcha from that night has a part I'd put in every file, a check:
**Check:** `curl -s <article url> | grep -c 'og:image'` should print 1.
The bug was that every article page emitted about 97 og:image tags, the first one for a different article. The check is one command with one expected number. An agent touching social images later can prove it hasn't brought the bug back, rather than believing it.
The four parts every gotcha needs
The C² starter kit has a gotcha template with frontmatter and six headings. Real gotchas drift from it, and that's fine. Only 49 of my 217 use frontmatter at all. What they keep is four parts:
| Part | What it answers | Write it as |
|---|---|---|
| Symptom | What will I see? | The exact error text or behaviour, and when it was found |
| Cause | Why does it happen? | The mechanism, especially why the obvious fix doesn't work |
| Fix | What do I do instead? | A specific pattern, command or setting |
| Check | How do I know I'm clear? | A command with an expected result |
The cause is the part people skip and shouldn't. A fix without a cause is a ritual. The next agent will follow it until something nearby changes, then drop it, because it can't tell whether it still applies.
Name the file after the trap, not the topic
Look at a few real filenames from the main repo:
deleting-a-function-source-does-not-undeploy-it.md
merge-deploys-code-but-never-applies-its-migration.md
desktop-vitest-needs-its-own-npm-ci.md
kv-access-changes-are-not-instant.md
worker-lockfile-wrangler-drift.md
Each name is the warning. A plain ls of the folder reads as a list of things that will hurt you, and an agent grepping filenames for "migration" or "npm ci" lands on the right file without opening anything.
The older style, openai-parameter-naming-gotcha.md, tells you the topic and nothing else. Five files in that folder still use it.
When to write a gotcha
Three conditions, all true. It was non-obvious: a competent person would walk into it. It cost real time. It will bite again: the code, tool or habit that caused it is still there.
The best time is the session that found it. The C² session brief template has a gate for exactly this: if the brief's "key discovery" section has content, a file in docs/03-knowledge/ goes in the same commit. Not next week. The overnight brief from this site shows it working: two traps found, two gotcha files committed in the same session, both linked from the brief.
The worst time is the second time. The font failure above first hit on 9 November. It hit again on 17 November, and that's when it got written down. A file on the 9th would have saved the second failed deploy.
How the router points at gotchas
A gotcha the agent never opens doesn't help. Two things make it get opened.
The router points at the folder. My main repo's CLAUDE.md lists /docs/03-knowledge/gotchas/ among its most-used locations, and my global instructions tell every session to check the latest session brief and the gotchas before starting work.
The router points at the worst ones by symptom. For traps that are costly and easy to misread, CLAUDE.md has a table keyed on what you'd actually see:
| Issue | Guide |
|---|---|
| A worker won't deploy / "lock file does not satisfy" | worker-lockfile-wrangler-drift.md: check all eleven, not just the one that broke |
| Changed a bucket's access and it didn't take | kv-access-changes-are-not-instant.md: ~60s |
That's one line per gotcha in the router, and the line carries the punchline, so even an agent that doesn't open the file gets the most important part. The rest stays in the file, paid for only when needed. Claude Code's path-scoped rules are another way to do this: a rule in .claude/rules/ with a paths field loads only when Claude works with matching files, so a one-line pointer to a gotcha can load only for the code it's about.
What doesn't work is a hand-kept index. The folder has a README.md that was meant to list the gotchas. It links 11 of the 217 and was last updated in May 2026. Nobody maintains an index when they're busy fixing the thing. Let the filenames be the index, and spend your router lines on symptoms.
Write the general lesson, not just the incident
The gotchas that pay most go one step past the incident. worker-lockfile-wrangler-drift.md starts with one worker that wouldn't deploy because its lockfile pinned an old wrangler version. Then:
## The part worth internalising
It surfaced only because a change touched that worker. **Checking all eleven found a second one**,
identical fault ... Not drifted, not broken in production: simply undeployable the moment anyone
edits it.
It then gives a loop that dry-runs npm ci in every worker directory. The file opens: "Found three times now." The lesson isn't "fix this lockfile". It's "when one breaks, check the whole set".
kv-access-changes-are-not-instant.md does the same. It records an access change that took about 60 seconds to reach the edge, then ends on the general rule: anything globally replicated needs a poll, not an assertion, and one negative read is not evidence. The file names its cousins: a just-deployed worker that still serves the old version, and a package publish that isn't on the registry the instant it returns.
And some gotchas grow into small systems. agent-worktrees-are-never-cleaned-up.md began on 5 October 2026 when 123 leftover agent worktrees, about 216 GB, filled my Mac's disk. The file now holds a measured table of three ways to create a worktree (from about 2.9 GB down to about 0.08 GB each), why du lies about APFS clones and df doesn't, and the three guards now in place against it. The router carries one line pointing at it.
What doesn't go in the gotchas folder
Keep the folder for traps. Other knowledge has other homes:
- Rules ("never commit to main") go in the router. They apply every session.
- Decisions ("X was chosen over Y because Z") go in decision records.
- Session state ("item 3 is half done") goes in the session brief.
- Patterns ("this is how an edge function is written here") go in patterns.
A gotcha is specifically the thing that looks fine and isn't. That's what makes it worth a file: it's the knowledge an agent can't derive from reading the code, because the code looks right.
Two minutes to write the file. One line in the router if it's a bad one. After that, the mistake costs nothing the next time, for every agent, on every model.
Start here: how to stop your agent forgetting, what a contextbase is, or run your first C² session.
Questions people ask
- How do I stop an AI agent repeating the same mistake?
- Write the mistake down once, where the next session will read it before it acts. In C² that is a short file in docs/03-knowledge/gotchas/ with the symptom, the cause, the fix and a check, named after the trap itself. Then point your router file at it by symptom, so an agent that sees the error finds the file.
- What is a gotcha file?
- A short markdown file describing one non-obvious trap in a project: what you see when you hit it, why it happens, what to do instead, and how to check you're clear. In my main repo the median is about 40 lines. It is written once, at the moment the trap is found, and committed with the fix.
- Should gotchas go in CLAUDE.md?
- Not in full. CLAUDE.md loads into every session, and Claude Code's docs recommend keeping each one under 200 lines. Put the gotcha in its own file and give the router a one-line pointer for the few that bite most often. The file costs nothing until an agent works in that area.
- When should I write a gotcha?
- When something was non-obvious, cost real time, and would bite again. If a session brief has a 'key discovery', the gotcha goes in the same commit. The worst time to write one is the second time the same trap bites.
- How do you name gotcha files?
- As the sentence that describes the trap, in kebab case: deleting-a-function-source-does-not-undeploy-it.md rather than functions-gotcha.md. Then a plain directory listing reads as a list of warnings, and a search for the symptom finds the file.
Part of the C² Method. Start with the method
Put this in your repo
The C² Method is free and open. Point your agent at the kit and get started in minutes.