What this template is for
An architecture decision record is not a design document. It is the audit trail of a single significant choice - what forced it, what alternatives were considered, what was chosen, and what the team agreed to live with as a consequence. ADRs answer the question every engineer eventually asks of a codebase: “why on earth did we do it this way?”
Storing ADRs in Jira gives them three properties they rarely have when they live in a wiki:
- They are append-only. A Jira ticket is naturally immutable in the way an ADR should be - you supersede, you don’t edit.
- They are linkable. Implementation epics, related ADRs, and superseded ADRs all become first-class issue links.
- They are searchable from the tool engineers already live in. No second login, no second search index.
When to use it
Use an ADR ticket whenever a decision will be hard or expensive to reverse, will be questioned later, or affects more than one team. Examples: choosing a message broker, picking a public-API style, deciding on a tenancy model, adopting (or dropping) a framework.
Do not create ADRs for routine choices that any senior engineer would make the same way. ADRs exist to record contested decisions and their reasoning.
Sub-task breakdown
The sub-tasks above turn an ADR from a one-shot document into a process: draft, review, decide, link to implementation, schedule a future check-in. STM Issue Templates can auto-create that sub-task set on every new ADR ticket via an On Create Issue Executor scoped to the ADR component or label. The 90-day review reminder, in particular, is the kind of sub-task that quietly disappears unless it is created automatically.
Fields to add to your Jira create screen
These are the fields a project admin should make sure exist on the Create Issue screen for this issue type (Project settings → Screens). Without these on the screen, reporters can't provide the information triage needs - and STM can't reference them either.
| Field | Example value | Required |
|---|---|---|
Summary | ADR-042 - Adopt Kafka over RabbitMQ for order events | Yes |
ADR Number (custom) | ADR-042 | Yes |
Status (custom) | Proposed / Accepted / Superseded / Deprecated | Yes |
Context (custom) | What forced the decision and why now | Yes |
Decision (custom) | We will use Kafka for all order-domain events | Yes |
Options Considered (custom) | Kafka, RabbitMQ, SNS+SQS, NATS | Yes |
Consequences (custom) | Positive, negative, and neutral outcomes | Yes |
Deciders (custom) | @alex.chen, @priya.patel, @platform-tl | No |
Supersedes | Link to prior ADR if applicable | No |
Component/s | orders, messaging | No |
Labels | adr, architecture | No |
Note on custom fields. STM currently supports up to 5 custom fields per template. You can add as many custom fields as you like to your Jira Create Issue screen - the 5-field limit only applies if you want STM to set or update those custom fields itself.
Sub-tasks STM creates automatically
Build an STM sub-task template containing the items below, then wire it to an On Create Issue Executor scoped to this issue type. Whenever a new issue of this type is created in the project, STM creates the full sub-task set in one step - with assignee, due date, and components inherited from the parent unless you override them.
- Draft ADR in the standard template (context, options, decision, consequences)
- Circulate to deciders and architecture reviewers for comment
- Hold the decision meeting and capture dissent in the ticket
- Mark Status = Accepted and link to the implementation epic
- Schedule a 90-day review reminder to confirm the decision still holds
Common questions
What is an architecture decision record (ADR)?
An ADR is a short, immutable document that captures one significant technical decision - the context that forced it, the options considered, the choice made, and the consequences. ADRs are numbered, append-only, and superseded rather than edited. Storing them as Jira tickets makes them searchable, linkable, and visible alongside the code they govern.
Why store ADRs in Jira instead of a wiki?
Wikis encourage editing in place, which destroys the decision history. Jira tickets are append-only by nature, link cleanly to epics and pull requests, and surface in search alongside the work the decision shaped. Teams that store ADRs in Jira tend to reference them more often because the tickets show up in the same tool engineers already use daily.
How do you number ADRs in Jira?
Use a dedicated custom field 'ADR Number' rather than the Jira issue key. ADR numbers are monotonic and human-friendly (ADR-001, ADR-042); Jira keys are project-scoped and change if you move projects. The ADR Number field becomes a stable identifier that you can reference from code comments and design docs.
Should ADR tickets have sub-tasks?
Yes - draft, circulate, decide, mark accepted, and schedule a 90-day review. STM Issue Templates can auto-create that sub-task set whenever a ticket is created in the ADR component, so the decision process is consistent and the 90-day review never gets forgotten. See [STM Issue Templates](/stm/) for the executor pattern.
Automate the sub-tasks with STM
STM Issue Templates saves the sub-task list above as a reusable template and creates them on every new issue of this type - via an Executor on issue creation, on status transition, or triggered manually from the issue's "Create bulk sub-tasks" menu. STM does not change the parent issue's create screen (that's a Jira project-settings job) but it removes the manual work of creating the sub-tasks every time.
Try STM on the Atlassian Marketplace ↗ See how STM templates are built →