Как разработка по спецификациям дисциплинирует AI-агентов

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

Я усвоил это различие дорогим способом. Агент может выполнить подробную инструкцию из чата, пройти очевидные тесты и при этом изменить контракт API, ослабить границу авторизации или придумать поведение, которого никто не утверждал. Обычно проблема не в том, что модель не умеет писать программы. Команда дала ей текст без контракта и приняла правдоподобный результат за доказательство.

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

Промпт устаревает вместе с сеансом

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

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

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

Выбор модели тоже становится менее значимым. Разные агенты по-прежнему предложат разные реализации, но будут работать в одной границе. Без спецификации смена модели часто меняет подразумеваемое продуктовое решение. Со спецификацией меняется в основном путь к согласованному результату. Оптимизировать такую переменную гораздо безопаснее.

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

Полезная спецификация устраняет пять видов неоднозначности

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

Начните с наблюдаемого поведения. Назовите участника, предусловие, действие и результат. «Добавить экспорт CSV» - это ярлык функции. Фраза «администратор аккаунта может экспортировать текущую отфильтрованную выборку счетов в CSV в кодировке UTF-8» задает проверяемую поверхность. Добавьте пример, если слова допускают два разумных толкования.

Затем обозначьте границы. Прямо перечислите, что входит в объем изменения, а что намеренно исключено. Если экспорт относится к счетам, но не к кредит-нотам, так и напишите. Если публичный API менять нельзя, зафиксируйте ограничение. Агенты склонны попутно исправлять соседние несоответствия, потому что на тестовых задачах это часто улучшает результат. В рабочем репозитории незапрошенная чистка увеличивает объем ревью и риск регрессии.

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

Ограничения качества должны измеряться. Слова «быстро» и «безопасно» не могут провалить проверку. Хорошее требование называет бюджет, правило авторизации, поддерживаемую платформу или запрещенный поток данных. Если честное число выбрать нельзя, задайте сравнение или процедуру наблюдения вместо выдуманной точности. Например, потребуйте, чтобы новый план запроса не выполнял последовательное сканирование на фикстуре, похожей на продакшен.

Наконец, определите доказательство. Для каждого требования нужен хотя бы один приемочный сценарий, а каждому сценарию должен соответствовать автоматический тест или явная ручная проверка. Я экономно использую слова из RFC 2119: MUST для условия, которое блокирует выпуск, SHOULD для осознанного правила по умолчанию с понятными исключениями и MAY для допустимой вариативности. Стандарт предупреждает, что эти термины уместны лишь там, где от них зависит совместимость или предотвращение вреда. Если превратить каждую фразу в MUST, получится церемония, а не ясность.

Компактное требование может выглядеть так:

Requirement: Filtered invoice export
Actor: Account administrator
Precondition: At least one invoice matches the active filters
Behavior: The system MUST export exactly the matching invoices
Format: UTF-8 CSV with one header row and RFC 4180 field escaping
Failure: A non-administrator receives 403 and no export job is created
Out of scope: Scheduled exports and credit notes
Evidence: API contract test, permission test, CSV fixture comparison

Названия полей не имеют особого значения. Важны закрытые решения.

Разделяйте замысел, проектирование, задачи и доказательства

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

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

Такое разделение дает трассируемость без громоздкой базы требований. Присвойте каждому поведенческому требованию стабильный идентификатор, например EXP-003. План ссылается на него при выборе эндпоинта или очереди. Тесты включают его в имя или метаданные. Пул-реквест сообщает результат. Если требование изменится, поиск покажет артефакты, которые могли устареть.

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

specs/
  current/exports.md
  changes/exp-014-filtered-csv/
    proposal.md
    spec.md
    plan.md
    tasks.md
    evidence.md
contracts/
  exports.openapi.yaml
tests/acceptance/
  exp_014_export_test.ts

Храните текущее истинное состояние отдельно от предлагаемой дельты. OpenSpec формализует это через openspec/specs/ для принятого поведения и openspec/changes/ для предложений, задач, необязательных проектных решений и дельт спецификаций. Такая модель подходит зрелым продуктам: ревьюеры видят и стабильный контракт, и точное предлагаемое изменение. После утверждения и реализации архивация переносит дельту в текущее состояние.

GitHub Spec Kit предлагает более широкий поэтапный подход: конституция, спецификация, план, задачи и реализация. В документации основной процесс описан как переход от Spec к Plan, затем к Tasks и Implement, а рядом доступны уточнение и анализ согласованности артефактов. Мне нравится это разделение, но ни одна команда не определит, верно ли критерии приемки выражают бизнес-политику. Обвязка контролирует последовательность и форму, а за смысл по-прежнему отвечает конкретный человек.

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

Контроль превращает документы в систему управления

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

Первый барьер проверяет структуру. Валидируйте наличие владельца, объема, исключений, приемочных сценариев и трассируемых идентификаторов у каждого изменения. В OpenSpec есть команда openspec validate <change> для проверки обязательного формата дельты. В Spec Kit есть этапы checklist и analyze, которые ищут неясные требования и противоречия между созданными артефактами. Можно взять любой из этих инструментов или маленький локальный валидатор, если ошибка сообщает, что именно исправить.

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

Третий барьер работает в непрерывной интеграции. Простой конвейер может проверить контракт до того, как потратит минуты на полный набор тестов:

spec-check:
  script:
    - ./bin/spec-lint specs/changes/$CHANGE_ID/spec.md
    - ./bin/trace-check $CHANGE_ID
    - npm test -t $CHANGE_ID

contract-check:
  script:
    - ./bin/openapi-diff contracts/base.yaml contracts/exports.openapi.yaml
    - ./bin/verify-evidence specs/changes/$CHANGE_ID/evidence.md

spec-lint должен выводить место и отсутствующее поле, а не туманное сообщение о невалидности. Полезный формат результата выглядит так: spec.md:24 EXP-003 missing failure behavior. trace-check должен падать, когда задача или приемочный тест ссылается на неизвестный идентификатор. Сравнение API должно отличать совместимое добавление от ломающего изменения и требовать отдельного согласования для второго случая.

Четвертый барьер задает политика слияния. В документации GitHub сказано, что защищенные ветки могут требовать успешных статусных проверок до слияния и ревью владельцев кода. Назначьте владельцев путям спецификаций и файлам контрактов, затем сделайте проверки спецификации, контракта и приемки обязательными. Защитите и сам файл CODEOWNERS. GitHub отдельно отмечает этот момент, потому что иначе правило владения можно изменить в том же пул-реквесте, который оно должно контролировать.

Не просите модель оценить собственное соответствие требованиям и не называйте это контролем. Агентское ревью помогает найти пробелы, но решение об открытии барьера принимают детерминированные проверки и названные люди.

В процессе работы агента нужны явные точки остановки

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

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

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

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

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

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

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

Разобранное изменение обнаруживает пропущенные решения

Представим биллинговый продукт с существующим эндпоинтом POST /exports, который запускает асинхронный экспорт счетов. Сейчас запрос принимает диапазон дат. Основатель поручает агенту: «Дай пользователям экспортировать счета с текущими фильтрами интерфейса, сохрани существующий эндпоинт и добавь тесты». Запрос кажется подробным, но опасные решения остаются открытыми.

Что означает слово «фильтры»: поисковую строку, статус, клиента, валюту и сортировку? Экспорт фиксирует сами фильтры или точный набор совпавших записей? Что случится, если счета изменятся во время выполнения задания? Может ли пользователь экспортировать счета чужого аккаунта, угадав идентификатор клиента? Пустой результат должен стать корректным файлом или ошибкой? Агент способен выбрать ответы и написать чистый код. Чистота кода не дает этим ответам законной силы.

Сначала запишите поведенческую дельту:

Change: EXP-014 Filtered invoice export

EXP-014-1
Given an account administrator with active date, status, and customer filters
When the administrator creates an invoice export
Then the job stores the normalized filter values
And the worker exports invoices matching those values at execution time

EXP-014-2
The service MUST derive account_id from the authenticated session.
It MUST reject a customer_id that does not belong to that account with 404.

EXP-014-3
An empty match MUST produce a CSV containing the header row.
Search text, currency filters, and sort order are out of scope.

Теперь решение применять фильтры во время выполнения сформулировано явно. Экспорт снимка потребовал бы другого проекта и дополнительных затрат на хранение. Ответ 404 не подтверждает, что угаданный идентификатор клиента принадлежит другому аккаунту. Файл только со строкой заголовков позволяет пользователям и автоматике отличить успешный пустой запрос от сломанного экспорта.

Затем измените контракт интерфейса до рабочего кода:

ExportRequest:
  type: object
  additionalProperties: false
  properties:
    date_from: { type: string, format: date }
    date_to: { type: string, format: date }
    status: { type: array, items: { enum: [draft, open, paid, void] } }
    customer_id: { type: string, format: uuid }
  required: [date_from, date_to]

additionalProperties: false не даст системе молча проигнорировать опечатку в customer_id. Перечисление защищает названия статусов от расхождения между интерфейсом и сервисом. Теперь план может назвать валидатор запроса, запрос авторизации, полезную нагрузку задания, запрос воркера, фикстуру CSV и тест совместимости.

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

Допустим, агент обнаруживает, что задания сейчас хранят только date_from и date_to в фиксированных столбцах базы данных. Для фильтров нужна миграция. Исходный запрос не давал права выбирать стратегию схемы, поэтому агент останавливается и предлагает два плана: nullable-столбцы для ограниченного набора фильтров или версионируемая полезная нагрузка JSON с более строгой валидацией в приложении. Ревьюер выбирает вариант с учетом ожидаемых изменений и запросов. Такая остановка означает успех. Процесс со спецификацией обнаружил решение до того, как код сделал его дорогим для отмены.

Изменение закрывают доказательства, а не один зеленый набор модульных тестов:

EXP-014-1: acceptance/export_filters.test.ts passed
EXP-014-2: acceptance/export_tenant_boundary.test.ts passed
EXP-014-3: fixtures/export_empty.csv byte comparison passed
API compatibility: additive request fields, existing request fixture passed
Migration: upgrade and rollback tested on a production-shaped fixture
Human approval: billing owner reviewed execution-time semantics

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

Тесты дают доказательства, но не заменяют спецификацию

Тесты подтверждают выбранные наблюдения за реализацией. Они не объясняют полностью, зачем существует поведение, какие варианты отвергли, кто отвечает за политику и что осталось за пределами задачи. Если считать тесты всей спецификацией, продуктовый замысел окажется заперт в деталях проверок.

Обратная ошибка хуже: приемочный текст без исполняемых проверок. Формат Given-When-Then помогает ревьюерам рассуждать о поведении, но не предотвращает расхождение, пока его не оценивает тест, валидатор контракта, измерение или названный ревьюер. Каждому критерию приемки нужен тип доказательства. Не каждому критерию нужен модульный тест. Доступность может потребовать автоматических проверок и ручной работы с клавиатурой. Для миграции может понадобиться репетиция и сверка числа строк. Для эксплуатационного лимита может понадобиться нагрузочный тест с зафиксированной фикстурой.

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

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

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

Инструмент должен соответствовать возрасту кодовой базы

Выбирайте инструменты по характеру изменений в системе, а не по громкости запуска очередного репозитория. Новым продуктам, зрелым системам, API и регулируемым процессам нужен разный объем структуры.

GitHub Spec Kit подходит командам, которым нужен полный поэтапный процесс и которые готовы поддерживать конституцию, спецификации функций, планы, задачи и анализ. Явные этапы помогают новому проекту установить правила до появления множества противоречивых шаблонов. Официальная документация теперь описывает его как расширяемую обвязку, способную запускать этапы отдельно или в автоматических процессах. Эта гибкость полезна, но автоматизация усиливает потребность в осознанных точках утверждения.

OpenSpec удобен для существующих систем, потому что отделяет текущее истинное состояние от предлагаемых изменений и валидирует сценарии требований и дельты. Цикл proposal, apply и archive естественно ложится на зрелый продукт, где маленькие изменения обязаны сохранять большой объем поведения. Он также поддерживает инструкции для разных агентов программирования, поэтому команда меньше зависит от одного интерфейса.

Процесс спецификаций Kiro организует работу над функцией вокруг требований, проекта и задач. Он подходит команде, которая хочет видеть эти этапы внутри интегрированной среды агента. OpenAPI, AsyncAPI, JSON Schema, Protocol Buffers, инструменты миграции баз данных и движки политик решают более узкие части той же проблемы контроля. Используйте их для интерфейсов, которые можно проверить машиной, вместо повторения точных ограничений в прозе.

Часто хватает обычного Markdown и валидатора. Маленькой команде не нужен брендированный фреймворк, чтобы присваивать идентификаторы требованиям, проверять diff спецификации, запускать контрактные тесты и защищать ветку. Ей нужны постоянные пути, шаблоны с трудными вопросами и CI, который падает при отсутствии доказательств. Инструмент должен сокращать свободу толкования, а не создавать папку с текстом, который никто не читает.

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

Внедрение начинается с одного рискованного изменения

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

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

Будьте готовы, что первые спецификации обнаружат организационные пробелы. Продуктовая команда может не знать, кто определяет поведение при пустом состоянии. У инженеров может не быть стабильного контракта API. Тесты могут зависеть от фикстур, которые не отражают размер продакшена. Эти находки похожи на процессные издержки, потому что старый процесс прятал их в ревью кода или рабочих инцидентах. Исправляйте владение и инструменты, а не удаляйте вопросы из шаблона.

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

Для компаний, которые переходят к маленьким командам с AI, эта дисциплина не управленческий театр. Меньшее число инженеров может выпускать больше изменений, только если замысел, полномочия и доказательства остаются доступными для проверки. В рамках Team & AI Audit на oleg.is я нахожу места, где на пути поставки ломаются спецификации, разрешения агентов, барьеры CI и владение; полезный результат такой работы состоит в изменении процесса, а не в очередной презентации про AI.

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