| name | write-tech-spec |
| description | Написание TECH.md для значимой фичи после исследования текущей кодовой базы и ограничений реализации. Использовать, когда нужна техническая спека, план реализации или архитектурный документ, привязанный к продуктовой спеке. |
| vibeVersion | 1.1.0 |
write-tech-spec
Написать TECH.md для значимой фичи.
Суть
Техспека переводит продуктовое намерение в план реализации, который вписывается в существующую кодовую базу, документирует архитектурные решения и делает работу проще для агентов-исполнителей и понятнее для ревьюеров.
Путь: specs/<id>/TECH.md. <id> совпадает с id соседнего PRODUCT.md, если тот существует; правила выбора id и работы с трекером — в скилле spec-driven-implementation.
Когда использовать
Реализация затрагивает несколько модулей, есть осмысленные архитектурные trade-off'ы, или ревьюерам полезнее увидеть план до/вместе с кодом. Для чисто UI-правок и прямолинейных фиксов техспека обычно не нужна.
Предпочтительно иметь PRODUCT.md до техспеки — план привязывается к согласованному поведению. Реализация слишком неопределённа → сначала сквозной прототип, потом техспека по итогам.
Исследование до написания
Прочитать продуктовую спеку (если есть), осмотреть релевантный код, определить ключевые файлы, типы, потоки данных и границы владения. Не гадать об актуальной архитектуре, когда код можно открыть и посмотреть.
Структура
Обязательные секции:
-
Context — что строим, как сейчас работает изменяемая область, ключевые файлы со ссылками на строки. Объединяет «проблему», «текущее состояние» и «релевантный код» в одну заземлённую секцию. Примеры ссылок:
src/workspace/mod.rs:42 — точка входа пользовательского сценария;src/workspace/workspace.rs (120–220) — состояние и обработка событий, которые, вероятно, изменятся.
За пользовательским поведением отсылать к PRODUCT.md, не пересказывать его.
-
Proposed changes — план реализации: какие модули меняются, какие типы/API/состояние вводятся, поток данных, границы владения, чем дизайн следует существующим паттернам репозитория. Где разумных путей больше одного — явно назвать trade-off'ы.
-
Testing and validation — как реализация будет проверена против продуктового поведения. Секция владеет всем доказательством работоспособности: unit, интеграционные, ручные шаги, скриншоты, видео. Ссылаться на нумерованные инварианты Behavior из PRODUCT.md напрямую, не пересказывая: каждый важный инвариант → конкретный тест или шаг проверки. Валидация живёт здесь — в PRODUCT.md секции Validation сознательно нет.
Опциональные секции — только когда добавляют сигнал; пустую секцию не писать вовсе (никаких «None»-заглушек):
- End-to-end flow — только если трасса через систему говорит то, чего не видно из списка изменений.
- Diagram — Mermaid, только когда визуал объяснит дизайн быстрее прозы (поток данных, переходы состояний, sequence через слои). Одна-две прицельных диаграммы лучше декоративных.
- Risks and mitigations — когда есть реальные режимы отказа, регрессии, миграции или опасности раскатки.
- Parallelization — когда работу можно чисто разделить между агентами и это разделение неочевидно.
- Follow-ups — когда есть отложенная уборка или будущая работа, которую стоит назвать.
Эвристика длины
- Изменение одного файла с ясным подходом: техспеку пропустить или уложить в ~40 строк.
- Мультимодульное изменение с неоднозначностью: ~80–150 строк.
- Крупное сквозное или архитектурно новое: длиннее — нормально, если каждая секция отрабатывает своё место.
Если Context и Proposed changes описывают одни и те же файлы и состояние с разных сторон — схлопнуть.
Принципы письма
- Заземлять план в реальной структуре и паттернах кодовой базы.
- Конкретные указания по реализации вместо общеархитектурного языка.
- Объяснять, почему предложенный дизайн подходит этому репозиторию.
- За поведением — в
PRODUCT.md, не пересказывать.
- Секция либо отрабатывает место, либо удаляется.
Актуальность спеки
Поддержание TECH.md синхронным с реализацией (тот же PR, обновление при смене границ модулей/последовательности/рисков/валидации) — по каноническим правилам скилла implement-specs.
Связанные скиллы
implement-specs, write-product-spec, spec-driven-implementation
