Spec-first разработка: договоритесь о намерении до того, как ИИ напишет код

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

Все гадали

Знакомый сценарий провала выглядит так. Изменение выкатывают, и только на ревью, а то и в продакшене, команда понимает, что получилось не то, чего кто-либо хотел. Требования были раскиданы по ветке чата, комментарию в тикете и головам нескольких людей, и каждый источник говорил немного своё.

Конкретно: кто-то берёт задачу, требования к которой такие:

• заголовок тикета в одну строку,
• ветка в Slack, которая заглохла,
• и допущение, которое все считали общим, хотя это было не так.

Человек это делает. Ревью ловит часть расхождений, а остальное пропускает: ревьюер видит только дифф и вынужден идти от кода назад, к догадке о том, чего хотели. Это ровно противоположное направление. После релиза единственная запись о том, что должна делать фича, — это код плюс то, что команда ещё помнит.

Именно последнее тихо вредит больше всего. Контекст испаряется, как только разговор закончен. Через полгода никто, ни человек, ни агент, не может сказать, каким должно было быть поведение, — только что код делает на самом деле.

Почему агенты меняют расчёт

Агенты перевернули экономику за одну ночь. Десятилетиями написание кода было дорогим и аккуратным шагом, и все процессы строились вокруг него. Агент же — быстрый и уверенный угадчик. Дайте ему расплывчатый промпт, и через секунды он вернёт правдоподобный, красиво структурированный и совершенно неверный код. Генерация теперь почти бесплатна. Решить, что правильно, — вот и вся работа.

Поэтому долговечным и дефицитным артефактом становится точное общее описание намерения — спецификация. Не как бумажная работа, а как то, о чём договариваются люди, и как контекст, который вы даёте агентам. Отсюда эксперимент: сначала написать спецификацию, согласовать её, а потом пусть люди и агенты строят по ней.

Что значит разработка через спецификации

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

Сразу всплывают три возражения, так что вот чем это не является:

• Это не водопад. Спецификация должна быть достаточно хорошей, чтобы начать, и вы правите её по ходу. Думайте о живом документе, а не о подписанной папке с требованиями.
• Это не тяжело. Крошечным изменениям хватит дельты спецификации на десять строк в одном пул-реквесте. Усилия растут только вместе с размером изменения.
• Это не дизайн-документ. Дизайн-документ объясняет, почему выбран подход, а спецификация описывает, что система делает сегодня. Этой границе ниже посвящён отдельный раздел.

Выгода простая: сначала договоритесь о цели, потом тратьте силы на то, чтобы в неё попасть, и сохраните эту договорённость, когда чат давно забыт.

Ваша должностная инструкция меняется

Всё остальное держится на одном сдвиге в мышлении. Ваша главная ответственность теперь — писать сильные спецификации, ревьюить их и править код руками только там, где ИИ не справляется.

Это переворачивает то, чему учили большинство разработчиков. Раньше работой было писать код. Теперь это то, что вы делаете меньше всего. Настоящая работа по важности начинается со спецификации и её ревью, и только потом идёт код, написанный вручную.

Шесть принципов, которые стоит повторять

Когда спрашивают, сколько спецификации достаточно, раз за разом звучат одни и те же ответы:

• Сначала договоритесь. Напишите или обновите спецификацию, получите быстрое ревью и только потом реализуйте.
• Держите спецификации рядом с кодом. Они лежат в репозитории, ревьюятся в том же изменении и принадлежат тем, кто владеет этим кодом.
• Маленькие дельты лучше больших переписываний. Каждое изменение говорит, что добавлено, изменено или удалено, а не пересказывает весь мир заново.
• Описывайте поведение проверяемыми сценариями. Где что-то можно протестировать, используйте given/when/then, а не прозу.
• Оставайтесь гибкими. Если реальность разошлась со спецификацией, обновите спецификацию, а не дайте ей сгнить.
• У каждой возможности должен быть один источник правды — одно место, где описано её текущее поведение.

Ежедневный цикл

Подход не зависит от инструментов. Обычных Markdown-файлов в папке specs/ достаточно. Но немного инструментов снижает трение, и OpenSpec — это open-source процесс работы со спецификациями, который подключается к ИИ-агентам и даёт слэш-команды под этот цикл:

1. Исследование, по желанию. Когда форма изменения размыта, пусть агент прочитает код, взвесит варианты и набросает план до того, как вы возьмёте на себя обязательства.
2. Предложение. Дайте описание в одну строку, и инструмент сгенерирует предложение, короткую дизайн-заметку, список задач и дельту спецификации — самую важную часть, потому что она показывает, как изменится живая спецификация.
3. Сначала ревью спецификации. В этом вся игра. Предложение и дельту ревьюят до того, как появится хоть строчка кода, потому что поменять предложение в тексте дёшево, а поменять выкаченную реализацию — нет.
4. Применение. Стройте по согласованной спецификации, сами или с агентом.
5. Проверка. Запустите проверки, в идеале с приёмочными сценариями, которые напрямую превращаются в тесты.
6. Архивирование. Влейте дельту в живую спецификацию, чтобы она всегда описывала настоящее, а предложение отправьте в историю.

Если оставить только один шаг, оставьте третий: ревью спецификации до кода.

Настройка OpenSpec с ИИ-агентом

Современные агенты вроде Claude Code могут выучить этот процесс и вести его вместе с вами, так что не придётся проговаривать каждый шаг. OpenSpec упаковывает эти знания в навыки агента и слэш-команды. Две команды подключают его к репозиторию и к агенту:

# install the CLI (drives everything below)
npm install -g @fission-ai/openspec@latest

# scaffold the spec structure AND generate agent skills + slash commands
openspec init --tools claude

Шаг init делает две вещи. Во-первых, создаёт место для спецификаций: папку specs/ для живых спецификаций, папку changes/ для предложений в работе и небольшой конфиг, где вы описываете стек и соглашения. Во-вторых, устанавливает навыки агента. Для Claude это файлы навыков плюс команды /opsx:*: explore, propose, apply, archive и sync. Навыки учат агента составлять предложение, делать дельту спецификации, реализовывать по ней и вливать результат обратно в живую спецификацию.

Как выглядит изменение

Представьте фоновую задачу, которой нужен настраиваемый таймаут. Задача, превысившая лимит, должна отменяться и помечаться как timed_out.

Всё начинается с дельты спецификации, то есть диффа относительно живой спецификации, который точно показывает, что сдвинется:

### Requirement: Job timeout
- The system SHALL run a job to completion.
+ The system SHALL cancel a job that exceeds a configurable timeout
+ (default 30s) and record the outcome as `timed_out`.+ #### Scenario: Job exceeds the configured timeout
+ - GIVEN a job configured with a 5s timeout
+ - WHEN the job has run for 5s without completing
+ - THEN the system cancels the job
+ - AND sets its status to `timed_out`
+ - AND emits a `JobTimedOut` event with the job id

Именно этот дифф ревьюят люди, до любой реализации. Коллега может поставить под вопрос значение по умолчанию, название статуса или событие, пока это всего лишь предложение в тексте. Когда все согласны, у сборки есть однозначная цель, а сценарий превращается в тест.

После выката архивирование вливает это требование в живую спецификацию как простое описание того, как система ведёт себя сейчас, без оставшихся плюсов и минусов. Следующий, кто тронет этот код, человек или агент, прочитает его и не будет гадать.

Спецификация или дизайн-документ

Их путают, и это ведёт к дублированию и путанице. Разделение, которое прижилось:

• Дизайн-документ объясняет решение: почему этот подход, какие были компромиссы. Это снимок момента, и он должен устаревать, потому что это историческая запись.
• Спецификация описывает текущее поведение, то есть что система делает прямо сейчас. Она живая и никогда не должна устаревать, потому что работает как контракт.

На практике исследуйте варианты и принимайте решение в дизайн-документе, фиксируйте долгоживущее поведение в спецификации и связывайте их ссылкой, а не дублируйте. Если одно и то же поведение поддерживается в обоих местах, сократите дизайн-документ до ссылки.

Внедрение в команде

Поможет короткий чек-лист. Для следующего изменения: опишите его и сгенерируйте предложение и дельту спецификации, отдайте спецификацию на ревью до написания кода, после одобрения реализуйте и добейтесь прохождения сценариев, затем заархивируйте, чтобы живая спецификация совпадала с реальностью.

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

Не пытайтесь заранее описать всю существующую систему. Пишите спецификации по мере того, как трогаете код, и покрытие будет расти там, где идёт работа.

Попробуйте на следующем изменении

Не нужна большая инициатива или указание сверху. При следующем нетривиальном изменении до кода запишите, что оно должно делать, в виде нескольких сценариев given/when/then. Попросите коллегу посмотреть сначала на эти сценарии. Потом стройте, добейтесь прохождения сценариев и закоммитьте спецификацию вместе с кодом.

Вот и всё. Сделайте так несколько раз, пусть ваши пул-реквесты тихо станут лучше, и команда начнёт спрашивать вас, где спецификация.

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