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>
2.3 KiB
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:
- Hard to reverse — the cost of changing your mind later is meaningful.
- Surprising without context — a future reader will look at the code and wonder "why on earth did they do it this way?"
- 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
# {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.