# 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 →](../../where-to-use-fly/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

- [Releases →](../releases/) - Decision Records appear on every release page
- [Runtime Environments →](../runtime-environments/) - See what's deployed where