Спецификация («спека»)

6 июля 2026 · ~13 мин чтения

Спецификация («спека»)

Спецификация — документ, который до начала работы точно описывает, что должно получиться и по каким критериям проверять, что получилось именно оно. В разговорной речи разработчиков — «спека». Ключевое слово — «до»: спека пишется раньше, чем работа сделана, и служит контрактом между тем, кто придумал, и тем, кто делает.

История

Спецификация старше софта примерно на пару веков. Как только производство разделилось на «того, кто проектирует» и «того, кто изготавливает», понадобился документ-посредник: инженерные чертежи с допусками, промышленные стандарты на резьбу, калибры, рецептуры. Вся взаимозаменяемость деталей XIX–XX века держится на том, что изделие описано на бумаге точнее, чем словами у станка.

В компьютерную эпоху у спецификации несколько заметных вех.

1969 — RFC 1. Аспирант Стив Крокер пишет первый Request for Comments (дословно «запрос комментариев») — рабочую заметку о протоколах зарождающегося ARPANET. Скромное название прижилось, и сегодня RFC — это фактические спецификации интернета: IP описан в RFC 791 (1981), HTTP/1.1 — в RFC 2616 (1999). Сейчас RFC перевалили за девять тысяч. Интернет в буквальном смысле работает потому, что тысячи независимых команд реализуют одни и те же спеки.

1970 — Уинстон Ройс и «водопад». В статье «Managing the Development of Large Software Systems» Ройс описал каскадную модель: требования → проектирование → код → тестирование, и между этапами — документы. Ирония в том, что сам Ройс в той же статье предупреждал: в чистом виде одна проходка «сверху вниз» рискованна. Но индустрия запомнила картинку, а не оговорку, и на пару десятилетий толстая спецификация стала главным артефактом разработки.

1975 — «Мифический человеко-месяц». Фредерик Брукс, руководивший созданием OS/360 в IBM, формулирует идею концептуальной целостности: у системы должен быть один замысел, и письменная спецификация — способ этот замысел сохранить, когда над проектом работают сотни людей.

1984 — IEEE 830. Выходит стандарт на то, как писать спецификацию требований к ПО (SRS, Software Requirements Specification). Пересматривался в 1998-м, а в 2011-м его сменил ISO/IEC/IEEE 29148, действующий до сих пор.

1986 — Design by Contract. Бертран Мейер встраивает спецификацию прямо в код: в его языке Eiffel у каждой процедуры есть предусловия и постусловия — машинно-проверяемый мини-контракт. На другом полюсе строгости — TLA+ Лесли Лэмпорта (конец 1990-х): математический язык спецификаций, которым Amazon в 2010-х проверял алгоритмы AWS и, по статье в Communications of the ACM (2015), находил реальные баги в DynamoDB до того, как они случились в проде.

2001 — Agile-манифест. Семнадцать практиков в Юте формулируют: «работающий продукт важнее исчерпывающей документации». Маятник качнулся от толстых спеков к user stories и живому общению. Важно: манифест не запрещал спецификации — он возражал против документов, которые пишутся ради документов.

2011 — Swagger → OpenAPI. Тони Тэм делает Swagger — машиночитаемое описание HTTP-API; в 2016-м проект передан Linux Foundation и переименован в OpenAPI. Спека перестала быть только текстом для людей: по ней генерируют код, тесты и документацию.

2020-е — ренессанс из-за ИИ. Когда исполнителем становится языковая модель, спека снова главный артефакт: агенту нельзя «объяснить на пальцах у кофемашины». Появился термин spec-driven development; в 2025-м GitHub выпустил Spec Kit — инструментарий ровно под этот подход.

Русская ветка — ГОСТы: серия ГОСТ 19 (документация на программы) и ГОСТ 34, где ГОСТ 34.602-89 описывает состав ТЗ (технического задания) на автоматизированную систему; в 2020 году вышла обновлённая редакция.

Что это такое

Спецификация отвечает на два вопроса: что должно получиться и как проверить, что получилось. Всё остальное — стиль, формат, объём — вторично. Спека может быть страницей текста в вики, ГОСТовским томом на сто листов, YAML-файлом OpenAPI или issue в трекере — если в ней есть однозначное «что» и проверяемое «как убедиться», это спецификация.

Главное разделение, которое стоит держать в голове: спека описывает что, а не как. «Пользователь восстанавливает пароль по ссылке из письма, ссылка живёт 24 часа» — это спецификация. «Возьми библиотеку X и сделай токен через JWT» — это уже проектное решение, и в хорошей спеке оно появляется только если выбор сделан сознательно и зафиксирован как ограничение.

Полезно развести спеку с соседями:

Спецификация vs ТЗ. Техническое задание — это спецификация, оформленная как часть договора: в русской традиции ТЗ несёт юридический вес, по нему принимают работу и судятся. Каждое ТЗ — спека, но не каждая спека — ТЗ: внутренний design doc никто не подписывает у юристов.

Спецификация vs документация. Спека пишется до работы и описывает желаемое будущее; документация пишется после и описывает существующее. Частая болезнь — спека, которую забыли обновить: она превращается в документацию, которая врёт.

Спецификация vs user story. Стори — «как пользователь, я хочу восстановить пароль» — это намерение плюс обещание поговорить о деталях. Спека — результат этого разговора, записанный так, что деталей больше не надо выяснять устно.

Спецификация vs стандарт. Стандарт — это спека, о которой договорилась целая индустрия: RFC, ГОСТ, стандарты W3C. Разница не в жанре, а в масштабе договаривающихся сторон.

Аналогии из жизни

Архитектурный проект дома. Ты не объясняешь бригаде «хочу уютный дом» — ты отдаёшь проект: планировки, сечения, марка бетона, узлы. Бригада строит по проекту, технадзор принимает по нему же. Спека в разработке играет ту же роль: единый документ, по которому и делают, и проверяют. Где ломается: в стройке изменить фундамент после заливки почти невозможно, поэтому проект обязан быть полным заранее. Софт переделывать на порядки дешевле, и попытка «спроектировать всё до последнего гвоздя» до первой строчки кода часто оборачивается томом, устаревшим к середине проекта. В софте спека может и должна уточняться итерациями.

Заказ стейка в ресторане. «Рибай, medium rare, без соли» — это крошечная спецификация: описан результат и критерии приёмки, а не инструкция повару, на какой сковороде жарить. Если принесли well done — заказ объективно не выполнен, и спор не нужен. Где ломается: в ресторане ты выбираешь из готового меню, а повар видел тысячу стейков — контекст общий и огромный. В разработке задача часто уникальна, «меню» нет, и минимальной фразой не обойтись: приходится описывать контекст, границы и краевые случаи самому.

Нотная партитура. Композитор умер двести лет назад, а оркестр играет его симфонию — потому что замысел записан в формальной нотации, пережившей автора. Партитура — спека, дирижёр — тимлид, оркестранты — исполнители. Где ломается: партитура намеренно оставляет простор интерпретации — темп, динамика, фразировка у каждого дирижёра свои, и это считается искусством. Инженерная спека стремится к обратному: две «интерпретации» платёжного протокола — это не творчество, а инцидент. Чем меньше простора для трактовки, тем лучше спека.

Как это работает

Жизненный цикл спецификации выглядит примерно так — независимо от того, пишешь ты ТЗ подрядчику или design doc внутри команды.

1. Сбор входных данных. Кто заказчик, какую проблему решаем, что уже есть, какие ограничения (сроки, бюджет, легаси, регуляторика). На этом шаге спека ещё не пишется — собирается сырьё.

2. Черновик. Автор садится и пишет. Именно здесь происходит главная работа: попытка связно изложить замысел вскрывает дыры, которые в голове не были видны. Типовая структура выглядит так:

Цель          — что должно получиться и зачем (одним абзацем)
Контекст      — что уже существует, от чего отталкиваемся
Решённые
развилки      — выборы, которые уже сделаны; исполнитель их
                не переоткрывает
Поведение     — что система делает, шаг за шагом, включая
                краевые случаи и ошибки
Границы       — чего НЕ делаем (out of scope); самый
                недооценённый раздел
Критерии
приёмки       — проверяемые условия: команды, сценарии,
                ожидаемый результат (DoD, Definition of Done)

3. Ревью. Черновик читают заинтересованные стороны: исполнитель, смежные команды, заказчик. Каждый ищет своё: исполнитель — неоднозначности, смежники — конфликты со своими системами, заказчик — соответствие замыслу. Комментарии дешевле кода.

4. Согласование (sign-off). Фиксация: «делаем вот это». С этого момента спека — источник истины. Изменения возможны, но проходят как изменения: с версией, датой и уведомлением сторон, а не молчаливой правкой.

5. Реализация. Исполнитель работает по спеке. Все вопросы, которых в ней нет, — повод дополнить документ, а не решить устно и забыть.

6. Приёмка. Результат сверяется с критериями. Хорошие критерии проверяются механически: «запусти X — увидишь Y», «в файле есть разделы A–M», «время ответа меньше 200 мс на тестовом стенде».

7. Судьба документа. Либо спеку поддерживают актуальной (living spec — как HTML, который сегодня «живой стандарт» WHATWG), либо честно архивируют с пометкой «исторический документ». Худший вариант — оставить устаревшую спеку выглядеть действующей.

Где встречается в обычной жизни

• Ремонт квартиры. Приложение к договору «Спецификация работ»: перечень, объёмы, материалы, сроки. Акт приёмки — это ровно проверка по критериям. Ремонты без спеки заканчиваются фразой «а я думал, вы имели в виду другое» — классическая цена устных договорённостей.
• Торт на заказ. «Два килограмма, фисташка-малина, надпись „С юбилеем“, без мастики, к субботе» — полноценная мини-спека: результат, ограничения, срок. Кондитер волен в технологии, но связан результатом.
• Лист характеристик техники. «Спецификация ноутбука» на сайте магазина — исторически тот же жанр: производитель обязуется, что в коробке 16 ГБ памяти, а не «примерно сколько-то».
• Зарядка, которая подходит. USB-C в телефоне, ноутбуке и наушниках разных фирм — потому что все реализуют одну спецификацию USB Implementers Forum. Каждый раз, когда чужой кабель подошёл, ты пользуешься плодами чьей-то спеки.
• Анализы в лаборатории. Бланк с референсными значениями — спецификация нормы: не «вроде неплохо», а числовой диапазон, с которым сравнивают результат.

Где встречается в IT и бизнесе

• ТЗ подрядчику и тендеры. Вся заказная разработка и госзакупки держатся на ТЗ: по нему оценивают стоимость, по нему принимают работу, по нему судятся. Нужно, когда исполнитель внешний и цена недопонимания — деньги.
• API-контракт между командами. Фронтенд и бэкенд договариваются об OpenAPI-спеке эндпоинтов и дальше работают параллельно: фронт — против мок-сервера, бэк — против контрактных тестов. Нужно, когда стороны работают одновременно и не хотят ждать друг друга.
• Design doc / внутренний RFC. Во многих инженерных культурах серьёзное изменение начинается с документа, который команда рецензирует до строчки кода. Нужно, когда решение затрагивает многих и его дорого разворачивать назад.
• Приёмочное тестирование. QA пишет тест-кейсы от спеки, а не от готового кода — иначе тесты проверяют «что сделали», а не «что было нужно». Формат Given/When/Then из BDD (Дэн Норт, около 2006) — попытка писать критерии приёмки так, чтобы их понимал и человек, и машина.
• Спеки для ИИ-агентов. Делегируешь задачу модели — пишешь ей цель, контекст, решённые развилки, границы и DoD. Это то же ТЗ подрядчику, только подрядчик читает мгновенно, не переспрашивает и понимает ровно то, что написано. Качество результата упирается в качество спеки почти линейно.

Кто пользуется

• IETF — организация, выпускающая RFC: свыше девяти тысяч документов, по которым реализованы TCP/IP, DNS, TLS, HTTP. Любые два устройства в интернете общаются потому, что их производители прочли одни и те же спеки.
• W3C и WHATWG — спецификации веба: HTML, CSS, DOM. HTML с 2019 года официально ведётся WHATWG как living standard — обновляемая спека без номерных версий.
• Google — культура design docs: значимые системы начинаются с документа, который проходит ревью инженеров до начала разработки.
• Amazon — знаменитые шестистраничные нарративы и PR-FAQ (пресс-релиз, написанный до создания продукта): примерно с 2004 года презентации в PowerPoint на совещаниях заменены связным текстом, который все молча читают первые минуты встречи. А AWS применяла TLA+ для формальной спецификации DynamoDB и S3 — об этом есть статья в CACM за 2015 год.
• Stripe — компания, у которой спецификация API и справочник по ней считаются одним из главных конкурентных преимуществ продукта.
• Госсектор РФ — ГОСТ 34 и ТЗ в каждой госзакупке на информационную систему.

Альтернативы и конкуренты

• User stories + бэклог. Плюс: быстро, дёшево, не отстаёт от меняющегося продукта; детали выясняются разговором в нужный момент. Минус: договорённости живут в памяти команды и чатах — при смене людей или споре с заказчиком опереться не на что.
• Прототип вместо документа. Плюс: показывает, а не описывает; заказчик реагирует на живое лучше, чем на текст. Минус: прототип не фиксирует невидимое — нагрузку, безопасность, краевые случаи, границы объёма работ; «сделайте как в прототипе» порождает споры о том, что именно в нём считалось обещанием.
• Устные договорённости. Плюс: нулевой оверхед, работает в паре людей с общим контекстом и доверием. Минус: не масштабируется ни по числу людей, ни по времени — через месяц каждый помнит своё.
• Формальные методы (TLA+, Z-нотация). Плюс: математическая строгость, ловит баги распределённых систем, которые не находит ни ревью, ни тесты. Минус: высокий порог входа и трудоёмкость; оправдано для ядра критичных систем, избыточно для 99% продуктовых задач.

Когда НЕ стоит использовать

• Исследовательский прототип. Когда результат эксперимента неизвестен, детальная спека устареет раньше, чем допишется. Фиксируй только цель эксперимента, бюджет времени и критерий «поняли/не поняли» — остальное сожрёт скорость.
• Микрозадача для человека с полным контекстом. Просить коллегу поправить опечатку через двухстраничный документ — оверхед дороже задачи. Спека окупается там, где цена недопонимания выше цены её написания.
• Продукт до product-market fit. Если продукт перепридумывается каждые две недели, тяжёлые спецификации фиксируют то, что завтра выбросят. Здесь честнее лёгкие стори и прототипы — а спеки появятся вместе со стабильным ядром продукта.

Связанные понятия

• ТЗ (техническое задание) — спецификация как часть договора, по которой принимают и оплачивают работу.
• DoD (Definition of Done) — согласованный список условий, при которых работа считается завершённой.
• Acceptance criteria (критерии приёмки) — проверяемые условия соответствия результата требованиям.
• RFC (Request for Comments) — жанр спецификаций интернета и, шире, формат «документ для обсуждения» внутри компаний.
• OpenAPI — машиночитаемая спецификация HTTP-API, из которой генерируют код, тесты и документацию.
• Design by Contract — подход, встраивающий спецификацию (пред- и постусловия) прямо в код.
• User story — лёгкая альтернатива: намерение пользователя плюс обещание обсудить детали.

Литература и источники

• Карл Вигерс, Джой Битти — «Разработка требований к программному обеспечению» (3-е изд., 2013, есть русский перевод) — самый полный практический учебник по требованиям и спецификациям.
• Джоэл Спольски — серия «Painless Functional Specifications» (2000, en) — четыре короткие статьи о том, зачем и как писать спеки без бюрократии; искать «Joel on Software painless functional specifications».
• Фредерик Брукс — «Мифический человеко-месяц» (1975, есть русский перевод) — глава о концептуальной целостности и роли письменной спецификации.
• ISO/IEC/IEEE 29148 — действующий стандарт на инженерию требований; искать по номеру на сайте ISO.
• Статья «Software requirements specification» в английской Википедии: https://en.wikipedia.org/wiki/Software_requirements_specification
• Chris Newcombe et al. — «How Amazon Web Services Uses Formal Methods» (CACM, 2015, en) — как TLA+ ловил баги в DynamoDB; искать по названию статьи.

Где встретилось у меня

Вчера конвейер этого самого дайджеста работал по схеме «оркестратор — исполнитель — верификатор»: дорогая думающая модель не писала статью сама, а составляла спеку — цель, контекст, решённые развилки, шаги, границы, DoD — и отдавала её агенту-исполнителю, после чего третий, независимый агент принимал работу строго по критериям из спеки. Документ выступал контрактом между тремя ИИ, ни один из которых не видел рассуждений другого, — и вся связность держалась именно на спецификации.

Краткое резюме

• Спецификация — это «что должно получиться» плюс «как проверить», записанные до начала работы; форма вторична, проверяемость обязательна.
• Спека нужна, когда работу делает не тот, кто её придумал: подрядчик, параллельная команда, ИИ-агент. Чем меньше общего контекста у сторон, тем она важнее.
• Главная ценность — мышление заранее: развилки и противоречия ловятся на бумаге, где правка стоит минуты, а не в коде, где она стоит дни.
• Спека без критериев приёмки — пожелание: если результат нельзя проверить процедурой, спор о нём неизбежен.
• Весь интернет — совместимость устройств, браузеров и API — работает на спецификациях: RFC, стандарты W3C, OpenAPI. А с приходом ИИ-агентов умение писать спеку становится навыком буквально ежедневного применения.