A few weeks ago I watched an agent build a feature beautifully.
Clean code. Tests passed. Did exactly what I asked.
Three sessions later, I opened the same service and didn't recognise it. Nothing was wrong, exactly. Every individual decision was reasonable. Stacked together, they'd quietly walked the codebase somewhere I would never have designed it.
That's when it clicked. The problem wasn't the model. The model was great. The problem was that every session started from zero — no memory of the boundaries I'd been protecting, no idea which patterns were load-bearing, no clue about the trade-off I made three weeks ago for a reason I never wrote down.
I'd seen this exact failure before. Just with humans.
The new hire who never read the docs
You know the version. Someone joins. They're sharp. They ship something in week one that works — and breaks an unwritten rule nobody told them about. Not their fault. The rule lived in my head, or in a Slack thread from last March, or in the muscle memory of whoever's been here longest.
So we'd explain it. Then explain it again to the next person. The "why" never made it anywhere durable. It just got re-explained, badly, on demand.
An AI session is a new hire who shows up brilliant, fast, and with total amnesia. Every single time. Re-explaining the codebase to a fresh chat window every morning is exhausting, and honestly I'd forget half of it under pressure anyway.
Same problem. I'd just been solving it twice.
One source of truth, two audiences
Here's the shift that fixed it for us: the context an AI agent needs to not wreck your codebase is the same context a new engineer needs on day one.
Not similar. The same.
Which patterns are deliberate. Where the boundaries are and why crossing them costs you. What "done" means here. Which decisions are settled and which are still up for debate. A human needs that to contribute without breaking things. An agent needs that to contribute without breaking things.
So we stopped keeping it in our heads and started keeping it in the repo. Plain markdown. Committed. Versioned with the code it describes.
service-payments/
├── CLAUDE.md # how this service works, and why
├── src/
├── test/
└── ...
A root CLAUDE.md (or AGENTS.md — pick the convention your tools read) carries the project-wide principles. Each service that has real rules of its own gets its own. When an agent opens that service, it loads the file automatically. When a human opens that service, the same file is sitting right there, written so a person can actually read it.
One file. Two readers. Nothing to keep in sync, because there's only one of it.
What actually goes in the file
This is where most teams get it wrong. They dump the obvious in there — "we use TypeScript," "run the tests before you push" — and the file becomes noise everyone scrolls past.
The rule I use: a line earns its place only if leaving it out would let a plausible, reasonable-looking mistake sail through review.
That filter kills most of what you'd be tempted to write. What survives is the good stuff:
## Boundaries
- Services talk over the message bus, never direct HTTP to each other.
If you need another service's data synchronously, that's a design
smell — raise it, don't route around it.
## Validation
- Every inbound payload is parsed by a schema at the edge. No raw
request bodies past the controller. A missing field fails loud on
the way in, not three layers deep at runtime.
## What "done" means here
- A feature isn't done when it works. It's done when the next person
can tell what it does without asking you.
## Settled vs open
- SETTLED: how we do idempotency. Don't reinvent it; copy the pattern.
- OPEN: our caching story. If you touch it, expect a conversation.
Notice none of those are syntax. They're judgment. The settled-vs-open split alone has saved me hours, because it tells both the agent and the human where to copy an existing pattern versus where to stop and ask a person.
The "why" matters as much as the rule. "Don't call services directly" is an order. "Don't call services directly, because the moment you do you've created a hidden dependency that nobody can see until it breaks at 2am" is something a human will actually remember and an agent will actually respect.
The honest part
This isn't free, and it isn't a silver bullet.
The files rot if you let them. A rule that's no longer true is worse than no rule — it teaches the wrong thing to two audiences at once. So they get reviewed like code, because they are code now. When a settled decision changes, the file changes in the same PR. If that feels like overhead, it's the overhead you were already paying in repeated explanations — just made visible.
And no, I didn't stop using AI tools while waiting for the perfect setup. The point isn't to control the agent. It's to make sure my long-term thinking is still present in a codebase that's increasingly being written by someone — something — that wasn't in the room when the decisions got made.
When one file stops being enough
A markdown file works until it doesn't. One service, a handful of rules — CLAUDE.md is perfect. But spread it across a dozen services and the tending becomes the whole job. The rules drift from the code they describe. The "why" behind a feature ends up split across a spec, a ticket, a PR description, and a conversation nobody can find six weeks later. The flat file can't keep up, and a stale rule teaches the wrong thing to both readers at once.
That rot is what pushed me to build Bodhiorchard — an open-source, self-hosted project I've been working on independently (Apache 2.0, runs on Claude Code). Same idea as the file, taken further. Instead of one feature's knowledge scattered across tickets, everything for that feature lives in a single living document: the spec, the tech spec, the test plan, the acceptance criteria, the full history — tied to the actual code. And the knowledge layer stays current by syncing from the code and those docs automatically, so it's semantically searchable by a human and fed straight into every agent's prompt.
That's the part I care about most. Not a wiki you have to remember to update. A wiki that's current because it's wired into where the work already happens. Confluence goes stale the day you write it. This doesn't, because nobody's job is to keep it alive by hand.
The principle never changed. One source of truth, two audiences. I just got tired of being the sync engine.
What changed
Less re-explaining. That's the boring, real win.
New engineers read the same file the agent reads, and it turns out the document you write for a machine that takes everything literally is a really good onboarding doc. No assumed context. No "you'll pick it up." Just the actual shape of the thing.
And the drift slowed down. Not because the agent got smarter — because it finally knew which walls were load-bearing.
I used to think the codebase lived in the code. It doesn't. Half of it lives in the decisions around the code — and for years I kept that half in my head, where exactly one reader could access it.
Now it's in the repo. Where everyone can. Human or not.
If you're letting AI write a meaningful share of your code: where do the rules of your codebase actually live right now? And who can read them?
Top comments (0)