52 lines
1.7 KiB
Markdown
52 lines
1.7 KiB
Markdown
---
|
|
name: documentation-and-adrs
|
|
description: Use when documenting architectural decisions, drafting ADRs (Architecture Decision Records), or writing technical specifications and system documentation.
|
|
---
|
|
|
|
# Architecture Decision Records (ADRs) & Technical Documentation
|
|
|
|
## Purpose
|
|
Produce concise, actionable, and structured architectural documentation and ADRs that capture the context, options considered, and tradeoffs made.
|
|
|
|
## ADR Standard Structure (MADR Format)
|
|
|
|
```markdown
|
|
# [Short title of solved problem and decision]
|
|
|
|
* **Status:** proposed | accepted | rejected | deprecated | superseded
|
|
* **Deciders:** [List of stakeholders/engineers]
|
|
* **Date:** YYYY-MM-DD
|
|
|
|
## Context and Problem Statement
|
|
What problem are we solving? What are the constraints, requirements, and background context?
|
|
|
|
## Decision Drivers
|
|
* Driver 1 (e.g. performance under 50ms latency)
|
|
* Driver 2 (e.g. zero external infrastructure dependencies)
|
|
* Driver 3 (e.g. strict backwards compatibility)
|
|
|
|
## Considered Options
|
|
1. Option A — [Short description]
|
|
2. Option B — [Short description]
|
|
3. Option C — [Short description]
|
|
|
|
## Decision Outcome
|
|
Chosen option: "Option A", because [justification linking to drivers].
|
|
|
|
### Positive Consequences
|
|
* Clear benefit 1
|
|
* Clear benefit 2
|
|
|
|
### Negative Consequences / Tradeoffs
|
|
* Accepted limitation 1
|
|
* Migration cost or operational overhead
|
|
|
|
## Pros and Cons of Options
|
|
[Brief comparison table or bullet breakdown]
|
|
```
|
|
|
|
## Documentation Principles
|
|
1. **One Home per Fact:** Do not duplicate invariants across multiple files.
|
|
2. **Focus on "Why" and "Tradeoffs":** Code shows *how*; documentation must explain *why* this choice was made over alternatives.
|
|
3. **No Fluff / Slop:** Direct, concise language. Omit generic platitudes.
|