Creating ADRs
Use the ADR editor to document decisions with metadata, content sections, options analysis, and links to related diagrams and decisions.
The ADR editor provides a structured form for creating and editing Architecture Decision Records. Fields change based on the selected format, and changes are auto-saved with automatic markdown export.
Creating a New ADR
Core Fields
Every ADR has these fields.
| Field | Description |
|---|---|
| ID | Auto-generated in ADR-0001 format. Based on filename. |
| Title | Required. A short description of the decision. |
| Type | The ADR format (Nygard, Structurizr, MADR, Y-Statement) |
| Status | Current state (Draft, Proposed, Accepted, etc.) |
| Date | When the decision was made |
Metadata Fields
Content Fields
Content fields use markdown and appear based on the selected format.
MADR Options
For MADR format, document the options you considered.
Linking Content
| Link Type | Purpose | How to Add |
|---|---|---|
| Related Diagrams | Connect to architecture diagrams that illustrate the decision | Click Add related diagram, select a .diagram.json file |
| Related ADRs | Link to other decisions that relate to this one | Click Add related ADR, select an .adr.json file |
| References | Add external URLs to supporting documentation | Click Add reference, enter the full URL |
Auto-Save
The editor saves automatically.
Validation
The editor validates your input. Title is required for all formats. Invalid fields are highlighted. Save is blocked until validation passes.
Editor Tips
Use Markdown
Use markdown in content fields for formatting
Concise Titles
Keep titles concise but descriptive
Add Deciders
Add deciders for accountability
Consistent Tags
Use consistent tags across your ADRs
Link Diagrams
Link to diagrams that visualise the decision
Reference ADRs
Reference related ADRs to build a decision graph