Шаблон техспеки для инженеров (2026)
В инженерной культуре Google есть правило: до первой строчки кода для любой нетривиальной задачи пишется design doc. Не 40-страничный монумент, а обычно 5-12 страниц, с двумя ревьюерами и комментариями на полях. Команда Engineering Practices из Google публично называла это одним из самых дешёвых рычагов качества в компании.
Большинство команд вне Google либо пропускают этот шаг, либо прикручивают шаблон в Confluence к существующему процессу и смотрят, как он атрофируется. Шаблон ниже — тот, который реально выживает при встрече с уставшим ревьюером в 16:45 в четверг. Это тот момент, когда спека живёт или умирает.
{/* truncate */}
В чём проблема
Инженерные команды пишут спеки по трём причинам: думать ясно, договориться, оставить след. Большинство шаблонов оптимизировано под третье. Поэтому они и умирают. Никто не читает спеку, написанную как артефакт compliance.
Автор должен потратить на спеку 2-6 часов, ревьюер — 20-40 минут. Если одна из сторон тратит больше, проблема в шаблоне, а не в людях. Stack Overflow Developer Survey 2024 поставил документацию на #2 место среди productivity killers после неясных требований — "нет документации" и "плохая документация" шли ноздря в ноздрю. Плохие шаблоны — это то, как хорошие команды получают плохую документацию.
Что реально должно быть в tech spec 2026
Девять разделов. Не больше, не меньше. Всё остальное — в приложение или в отдельный документ.
1. Problem statement
Один абзац. Кого это затрагивает, что сломано, как мы об этом знаем. Никаких намёков на решение.
Плохо: "Нужно отрефакторить auth-сервис."
Хорошо: "p99 session-refresh в auth-сервисе вырос с 80 мс до 340 мс за последние 6 недель, коррелирует с пересечением отметки 120k MAU. На прошлой неделе два тикета в саппорте из-за refresh timeout."
Если вы не можете указать на метрику или наблюдение — спека не готова.
2. Scope и non-goals
Bullet-лист: что входит и — что важнее — что не входит. Non-goals — первое, что ревьюеры ищут grep'ом. Это то, что защищает от scope creep на PR review через два месяца.
3. Current state
Как всё работает сегодня. Три предложения плюс одна диаграмма, если система не очевидна. Ссылки на существующую документацию, без пересказов.
4. Proposed design
Сердце спеки. Описывайте дизайн в том порядке, в котором объяснили бы его новичку у доски: сначала data flow, потом сложное место, потом edge cases. Sequence diagrams — когда поведение зависит от порядка.
5. Alternatives considered
Минимум две альтернативы, каждая с абзацем — почему отклонена. Именно здесь вы зарабатываете доверие ревьюера. Если у вас одна альтернатива — это не спека для review, это предложение.
6. Trade-offs
Явно назовите цену выбранного дизайна. Производительность? Операционная сложность? Vendor lock-in? Спека, утверждающая "нет trade-offs", — это будущая проблема на ревью.
7. Rollout plan
Имя feature flag, шаги миграции, путь отката, добавленная наблюдаемость. Для всего, что трогает данные — backfill plan и как вы поймёте, что миграция частично сломалась посередине.
8. Success metrics
На какие числа мы смотрим через 30 дней, чтобы понять — получилось. Если не можете описать каждую метрику одной строкой, вы пока не понимаете, что строите.
9. Open questions
Нумерованный список. Ревьюеры отвечают inline. Когда все закрыты — спека готова к merge.
Спека идёт от проблемы к измерению. Пропустите любую из этих коробок — документ превращается в театр.
Заполненный пример: реальный паттерн
Сжатая версия реальной спеки, которую я ревьюил для финтех-команды в прошлом квартале (детали клиента убраны). Отгрузилась. Полный документ — 7 страниц.
| Раздел | Содержание (выжимка) |
|---|---|
| Problem | Реконсиляционный job идёт 90 минут, блокирует утренние деплои, 3 пропущенных SLA в прошлом месяце |
| Scope | Переносим reconciliation на streaming; out of scope: новые отчёты, UI |
| Current state | Часовой cron, читает 12M строк, пишет в OLAP, owner — Payments team |
| Proposed design | Kafka topic от CDC; Flink job с окнами 5 минут; тот же OLAP target |
| Alternatives | (a) Распилить cron на 4 параллельных — отклонено, не решает latency. (b) Managed DW — отклонено, $14k/мес |
| Trade-offs | Операционно: новый Flink-деплой, требует обучения on-call платформенной команды |
| Rollout | Shadow mode 2 недели → dual-write 1 неделя → cutover с 24ч rollback-окном |
| Success | p99 reconciliation lag < 10 мин, ноль блокировок утренних деплоев 30 дней |
| Open questions | 1) Кто on-call для Flink? 2) Retention для Kafka-топика? |
Обратите внимание, чего нет: ни ROI-расчёта, ни био команды, ни market analysis. Спека отвечает: что, зачем, как, какой ценой, как поймём, что сработало. Остальное — cargo-cult из product-requirement docs, ему не место в инженерной спеке.
Типичные ошибки
| Ошибка | Почему это больно | Как чинить |
|---|---|---|
| Solution-first спека (дизайн раньше проблемы) | Ревьюер не может оценить дизайн, не зная, что вы оптимизируете | Сначала проблема, всегда |
| Нет alternatives | Выглядит так, будто автор не думал | Минимум две альтернативы, даже слабые |
| Метрики, которые невозможно измерить | Критерии успеха становятся произвольными | Каждая метрика должна цепляться за существующий дашборд или создаваемый в этой же спеке |
| Мутный rollout ("задеплоим и будем наблюдать") | 70% инцидентов — из-за просчётов rollout | Конкретные стадии, имена флагов, триггеры отката |
| Спека длиннее 12 страниц | Ревьюеры проскальзывают после 7-й страницы | Глубокие детали — в appendix, основной текст держите коротким |
| Нет имени автора и даты | Сломанный audit trail через 18 месяцев | Первая строка документа |
Ошибка "solution-first" — самая частая. Когда я ревьюил 40 спек из портфеля B2B-команд в 2025 году, 31 из 40 начиналась с решения, а проблема была footnote'ом. У каждой из них был scope-спор на первом круге review.
Чеклист (копируйте и используйте)
- Problem statement с метрикой или конкретным наблюдением
- Scope И non-goals явно выписаны
- Минимум 2 отклонённые альтернативы с причинами
- Trade-offs названы, а не спрятаны
- Rollout включает откат и наблюдаемость
- Метрики успеха измеримы с существующих или создаваемых дашбордов
- Open questions пронумерованы и назначены
- Меньше 12 страниц, или глубина убрана в appendix
- В хедере названы минимум 2 ревьюера
- Поле Approved-by в начале, пустое до подписи
Как понять, что процесс спек работает
Три сигнала, мониторинг квартальный. Два из них напрямую цепляются за данные delivery — те, которые PanDev Metrics считает автоматически из timestamps branch→deploy. Третий берётся из инструмента спек.
- Lead time от spec до первого коммита. Окно от merge спеки до первого commit в соответствующей ветке. У здоровой команды — 2-5 рабочих дней. Больше — значит спека реально не выровняла команду; меньше — спека обычно пишется после кода.
- Количество итераций review. Сколько раундов комментариев до approval. Команды с калиброванным процессом живут на 2-3 раундах; 5+ раундов — значит либо шаблон не тот, либо стандарт у авторов и ревьюеров разный.
- Корреляция инцидентов post-ship. Из инцидентов за квартал — сколько восходят к фиче со слабой или пропущенной спекой. Если число стабильно ненулевое — чинить надо сам процесс спек.
Команды с PanDev Metrics, подключённым к Git-провайдеру, получают сигнал по lead time автоматически через 4-стадийный разбор — мы писали про механику в гайде по lead time. Корреляция инцидентов потребует немного тегов в incident tool, но это метрика с самым высоким сигналом из трёх.
Когда шаблон не подходит
Три случая, где стоит взять другое:
- Research spikes. Таймбокс на 3 дня для прототипа не заслуживает документа из 9 разделов. Пишите "spike report" на одну страницу.
- Emergency fixes. Хотфикс — сам себе спека. Пишите post-mortem.
- Архитектурные изменения через всю компанию. 12-страничный шаблон превращается в 60-страничный RFC. Используйте внутренний architecture-review, не это.
Всё остальное — новые сервисы, значимые рефакторинги, изменения API с downstream-потребителями, всё, что трогает миграцию данных — ложится в шаблон. Если сомневаетесь, нужен ли спеке шаблон, сам факт сомнения означает "да, нужен".
Исследование DevEx-команды Microsoft (Forsgren, Storey et al., 2024) показало: команды с калиброванной практикой design-doc имели на 17% меньший change failure rate, чем команды без неё, при контроле за частотой деплоев. Это один из крупнейших эффектов в их датасете — и получен от практики, которая почти ничего не стоит внедрить.
Читать дальше
- DORA Metrics: полный гайд для инженерных лидеров (2026)
- Code Review чеклист: 11 правил, которые режут время ревью вдвое
- Как измерять Lead Time: разбор на 4 стадии
Спека — не deliverable. Deliverable — общее понимание в головах ревьюеров. Если ваш шаблон оптимизируется подо что-то кроме этого понимания, перепишите шаблон.