mirror of
https://github.com/zoriya/v10.git
synced 2026-08-10 16:09:18 +00:00
83 lines
1.9 KiB
Markdown
83 lines
1.9 KiB
Markdown
# Design Docs
|
|
|
|
Decisions you own — documented for posterity.
|
|
|
|
## What Belongs Here
|
|
|
|
Design Docs are **decisions you own**. Write one when:
|
|
|
|
- Making architectural decisions in your area
|
|
- Choosing between implementation approaches
|
|
- Introducing design patterns others will follow
|
|
- Documenting internal APIs or component specs
|
|
|
|
## When to Use RFC Instead
|
|
|
|
Use an RFC (`rfc/`) when:
|
|
|
|
- Changes public API surface
|
|
- Affects product direction
|
|
- Affects user-facing developer experience
|
|
- Significant changes to core architecture
|
|
- Hard to reverse once shipped
|
|
|
|
**Rule of thumb:** If you need someone else's approval, it's an RFC. If you're documenting your own decision, it's a Design Doc.
|
|
|
|
## Format
|
|
|
|
```markdown
|
|
---
|
|
status: decided
|
|
date: 2025-01-27
|
|
---
|
|
|
|
# Title
|
|
|
|
## Decision
|
|
|
|
What you decided. Be direct.
|
|
|
|
## Context
|
|
|
|
Why this came up. What problem triggered the decision.
|
|
|
|
## Alternatives Considered
|
|
|
|
- **Option A** — Why not chosen
|
|
- **Option B** — Why not chosen
|
|
|
|
## Rationale
|
|
|
|
Why this choice wins. Keep concise.
|
|
```
|
|
|
|
## Status Values
|
|
|
|
| Status | Meaning |
|
|
|--------|---------|
|
|
| `draft` | Thinking through it, not final |
|
|
| `decided` | Decision made, documented |
|
|
| `implemented` | Built and shipped — kept for rationale |
|
|
| `superseded` | Replaced by another design doc |
|
|
|
|
## Archive
|
|
|
|
`archive/` contains design docs for fully implemented features where the "what" is now captured by the code itself. These docs are preserved for reference but are no longer actively maintained. Docs with high "why" value (decisions, rationale, alternatives) stay in the main directory with `status: implemented`.
|
|
|
|
## File Naming
|
|
|
|
Use lowercase with hyphens:
|
|
|
|
```
|
|
queue-design.md
|
|
hook-naming.md
|
|
skin-theming.md
|
|
```
|
|
|
|
## See Also
|
|
|
|
- [Decisions](/internal/decisions/README.md) — ADR-style single-decision records
|
|
- [RFCs](/rfc/README.md) — Proposals needing buy-in
|
|
- [Plans](/.claude/plans/README.md) — Implementation details
|
|
- [CLAUDE.md](/CLAUDE.md#design-documents) — How these relate
|