Recording decisions as agents work
By Soumen Sarkar · October 2026
Playbook. Record each call the moment it's made, in one line with its reason, where every agent reads it. Steps, agent instructions and the signals that it's working.
How do you record decisions while agents work?
You record a decision at the moment it's made, in one line with its reason, in the place every person and agent reads before touching the same code. Whoever makes the call writes it, human or agent, while the work is still open in front of them. Done this way, the record grows with the work, and the next session in that part of the code follows the call instead of making a different one.
This playbook sets that up so it happens dozens of times a day without anyone treating it as paperwork.
Who is this for?
Tech leads and developers whose agents make real calls in the code: how money is stored, which library handles dates, whether an endpoint is versioned. If you run several sessions at once, or your teammates do, those calls are being made in parallel, and most of them are made by agents.
What do you get?
- A decision record that grows as the work does, with no one writing it up afterwards.
- Agents that follow a call made in another session, by another person, last week.
- Clashes caught when the second decision is written, not when two finished changes contradict each other.
- Reversals that carry their reasons, so nobody has to dig out why something changed.
What counts as a decision?
A decision is a call that others should follow. The simplest test: would the next agent working here make a different choice if it didn't know about this one? If yes, it's a decision, and it gets recorded.
It helps to keep three kinds of call apart:
- A decision is a one-off call behind the work: "Session tokens expire after 14 days of inactivity."
- A rule says how to keep building: "Never change a public endpoint without adding a new version."
- An [assumption](/glossary/assumption) is a call you're acting on but want checked: "Assuming expiry counts from the last request, not the last sign-in."
Skip the rest. Variable names, formatting, and choices the code already makes obvious don't need a line. A record full of trivia is a record nobody reads.
Step 1: Pick one place decisions live
Before any format or instruction, decide where decisions go. One place, searchable by every agent, organised by the part of the code they apply to. A decisions file per area works, such as docs/decisions/auth.md for "Auth · lib/auth". So does any shared record your agents can search.
What matters is that an agent about to change lib/auth can find every standing decision about lib/auth in one read, and that old decisions stay visible when they're replaced. Where decisions should live goes into the options.
Step 2: Use one line, every time
A decision written in one consistent shape is easy to write and easy to scan. The decision line template has the shape to copy: the call, the reason, what it applies to, what it replaces, and when to revisit it.
A filled-in line for the auth example reads: the call is that tokens expire after 14 days of inactivity; the reason is that the support team sees most lockouts from people returning after two weeks away; it applies to Auth · lib/auth; it replaces the earlier 30-day expiry; revisit if the security review asks for shorter sessions.
The "because" is the part that matters most. A decision without a reason can only be obeyed or ignored. A decision with one can be judged, which is what the next agent needs when the situation has changed.
Step 3: Tell agents when to record
Agents record decisions reliably when the instruction names the moment. Put this in the file every agent reads at the start (CLAUDE.md, AGENTS.md, or your client's rules file):
Record decisions as you make them.
- When you make a call another person or agent working in this area should follow,
write it as a decision line, with the reason, at the moment you make it.
- Before you write it, read the decisions that stand for this area. If yours
contradicts one, say so plainly and don't build on either until the team keeps one.
- If your call replaces an earlier decision, say which one and why. Never delete
the old one; mark it superseded.
- If the call isn't yours to make (data, money, access, public interfaces, deleting
things), state it as a high-stakes assumption instead and keep going.
- List the calls you made in the pull request description.
The team agent instructions template covers the rest of the working agreement; this block adds the detail for decisions.
Step 4: Check against what stands before writing
The cheapest moment to catch a clash is before the second decision exists. An agent that reads the area's decisions first will notice that "tokens expire after 14 days" contradicts a call made last month that "sessions never expire for single sign-on users". Now it can do one of two things, both fine:
- Narrow its own decision so they agree: "except single sign-on users, per the earlier decision".
- Write the clash down and tell the person it works for, so the team keeps one.
What it must not do is write the new decision quietly and build on it. Two standing decisions that contradict each other will each attract work, and the work will contradict too. What happens when two agents decide opposite things walks through settling one.
Step 5: Supersede, never delete
When a decision changes, the old one stays, marked superseded, with the reason and a pointer to what replaced it. This keeps two things visible: what the team believes now, and how it got there.
It also protects work in flight. A session that started an hour ago may still be building on the old decision. When the old line says "superseded by the 14-day expiry, because of support lockouts", that session can find the change and adjust, rather than finishing work against a call that no longer stands.
Step 6: Make decisions reach the next agent
A recorded decision only works if the next agent reads it before acting. Two habits make that happen:
- Keep an area summary at the top of each part of the code, with "Decisions here (follow these)" near the top.
- Tell agents to read it before their first change in that area, and to follow what it lists unless they record why not.
How decisions reach every agent that touches the same code covers this in more depth, including what to do when a decision looks out of date.
Step 7: Review decisions where the change is reviewed
Every pull request lists the calls made in it, with their reasons. The change reasons template has a "Calls made" section for this. A reviewer reading "Tokens expire after 14 days of inactivity, because of support lockouts" can disagree in one comment, and the fix is a new decision that supersedes it, not a stalled review.
What should you watch for?
- Decision inflation. If every line of code earns a decision, nobody reads them. Ask agents to record only calls that change what the next session would do.
- Missing reasons. "Decision: use library X" with no reason is a rule nobody can judge. Send it back for the "because".
- Silent reversals. Code that does the opposite of a standing decision, with nothing recorded. This is the most expensive pattern, because the record now misleads.
- Stale decisions. A call made months ago that nobody relies on any more. The "revisit if" field helps; so does reading old decisions with judgement rather than as law.
- Agents deciding what isn't theirs. A decision about deleting customer data is not an agent's to settle alone. It belongs in a high-stakes assumption, where the right person sees it first.
How do you know it's working?
Look for these signals rather than counting lines:
- Agents mention standing decisions in their plans and pull requests: "following the 14-day expiry decision".
- People stop asking each other "what did we decide about X?" because the answer is one search away.
- Clashes come up when the second decision is written, not in review or after release.
- Reversals arrive with a reason attached, and the old call is still readable.
- Someone new to an area reads its decisions and builds on them, instead of reopening them.
What does Campfyrr automate?
Campfyrr turns each step above into a tool call or something that happens on its own.
- Recording. Agents call
log_decision with a title, a kind (architecture or business), the context, the decision and its consequences, filed in the project. Rules go through log_rule. - Checking. Each new decision is checked against the project's standing decisions as it's recorded. If it contradicts one, the newer call stands and the earlier one is marked superseded; the reply says so straight away, and the agent is told to mention the change to the person it works for.
- Showing it. The change appears in the project's Activity feed, so the team sees which call replaced which. Nobody has to click to settle it; if the earlier call was right, record it again with its reason.
- Superseding. A decision that replaces another passes what it supersedes and why. The old one is kept, marked superseded with the reason, and the reply lists the documents that still link to it so someone can revisit them.
- Reaching the next agent. In Claude Code, the first time a session reads or edits a part of the code, its area brief lists the decisions made there. Decisions that are recent or still in use come first; one nobody has written to or relied on for four months is shown with "check it still holds".
- Finding the ones nobody logged. Campfyrr reads the team's pages and suggests the decisions written in them, for a person to approve.
- Reviewing. On commit or pull request, the change's reasons include the calls made, with a link for the description.
Campfyrr doesn't approve or block anything. A clash settles itself with the newer call, and the team can always record a different one.
The principle behind all of this is decide by doing: the call is made in the work, with its reason, and the sentence that records it is the decision.
The principle behind this: Decide by doing: Our decisions live in what we do, not in what we say.
Move as one at agent speed. Nobody waits. Add Campfyrr to Claude: it briefs every agent before it touches the code, keeps assumptions and handoffs where the team can see them, and never takes your code (what it keeps).