Decision Records

Overview

Build with your team’s decisions in every coding-agent session, and see what shipped and why on every release.

A Decision Record is a statement of what your team has decided to build, and why – automatically captured from your developer-agent conversations and recorded when you release.

Without them, intent evaporates: a developer says “use Postgres, not Redis” in chat, the agent applies it, the conversation closes, and the next session starts from zero. With Decision Records, that intent compounds.

How Decision Records Are Captured

Decision Records are collected from your developer-agent conversations as you work – the Fly App → captures these in the background. When a release is finalized, Fly reviews the conversations that led to it and produces the Decision Records for that release.

Each Decision Record on a release reflects one of three lifecycle events:

  • Created – the team commits to a new direction (“every HTTP error uses the shared envelope”).
  • Updated – the team changes its mind (“actually, route this through the queue, not inline”).
  • Removed – the topic no longer applies and the decision is retired.

How Decision Records Are Used

Agent context for better development

Decisions the team has already made show up in every future agent session for the same repository. Your agent reasons inside them on every prompt – it knows you picked Postgres, it knows your error envelope convention, it knows what’s been decided and doesn’t relitigate.

You ship faster and your team stays aligned – your agent always has the full context of what your team has decided.

Release tracking

Every release page in Fly Web shows the Decision Records added, updated, or removed in that release – alongside the commits, PRs, and artifacts. Each record carries who made the decision and when, so a release now answers what shipped, why, and who decided it.

The release summary also references the decisions when they shaped what was built.

Next Steps