| name | jb-adr |
| description | Use when the user mentions ADR, MADR, decision record, architectural decision, design decision, tech decision, or documenting architecture choices. |
MADR - Markdown Architectural Decision Records
Create structured ADRs to document important design decisions for coding projects.
Quick Start
- Create new ADR: Use template below in
docs/adr/
- Name format:
NNNN-title.md (e.g., 0001-use-postgres.md)
- Link from README: Add to ADR index
ADR Template (Minimal)
# Title
## Status
Proposed | Accepted | Deprecated | Superseded by [NNNN](./NNNN-new-decision.md)
## Context
What is the issue motivating this decision?
## Decision
What is the change being proposed?
## Consequences
What becomes easier or harder because of this change?
Full Template
For complex decisions, use the full template from references/full-template.md:
- Includes Options considered, Pros/Cons, Related decisions
- Load with:
read references/full-template.md
Naming Convention
- Use 4-digit numbering:
0001, 0002, ...
- Lowercase hyphenated titles
- Example:
0003-select-database.md
Best Practices
- One ADR per decision
- Write for future developers (explain why)
- Include pros/cons of options considered
- Link related ADRs
- Update status when superseded
File Location
Store in docs/adr/ or adr/ at project root.
