Long spec documents vs short decisions agents read
By Soumen Sarkar · October 2026
Comparison. If your problem is thinking a feature through before anyone builds it, write the spec: it is the best tool for one session building one feature. If agents keep building against calls your team already made, the fix is short decisions with their reasons, delivered to every session that works in that part of the product. Most product teams need both.
What are you trying to fix?
If your problem is thinking a feature through before anyone builds it, write the spec. If agents keep building against calls your team already made, a longer spec won't help. What helps is a short decision with its reason, in front of every session that touches that part of the product. Campfyrr does that second job. Most product teams have both problems.
Here is how product managers describe them, and what fixes each:
- "I need the agent to build this feature properly, edge cases and all." A spec. Claude Code's own guide suggests having Claude interview you and write a
SPEC.md, then building it in a fresh session. It adds that the most useful specs "are self-contained" and end with a check that proves the feature works (Claude Code best practices). GitHub's Spec Kit builds a whole workflow on the same idea. - "We decided this three weeks ago, and the agent built the opposite." A decision with its reason, where agents read it. The spec for last month's feature is not open when this month's session starts.
- "The rule is in the doc. The agent skipped it." A shorter thing to read. The same Claude Code guide warns that in an instruction file that is too long, "important rules get lost in the noise." Long inputs have a known weak spot: models use information at the start or end of a long context better than information in the middle (Liu and others, 2023).
The same day, with each
This is a scene, not a customer. Three developers and a product manager run a booking app. In May the product manager and the founder decided that refunds always go back to the original card, never as store credit, because store credit caused a run of support complaints. That call sits on page nine of the twelve-page payments spec.
With the long spec. In October a developer asks an agent to "let customers cancel a booking from the app". The agent reads the booking code and writes a good plan. Nobody hands it the payments spec, because the task is about bookings. Cancelled bookings now refund as store credit, the simplest path in the code. Support finds it a week later. The product manager points to page nine, and a developer spends a morning undoing it. The spec was right. It just wasn't the thing in front of the agent.
With Campfyrr. In May the same call is recorded as one line against the payments area: "Refunds go back to the original card, never store credit," with its reason and who made it. In October the agent reads its first payments file, and the hook adds a brief with that decision in it. The agent refunds to the card. It isn't sure about partial refunds for late cancellations, so it records an assumption. That reaches the product manager as a link, and she answers in one line. Nobody ran a command. See what a session gets.
At the end of the day, one team re-explains a decision it already made. The other makes the next one.
What does this look like in our own record?
Our own planning went the same way. By 17 October our strategy folder alone held nine documents (plans, roadmaps, user stories and research), about 35,000 words between them, with more plans in marketing. On 18 October one master plan combined the plans, and it opens with a single line that settles every clash: "Where any of them disagree with this page, this page wins."
Its decisions are short and carry their reasons. The price is "$9 per developer a month", and four one-line reasons follow, for example "Free business teammates make the product spread." A reader, or an agent, gets the call and the why in seconds. When a call changes, the new one replaces the old, as in this real example of a decision that replaced another.
When a long spec is the better choice
- One feature, built in one go. For a new checkout flow or an import tool, a spec that names the files, the edge cases and what is out of scope is the right thing to hand one session.
- The thinking is the point. Writing a spec is how a product manager finds the holes before an agent builds them. The spec built literally shows what happens when that step is skipped.
- Someone outside the team signs off. A client, legal or a partner wants the whole picture in one document. Campfyrr records one-line calls with reasons, not long design pages.
What it costs
Take 5 developers and 3 business teammates. A spec costs no licence: it lives in a file, Google Docs or Notion. Campfyrr is five developers at $7 billed yearly, so $35 a month ($45 billed monthly). The three business teammates read and answer for free, and everything is free during early access (pricing).
The cost that matters more is upkeep. With specs alone, someone has to remember which old spec holds the call, and paste it into each new session. With Campfyrr, the product manager records the decision once, and every session in that area gets it. Campfyrr doesn't write specs, run tests or replace your documents.
More on where decisions should live, on decisions in Notion, Linear or ADR files, on the wider problem of deciding what to build, and every product we compared in our research.
Verdict
Write a long spec if one session is about to build one feature, and the thinking needs to happen first.
Choose Campfyrr if several people run agents on one product, and calls made weeks ago keep getting built around.
Use both if you want the spec for this week's feature and the decisions inside it to outlive it. Pull each lasting call out of the spec as one line with its reason, and link the spec from the reason.
The problem this answers: Deciding what to build: "Development is fast now. Deciding what to build, clearly, is the slow part."
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).