mirror of
https://github.com/zoriya/v10.git
synced 2026-08-16 02:45:09 +00:00
68 lines
2.6 KiB
Markdown
68 lines
2.6 KiB
Markdown
# Internal design records
|
|
|
|
These documents preserve architecture, constraints, and rationale that code and tests cannot explain by themselves. Treat implementation and tests as the source of current behavior.
|
|
|
|
## Choose the smallest durable record
|
|
|
|
- `internal/design/<area>/`: architecture, subsystem, or feature design owned by the author.
|
|
- `internal/decisions/`: one tactical choice and its tradeoffs.
|
|
- `rfc/`: a proposal requiring wider approval, especially public API or hard-to-reverse product direction.
|
|
- `.agents/plans/`: temporary implementation notes; delete before merge or extract durable rationale here.
|
|
|
|
Skip a record for ordinary implementation detail, inventories, status logs, or information already clear from source and tests.
|
|
|
|
## Layout
|
|
|
|
| Area | Contents |
|
|
| --- | --- |
|
|
| `element/` | Custom-element architecture |
|
|
| `i18n/` | Locale and translation architecture |
|
|
| `media/` | Media model architecture |
|
|
| `site/` | Documentation-site decisions |
|
|
| `spf/` | Streaming framework architecture, conventions, feature registry, and use-case compositions |
|
|
| `ui/` | Component and interaction designs |
|
|
|
|
Put new records in an area directory. Add a new area only when at least two durable records are likely; otherwise use the nearest existing area.
|
|
|
|
## Status
|
|
|
|
| Status | Meaning |
|
|
| --- | --- |
|
|
| `draft` | Proposed or still under active design |
|
|
| `decided` | Choice made; implementation may follow |
|
|
| `active` | Living convention, index, or registry maintained with the code |
|
|
| `partial` | Registry feature or use case is partly implemented |
|
|
| `implemented` | Shipped; retained for rationale and stable contracts |
|
|
| `superseded` | Replaced; link the successor |
|
|
| `reference` | Prior art or research, not a status claim |
|
|
|
|
## Minimal format
|
|
|
|
```markdown
|
|
---
|
|
status: decided
|
|
date: YYYY-MM-DD
|
|
---
|
|
|
|
# Title
|
|
|
|
## Decision
|
|
|
|
## Context
|
|
|
|
## Alternatives considered
|
|
|
|
## Rationale
|
|
```
|
|
|
|
Use a different structure for a living reference or registry, but keep frontmatter and make the document's authority clear.
|
|
|
|
## Maintenance
|
|
|
|
- Link current source and tests; do not copy APIs, schemas, or file inventories.
|
|
- When implementation lands, collapse the record to durable rationale, constraints, consequences, and source pointers; remove speculative mechanics and current-behavior inventories.
|
|
- When a record becomes wrong, update it, mark it superseded with a successor, or delete it if no rationale remains.
|
|
- Keep implemented records only when their constraints, alternatives, or tradeoffs still help future changes.
|
|
|
|
Use `write-design-doc` for a design or decision record and `write-rfc` for wider proposals.
|