Series: Weekend at Claude's — misadventures in building a production app with an AI anyone could mistake for the person who's going to make the whole thing happen
I made a very reasonable assumption that turned out to be completely wrong.
Aphilaty has a CLAUDE.md file in the repo root — a guidance document for Claude Code with build commands, deployment steps, and a running list of known gotchas. Hard-won lessons like: always use --legacy-peer-deps in the mobile directory. Never make app.json dynamic on Windows. Always run gradlew clean before a release build.
I wrote them all down. I was proud of this list. It was thorough.
I assumed that having the gotchas documented meant Claude Code would check them automatically before diagnosing problems. It does not work that way.
Claude Code reads CLAUDE.md and uses it as context. But "available as context" and "actively consulting before every diagnosis" are meaningfully different things. When I was chasing a build error, Claude was reasoning from the error in front of it — not cross-referencing my gotcha list to see if a known issue matched the symptom. The list sat there, complete and ignored, like a fire extinguisher nobody looked at while the kitchen burned.
The fix, once I understood the problem, was embarrassingly simple. I added an explicit instruction to CLAUDE.md:
## Standard Diagnostic Protocol Before diagnosing any build, runtime, or test error: 1. Check the Known Gotchas list below against the symptom 2. If a gotcha matches or plausibly applies, address it first
Now it checks. Because I told it to check.
The lesson is one of those things that's obvious in retrospect: documentation is passive. Claude Code is a capable reasoner that follows the task in front of it. If you want it to follow a checklist, you have to write the checklist and tell it to follow the checklist. Don't assume it will infer the meta-instruction from the existence of the content.
This applies everywhere. Be explicit about process, not just information.
We had the manual. We just forgot to tell anyone to read it before starting the machine.
Aphilaty is a privacy-first community coordination app. aphilaty.com