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 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.

Review decisions from your coding agent

Ask your agent what the team has decided, and it lists the active decisions for the repository:

“Show me the decision records for this repo”

“What has the team decided about error handling?”

You see exactly what’s steering every session – handy before you start a feature, or when you suspect the agent is following something that’s gone stale.

Manage Decision Records

Fly manages your team’s decisions as you work – capturing them from your conversations and keeping them current. And when a decision no longer fits, you can remove it yourself by simply asking your coding agent.

Automatically, as you work

Decision Records are captured from your developer-agent conversations as you work – the Fly App → records them 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.

Remove decisions on demand

When a decision no longer applies, you can simply remove it by asking your coding agent:

“Remove the decision record about using Redis for caching”

“Delete the decision about the old API envelope format”

Not sure which one? List them first with “Show me the decision records for this repo”.

By removing a decision record, you and your team will no longer have it as context for your agent in future sessions.

Pause collection

To stop capturing new Decision Records, open the Fly App settings (gear icon in the tray header) and toggle off Capture decision records.

While collection is paused:

  • No new decisions are captured from your coding agent conversations.
  • Existing Decision Records stay available as agent context and on releases.
  • Sync continues: records from your team still arrive normally.

Toggle it back on whenever you’re ready to resume. Collection is enabled by default.

Next Steps