ddadmin
f24b342123
- Зачем:
- внешнее ревью выявило риск двойной записи решений (spec/ADR) и
терминологическую путаницу; правки документные, поведение не меняют.
- Что:
- adr.md и spec.md: добавлен lifetime-критерий ADR vs spec (ADR — для
решений, переживающих спеку; локальные остаются в спеке).
- spec.md: разведены Options considered (до выбора) и Decisions (после).
- SKILL.md: блок <validation> переименован в <self_review>, чтобы не
путать с секцией ## Validation в spec.md.
- README.md: честнее описано авто-срабатывание на Codex.
- SKILL.md: у SEAM зафиксирован TODO(F1) про строку дивергенции
(отложена ради чистого baseline на обкатке).
- Проверка:
- python3 yaml-парс frontmatter; нет висячих ссылок на <validation>.
1.8 KiB
Solution Design / Spec
Use for engineering, architecture, DevOps, integration, migration, or any non-product feature work where a direction has been chosen but not yet built.
Use the smallest version that preserves the useful thinking. Drop sections that add nothing for this particular problem — an empty section is noise.
Template
# Title
## Problem
## Context
## Goals
## Non-goals
## Current state
## Options considered
## Recommended approach
## Rationale
## Decisions and rejected alternatives
## Risks and mitigations
## Validation
## Documentation impact
## Open questions
Notes on key sections
Options considered vs Decisions. Keep these two sections doing different jobs so the rejected options aren't written twice. Options considered is the landscape before the choice — the candidates and their trade-offs as they stood. Decisions and rejected alternatives is the outcome after the choice — what was picked and why each alternative was rejected. Frame in the first, judge in the second.
Decisions and rejected alternatives is the highest-value section. Capture:
- accepted decisions and the reason behind each
- rejected alternatives and why they were rejected
- subtle constraints and important defaults
- sequencing decisions
- assumptions future agents must not silently re-derive
Do not turn this section into an ADR dump. Keep decisions that are local to this
work here; promote a decision to its own ADR (artifacts/adr.md) only when it is
durable, surprising, the result of a real trade-off, and will still matter after
this spec is obsolete (see the lifetime test in artifacts/adr.md).
Validation describes how we will know the implementation is correct — tests,
checks, acceptance criteria. It belongs here, not in CONTEXT.md.