When a new developer joins the team, nobody expects them to start fixing bugs on day one with zero background. A senior sits with them and walks through the business decisions: why the product behaves the way it does, what changed before, and why we changed it. Skip that, and even a sharp new joiner will "fix" things that were done on purpose.
A coding agent shows up with even less, and it shows up fresh in every new session. It knows the framework. It has no idea what our product owner decided in March, so it'll happily undo behavior that was deliberate, because nothing in front of it says the behavior was a decision. We treat agents like new joiners who need that walkthrough, and behavior docs are how we give it to them.
The same docs fix an older problem for people. Product decisions used to disappear after they shipped. Six months later nobody remembered why a component behaved that way, and code review only ever spread the knowledge to the two people on the change. The idea came out of a team discussion, and of everything in how we run agents, it's the one I'd most like other teams to copy.
What goes in a behavior doc
Every ticket that changes behavior gets a behavior doc, a short text file written from a template and stored in the repo next to the code it describes. It's the walkthrough a senior would give, written down. It opens with what the feature is for in plain English, then covers how it's supposed to behave, the rules that must always hold and the behavior that must never come back, each with the reason behind it. A change log at the bottom records every ticket that touched it, with what changed, when and why.
For people, it's the fastest answer to "wait, why does this work like that?" You can search for it, and its history sits in version control next to the code. The decision no longer lives only in the heads of whoever reviewed the change.
For agents, it's the onboarding they'd otherwise never get. They read the matching doc before changing a component, and the separate agent that reviews our changes checks each one against it. What sold us was the first time an agent pushed back on a change with something like "this looks like a regression; per ticket X we decided the behavior should be Y," which is exactly what you'd hope to hear from a new joiner who'd been properly briefed.
The more decisions we write down, the better the agents get at our codebase. I mean our own decisions here, the calls the product owner and the team made, which no framework's documentation is ever going to cover.
How it rots as it grows
Living documentation can rot, and I'd rather say so up front. We're watching for three ways it goes wrong as the pile grows.
Staleness is the dangerous one. If a decision gets reversed and its doc doesn't say so, an agent will defend behavior you've already walked away from. That's a senior briefing the new joiner on a rule the team dropped last year, and I think it's worse than no briefing at all. You need a way to mark a doc as replaced, with a pointer to whatever replaced it, from early on. Michael Nygard's architecture decision records have handled this since 2011. When a later decision changes or reverses an earlier one, the earlier record can be marked superseded, with a reference to its replacement. Behavior docs need the same thing.
Volume comes next. Once there are hundreds of these, you need an index or some other way to pull up the right one, or the relevant doc gets lost in the pile.
Then there's ownership. A doc nobody owns slowly stops matching the code. Ours carry a "last reviewed" date, and the habit that matters is someone actually checking the doc against the code and moving that date forward.
None of this would stop me recommending the pattern. It's upkeep you sign up for, and it's cheaper to plan for at the start than to fix once the pile is big.
Why I think every team will need this
Every team using coding agents is about to find out their agents need the same briefing a new joiner gets. I think most will reach for something exotic, like vector stores, memory services or fine-tuning. The boring answer works today. Write each decision down in the repo, in a predictable place and in the same format every time.