How the architect creates Architecture Decision Records — capturing the context, options, and rationale behind design decisions so future agents understand WHY, not just WHAT
Agents don't have persistent memory across sessions. An architect who designs a pattern today won't remember why next week. An engineer who encounters the pattern will ask "why not the simpler approach?"
ADRs answer that question before it's asked.
You DON'T need an ADR for:
# ADR-{number}: {title}
## Status
{Proposed | Accepted | Deprecated | Superseded by ADR-{number}}
## Context
{What is the situation? What forces are at play? What constraints exist?
Be specific to the fleet — mention which agents, tools, or systems are affected.}
## Decision
{What we decided and WHY.}
## Options Considered
### Option A: {name}
- Pros: {list}
- Cons: {list}
- Fit for fleet: {how well this works in the multi-agent context}
### Option B: {name}
- Pros: {list}
- Cons: {list}
- Fit for fleet: {assessment}
## Consequences
### Positive
- {what gets better}
### Negative
- {what gets worse or constrained}
### Neutral
- {side effects that are neither good nor bad}
## Notes
{Any additional context, links to fleet-elevation docs, related ADRs}
Before finalizing an ADR:
docs/adr/ directory001-use-fastmcp-for-tools.md