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?
arcroom decide records the choice, the options weighed and the reason.
- Decision
- Saved decision
Decision: prices stored as integer cents.
Step by step
- arcroom decide records the choice, the options weighed and the reason.
- A later decision can replace an earlier one, so the playbook keeps only the current one.
- 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 #212Compared 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.