Decisions with the why attached

Small teamsTeam that keeps asking 'why did we do this?'

Why do we store prices in cents? Why Postgres and not Mongo? The answers lived in old chats, and agents re-opened the same debates.

Where should my team record why we made technical decisions so our AI agents follow them?

Use ArcRoom's arcroom decide to record the choice, the options weighed and the reason. A later decision can replace an earlier one, so the playbook keeps only the current one, and agents and people see it with its why. Decisions need someone to record them: ArcRoom doesn't pull them out of chat on its own.

Also asked as: Why do our AI agents keep reopening debates we already settled? · How do I keep a decision log that our AI agents can read? · Can AI agents see the reason behind a past team decision?

The work

arcroom decide records the choice, the options weighed and the reason.

ArcRoom keeps
  • Decision
  • Saved decision
The next agent gets

Decision: prices stored as integer cents.

Step by step

  1. arcroom decide records the choice, the options weighed and the reason.
  2. A later decision can replace an earlier one, so the playbook keeps only the current one.
  3. Agents and people see the current decision and why.

What the agent sees

Decision: prices stored as integer cents.
Weighed: decimal, float, cents. Why: no rounding errors across currencies.
Decided by: Ankit · source: PR #212

Compared with today's tools

ADRs (docs/adr) in the repo

Write one short markdown file per decision with context and reasons, and link the folder from CLAUDE.md.

Setup
1 hour
Ongoing
~15 min per decision

ArcRoom

Every agent reads the team playbook before it works and writes to it when it finishes. Nothing to update by hand.

Setup
2 min per person (npx arcroom init)
Ongoing
None

ADRs are the better long-term record for people; agents read them only when told to, while ArcRoom puts the matching decision in front of the prompt.

Where it stops

Decisions need someone to record them. ArcRoom doesn't pull them out of chat on its own.

Try it in your project

Works with the agents your team already uses, and any agent over MCP or the HTTP API.

More in small teams