Dmitry DementievandClaude Opus 4.8
6f9de57b0c
- Зачем:
- гравитация скилла тянула к «выдать артефакт»; управляющие документы
раздувались деталями реализации (диагностировано на живом тесте — ADR
с инлайном SQL).
- Что:
- gate/stop: «готово» = общее понимание + рекомендованное направление,
записанное минимально-достаточно, а не «артефакт произведён»; определение
в одном месте (stop_condition), gate на него ссылается.
- core_rules: минимально-достаточный артефакт + барьер высоты (без инлайна
исполняемых артефактов) + single source of truth; приоритет над
конвенциями репозитория.
- шаг 2: артефакт(ы) выбираются ПОСЛЕ понимания, набором по жанрам.
- adr.md/spec.md: Lifetime test → Scope test (ADR↔spec по охвату, не сроку);
detailed plan — transient и вне scope скилла.
- description + README: формулировки-цели ведут пониманием, не артефактом.
- Проверка:
- grep: старый framing (lifetime/transient) убран; cross-ref Scope test
сходится; определение «готово» не дублируется; витрина не artifact-first.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
51 lines
2.3 KiB
Markdown
51 lines
2.3 KiB
Markdown
# ADR — Architectural Decision Record
|
|
|
|
ADRs live in `docs/adr/` with sequential numbering: `0001-slug.md`,
|
|
`0002-slug.md`, etc. Create `docs/adr/` lazily — only when the first ADR is
|
|
needed. To number a new one, scan `docs/adr/` for the highest number and add one.
|
|
|
|
## When to offer an ADR
|
|
|
|
Offer one only when **all three** are true:
|
|
|
|
1. **Hard to reverse** — the cost of changing your mind later is meaningful.
|
|
2. **Surprising without context** — a future reader will look at the code and
|
|
wonder "why on earth did they do it this way?"
|
|
3. **The result of a real trade-off** — there were genuine alternatives and one
|
|
was picked for specific reasons.
|
|
|
|
If any of the three is missing, skip it. Easy to reverse → you'll just reverse
|
|
it. Not surprising → nobody will wonder. No real alternative → nothing to record
|
|
beyond "we did the obvious thing". Do not create an ADR for every small choice.
|
|
|
|
**Scope test (ADR vs spec).** Both an ADR and a spec are durable records, so the
|
|
split isn't lifetime — it's scope. A spec captures the shape of *one piece of
|
|
work* (what we're building and why); an ADR captures a single decision that is
|
|
*cross-cutting* — it matters beyond that one piece of work, and a future reader
|
|
elsewhere will need its rationale. So record a decision in an ADR only when it
|
|
applies beyond the scope of the spec that introduced it. Decisions local to the
|
|
current work belong in the spec's "Decisions and rejected alternatives" section,
|
|
not here. (The transient, stale-able document is the detailed implementation
|
|
plan — a separate artifact, not produced by this skill.)
|
|
|
|
## Template
|
|
|
|
```markdown
|
|
# {Short title of the decision}
|
|
|
|
{1-3 sentences: what's the context, what we decided, and why.}
|
|
```
|
|
|
|
That's it. An ADR can be a single paragraph. The value is recording *that* a
|
|
decision was made and *why* — not in filling out sections.
|
|
|
|
## Optional sections
|
|
|
|
Add these only when they earn their place (most ADRs won't need them):
|
|
|
|
- **Status** frontmatter (`proposed | accepted | deprecated | superseded by
|
|
ADR-NNNN`) — useful when decisions get revisited.
|
|
- **Considered options** — only when the rejected alternatives are worth
|
|
remembering (otherwise someone re-proposes them in six months).
|
|
- **Consequences** — only when non-obvious downstream effects need calling out.
|