Agents write the code. Who keeps the why?

Code records what, not why

A codebase is an exact record of what software does and a poor record of why it does it. A function that rounds prices down tells you that it rounds down. It doesn't tell you that a customer complained about being overcharged, that whoever owns billing agreed to round down from then on, or that the rule holds for invoices and not for quotes. Comments help a little and commit messages a little more, but both are written at the moment of the change, by whoever made it, and they rarely say what was weighed and turned down.

When people wrote the code, memory covered the gap. The person who settled the rounding question was usually still around when the next change touched it. They remembered the complaint and the agreement, and they stopped anyone who tried to undo it. The why lived in people, and the people stayed.

With coding agents, the one who decides and the one who writes are no longer the same. The agent writes and you decide. The agent that writes tomorrow's change isn't even the one that wrote today's: it starts again from the code and from whatever text it is handed at the start of its session.

Where the why ends up today

In most projects built with agents, the reasons end up in three places. The first is the chat. You explained the pricing rule in a long session, corrected the agent twice and agreed on an approach. Then the session ended, and the transcript went into a folder nobody opens.

The second is an instructions file in the repository that grows by a paragraph every time an agent gets something wrong. It collects orders rather than reasons: always do this, never do that. After a few months it also collects contradictions, and nobody remembers which line came from which mistake.

The third is your head. That works while you are the only person on the project and you remember everything. It stops working the first time you hand a feature to an agent while you sleep, come back from a week away, or bring a second person in.

What a missing why costs

Anyone who has built with agents for more than a few weeks knows the symptoms. An agent brings back a feature you removed, because the code that removed it looks like an oversight. Another simplifies a check that exists for a legal reason. A third renames a concept to the word it finds more natural, and the product now has two names for one thing.

None of these is a failure of skill. Each agent did something reasonable with what it could see. The failure sits upstream: the decision that would have stopped it was never written down where the agent reads.

The cost isn't only the rework. Review gets heavier, because you can't trust a change to respect what was decided, so you read everything. And decisions get taken twice, because nobody can find the first answer, which means they are sometimes taken differently the second time.

Write the why where agents read

The fix isn't more comments. It is a place for intent that sits beside the code rather than inside it, written in a shape an agent can read before it starts. Four kinds of record carry most of the weight.

Goals, with what done means. Not a ticket title but the outcome and the condition that proves it, written when the goal is set. An agent that knows the goal can tell whether its change serves it, and a reviewer can tell whether the goal was met.

Decisions, with their reasons. Short, dated, with the option that lost: we round down on invoices because billing agreed to after a customer complaint, and rounding up was turned down. One line like that saves weeks of drift, because the next agent that wonders about rounding finds the answer instead of inventing one.

Behaviour, described in product terms: what a customer sees, what the system must never do, where the edge cases are. And links, from every piece of work back to the goal it serves and the decisions that shape it, so the reason travels with the change instead of staying behind in a chat.

Keep the decisions with a person

Writing the why down doesn't hand it to the agents. It does the opposite. Once the reasons are written, it becomes clear which questions an agent may settle and which it must bring back. How to structure a function is the agent's call. Whether the product rounds prices up or down is not.

That line is easier to hold when the work has places where it stops for a person: a plan approved before the build starts, a result checked against the goal before it ships. The agent proposes, a person decides, and the history shows what was decided and by whom. Over time that history becomes one of the most useful things a project owns, because it is the part of the product an agent can't reconstruct from the code.

Where ctxflows fits

ctxflows is where that lives: roadmap, boards, docs and the rules your product follows, written once, and the workflows agents follow to build from them. Goals on the roadmap carry what done means, written with the goal. Docs describe the product's behaviour in pages your agents read, down to a single section. Every item on a board links back to the goal it serves.

Memory and search keep the reasons findable. A knowledge graph links a decision to the item it shaped and the run that built it, so the question “why did we choose this?” has an answer an agent can reach from its own session. The history of every change shows who made it, when and why. Your code never enters ctxflows: it stays in your repository, and the why sits beside it.

Workflows put the stops where they belong. An approval waits for a person before the build and before the work ships, and the agent works from what you wrote rather than from what it guessed. A person decides what is built and whether it was met.