Decision guide
What is a decision record?
A decision record, often called an ADR, captures the problem, options, chosen path, and consequences. It tells future humans and agents why the project moved in a specific direction.
What a decision includes
Context
The pressure or problem that forced a decision: product goal, technical constraint, risk, or tradeoff.
Options
The reasonable paths considered, including why each one might work or fail.
Decision
The selected path and the reason it fits the product, team, and architecture right now.
Consequences
The positive and negative effects the team accepts by choosing this path.
Why Amistio chose ADRs
Agents can edit code quickly, but speed is not the same as direction. ADRs slow down the decision point so the team can review the why before implementation. That matters when local runners execute approved work from the repository.
In Amistio, a prompt should not carry hidden architecture decisions. The decision belongs in an ADR so it can be reviewed, searched, and changed intentionally.
How ADRs protect future work
- They stop agents from re-litigating settled architecture every run.
- They make rejected options visible, which prevents accidental backtracking.
- They give plans and prompts a stable decision anchor.
- They create an audit trail for product and architecture changes.