> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plannotator.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR vs RFC vs Technical Specification

> Choose an ADR, software RFC, or technical specification by the decision, discussion, authority, lifecycle, and maintenance record you need.

Use an ADR to preserve one significant architectural choice and its consequences. Use an RFC to circulate a proposal that needs broad discussion before adoption. Use a technical specification to define behavior and design that implementers and maintainers need to keep true.

## The decision table

| Question             | ADR                                                  | RFC                                                          | Technical specification                                     |
| -------------------- | ---------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------- |
| Main job             | Record a choice                                      | Propose and discuss a direction                              | Define required behavior and design                         |
| Typical status       | Proposed, accepted, rejected, deprecated, superseded | Draft, in discussion, accepted, rejected, withdrawn          | Draft, accepted, implemented, superseded                    |
| Best scope           | One architecturally significant decision             | A proposal with organization-wide or cross-team consequences | One system, feature, protocol, or durable behavior contract |
| Alternatives         | Records the important considered options             | Invites comparison and disagreement                          | May link ADRs for choices rather than repeat all debate     |
| After acceptance     | Usually remains historical decision memory           | Produces follow-up decisions, specifications, and plans      | Stays current or is explicitly superseded                   |
| Implementation tasks | Link a plan                                          | Link a plan after decision                                   | Link or derive a plan; do not make the spec a task log      |

## Use an ADR for “why this choice?”

An ADR captures the context, decision, and consequences of one significant design choice. The [ADR community](https://adr.github.io/) and [MADR](https://adr.github.io/madr/) provide established definitions and formats.

Example: “Use a time-bounded database lease for job claims.” The record explains why process locks fail, what alternatives were considered, and what monitoring becomes necessary.

Use the [ADR template](/templates/architecture-decision-record).

## Use an RFC for “should we adopt this proposal?”

An RFC is a discussion vehicle. It gives reviewers a concrete proposal, motivation, alternatives, compatibility effects, rollout, and open questions. An accepted RFC often produces ADRs for durable architecture choices and a specification for maintained behavior.

Example: “Introduce expiring anonymous share links.” Reviewers need to discuss security, user recovery, abuse, migration, and whether expiry is fixed or activity-based.

Use the [software RFC template](/templates/software-rfc).

## Use a technical specification for “what must remain true?”

A technical specification defines observable requirements, non-goals, design, interfaces, data, failure behavior, security, compatibility, rollout, and verification. It should be maintained when the system changes.

Example: “Expired and unknown share links return the same public response, and expired links do not read document content.” That statement can become a requirement with a corresponding integration proof.

Use the [technical specification template](/templates/technical-specification).

## A useful document chain

```text theme={null}
RFC proposal
  → accepted architecture choices in ADRs
  → maintained behavior in a technical specification
  → current implementation sequence in a coding plan
  → returned evidence in an agent handoff
```

Not every change needs the whole chain. A small internal choice may need only an ADR and a pull request. A broad proposal may need all five records. Use the smallest set that leaves no ambiguity about the current authority.

For shared discussion, [Workspaces](/workspaces/review-plans-and-technical-decisions) uses the same document workflow across plans, specifications, ADRs, RFCs, and handoffs without treating them as separate products.

*Reviewed July 18, 2026. Written and maintained by the Plannotator documentation team. Format guidance is based on primary ADR sources and common software proposal practice; the example chain is Plannotator's editorial recommendation.*