refactor(brainstorm-with-docs): понимание ведёт, артефакт — запись
- Зачем:
- гравитация скилла тянула к «выдать артефакт»; управляющие документы
раздувались деталями реализации (диагностировано на живом тесте — 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>
This commit is contained in:
1 parent
14adf77424
commit
6f9de57b0c
4 files changed
+48
-22
No files matched your search
@@ -18,11 +18,15 @@ 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.
|
||||
|
||||
**Lifetime test (ADR vs spec).** A spec is transient — it describes what's being
|
||||
built now and goes stale once the work is done. An ADR is durable — it outlives
|
||||
the spec. So record a decision in an ADR only when it stays relevant *after* the
|
||||
spec that introduced it is obsolete. Decisions local to the current work belong
|
||||
in the spec's "Decisions and rejected alternatives" section, not here.
|
||||
**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
|
||||
|
||||
|
||||
@@ -3,8 +3,9 @@
|
||||
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.
|
||||
Use the minimum-sufficient version: the smallest form that fully preserves the
|
||||
understanding, and no smaller. Drop sections that add nothing for this particular
|
||||
problem — an empty section is noise.
|
||||
|
||||
## Template
|
||||
|
||||
@@ -57,8 +58,9 @@ in the second.
|
||||
|
||||
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`).
|
||||
durable, surprising, the result of a real trade-off, and matters beyond the scope
|
||||
of this work — cross-cutting, relevant to readers elsewhere (see the scope 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`.
|
||||
Reference in new issue
Block a user