write-tech-spec

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 до техспеки — план привязывается к согласованному поведению. Реализация слишком неопределённа → сначала сквозной прототип, потом техспека по итогам.

Исследование до написания

Прочитать продуктовую спеку (если есть), осмотреть релевантный код, определить ключевые файлы, типы, потоки данных и границы владения. Не гадать об актуальной архитектуре, когда код можно открыть и посмотреть.

Структура

Обязательные секции:

1. Context — что строим, как сейчас работает изменяемая область, ключевые файлы со ссылками на строки. Объединяет «проблему», «текущее состояние» и «релевантный код» в одну заземлённую секцию. Примеры ссылок:

   • src/workspace/mod.rs:42 — точка входа пользовательского сценария;
   • src/workspace/workspace.rs (120–220) — состояние и обработка событий, которые, вероятно, изменятся.

   За пользовательским поведением отсылать к PRODUCT.md, не пересказывать его.

2. Proposed changes — план реализации: какие модули меняются, какие типы/API/состояние вводятся, поток данных, границы владения, чем дизайн следует существующим паттернам репозитория. Где разумных путей больше одного — явно назвать trade-off'ы.

3. 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