| name | spec-driven-implementation |
| description | Spec-first процесс для существенных фич — оркестратор: PRODUCT.md до реализации, TECH.md когда оправдан, реализация по утверждённым спекам. Использовать при старте значимой фичи, планировании агентной реализации или когда спеки нужно хранить в репозитории. |
spec-driven-implementation
Оркестратор spec-first процесса. Сам спеки не пишет — решает, нужны ли они, и ведёт по цепочке дочерних скиллов: write-product-spec → write-tech-spec → implement-specs.
Где живут спеки
specs/<id>/PRODUCT.md и specs/<id>/TECH.md, где <id> — номер тикета (PROJ-1234), GitHub issue с префиксом (gh-4567) или короткое kebab-case имя фичи.- В
specs/ напрямую — только id-каталоги. Без подпапок по именам инженеров и без свободных слагов рядом с тикетами.
- Тикет/issue — опциональны. Есть трекер и релевантного issue нет — создавать только если пользователь явно попросил; команда/проект/лейблы неочевидны — спросить, не угадывать.
- Спеки пишутся преимущественно агентами и коммитятся в репозиторий — чтобы их ревьюили и держали синхронными с кодом.
Когда спеки нужны
Решительно за спеки, когда изменение существенное:
- продуктовая или архитектурная неоднозначность;
- ожидаемый объём порядка 1k+ LOC;
- глубокие или сквозные изменения стека;
- рискованные изменения поведения, где регрессии дороги;
- качество работы агента заметно вырастет от более ясных входных данных.
Спеки обычно не нужны: мелкие локальные багфиксы, прямолинейные рефакторинги, узкие UI-правки без неоднозначности. Для чисто UI-изменений продуктовая спека часто полезна, а техническая — нет.
Процесс
- Решить, нужны ли спеки. Оценить размер, неоднозначность и риск. Если спеки не улучшат ни исполнение, ни ревью — пропустить их и сосредоточиться на верификации.
- Продуктовая спека. Скилл
write-product-spec → PRODUCT.md: проблема, желаемый пользовательский опыт, инварианты и edge cases. Есть UI — спросить про дизайн-мок до написания.
- Техническая спека — когда оправдана. Скилл
write-tech-spec, если реализация затрагивает несколько подсистем, важна архитектура/расширяемость, есть осмысленные trade-off'ы или ревьюерам полезнее план, чем сырой код. Допустимо писать TECH.md после сквозного прототипа, если так план точнее; не выдавливать преждевременную спеку из неопределённости.
- Реализация. Скилл
implement-specs — сборка фичи по утверждённым спекам. Там же канонические правила: «спеки и код в одном PR», поддержание спек актуальными, опциональные PROJECT_LOG.md / DECISIONS.md, верификация против спек.
Принципы
- Прагматизм превыше всего: спеки — для качества входных данных агентов, не ради церемонии.
- Продуктовые спеки — про поведение, без реализации; технические — про реализацию, заземлённую в паттернах текущей кодовой базы.
- Время ревью тратить на валидацию спек и поведения, а не на стилистические придирки к коду.
Связанные скиллы
write-product-spec, write-tech-spec, implement-specs
