ddadmin
50640d8cb5
- Зачем:
- нужен ручной скилл для брейнсторма и дизайна, который удерживает
словарь смыслов (CONTEXT.md) и лёгкие ADR, активно прожаривает план
и не сваливается в реализацию.
- Что:
- SKILL.md: процесс (контекст → классификация → декомпозиция →
грилл → синтез опций → подтверждение → артефакт), единый HARD-GATE
«исследуй, но не меняй состояние» с поправкой на auto mode.
- artifacts/: шаблоны spec, research-note, adr, runbook, prd, context
(по файлу на тип для progressive disclosure).
- README.md с MIT-атрибуцией grill-with-docs (Pocock) и brainstorming
(obra/superpowers); шов для будущей фазы дивергенции в шаге 5.
- frontmatter переносим: Claude читает все поля, Codex — name+description.
- Проверка:
- python3 yaml-парс frontmatter; markdown-ссылки на artifacts/ резолвятся.
1.6 KiB
1.6 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.
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.