Разработке на основе спецификаций нужны проверки, а не новый текст

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

Я видел, как команды неделями унифицировали шаблоны, пока поведение системы в рабочей среде продолжало расходиться с описанием. И видел, как небольшие команды получали настоящий контроль с помощью обычного файла Markdown, JSON Schema и одной задачи в CI. Дело было не в формате. Вторая команда понимала, какие утверждения нужно сделать исполняемыми, кто за них отвечает и на каком этапе ошибка должна остановить работу.

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

Спецификация должна позволять обнаружить несогласие

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

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

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

Это различие становится еще важнее, когда в процесс входят агенты программирования. Агент способен превратить расплывчатый замысел в правдоподобный код, но именно правдоподобие создает риск. Если в репозитории не сказано, должен ли повторно использованный токен вернуть 400, 401 или идемпотентный 204, агент выберет сам. Код может собраться и пройти общие тесты, создав при этом поведение API, которое никто не утверждал. Дополнительные подсказки не исправят отсутствующее решение.

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

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

Формат должен соответствовать решению

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

Markdown хорошо подходит для целей, исключений, терминологии, переходов состояния и приемочных примеров. Его удобно читать при рецензировании, он переживает смену поставщика и хранится рядом с кодом. Его слабое место состоит в структурной неоднозначности. Заголовок «Обработка ошибок» мало что сообщает парсеру, а примеры на естественном языке могут противоречить таблице, не вызывая ошибки. Используйте Markdown для смысла, которому нужны пояснения, а обязательным утверждениям присваивайте стабильные идентификаторы наподобие AUTH-RESET-004.

OpenAPI подходит для HTTP-интерфейсов, когда клиенты, шлюзы, контрактные тесты или документация должны работать с одним описанием. OpenAPI 3.1 намеренно согласует Schema Object со словарем JSON Schema, что уменьшает старое расхождение между описанием API и валидацией. Но файл OpenAPI от этого не становится полной спецификацией поведения. Он может указать обязательное поле и шаблон, но сам по себе не объяснит, почему повторное использование токена сброса должно завершиться ошибкой и как разрешать одновременные запросы. Закрепите такое поведение в тестах, связанных с идентификаторами требований.

JSON Schema лучше подходит для событий, конфигурационных файлов, входных данных инструментов и хранимых документов, если речь идет не преимущественно об HTTP-операциях. Схема может отклонять неизвестные свойства, ограничивать сочетания и развиваться через явные версии. Команды часто не указывают additionalProperties: false, потому что строгость кажется неудобной. В результате они молча принимают поля с опечатками, а это намного хуже. Строгость полезна на подконтрольной границе; для открытой поверхности расширения ей нужна продуманная политика совместимости.

Protocol Buffers и другие языки описания интерфейсов уместны, когда сгенерированные клиенты и двоичная совместимость уже определяют устройство системы. Брать их первым инструментом лишь из-за формального вида дорого. Формат оправдывает свое место, когда его читает настоящий потребитель. В противном случае команда поддерживает ритуал.

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

На практике набор обычно смешанный:

• Markdown хранит замысел, исключения, примеры и решения, которым нужны пояснения.
• OpenAPI или язык описания интерфейсов задает вызываемые границы.
• JSON Schema описывает события, конфигурацию и структурированный вывод агентов.
• Тесты проверяют временные правила, авторизацию, параллельность и поведение при сбое.
• ADR сохраняют причины выбора после смены состава команды.

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

Проверки превращают спецификацию в средство управления

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

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

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

set -eu
./bin/validate-spec specs/orders.openapi.yaml
./bin/check-api-compat origin/main specs/orders.openapi.yaml
./bin/generate-api check specs/orders.openapi.yaml
./bin/test-contracts requirements specs/orders.md

В выводе должны быть решение и обнаруженный конфликт, а не только код завершения 1. Полезная ошибка имеет стабильную форму:

COMPATIBILITY_ERROR operation=POST_/orders path=response.201.id
change=required_property_removed requirement=ORD-CREATE-012
baseline=origin/main candidate=HEAD

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

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

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

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

Трассировка должна вести к доказательству

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

Стабильные идентификаторы работают, если описывают поведение, а не положение в документе. ORD-CANCEL-007 переживет правку заголовков и перенос файла. SECTION-4.2.1 не переживет. Разместите идентификатор рядом с обязательной фразой, затем ссылайтесь на него в именах тестов, контрактных наборах данных или структурированных метаданных теста. Не копируйте по этим местам сам текст требования.

Небольшой индекс можно генерировать из исходных файлов и результатов тестирования:

{
  "requirement": "ORD-CANCEL-007",
  "status": "covered",
  "evidence": ["contract/cancel_order_test.go::expired_orders_are_rejected"],
  "build": "8f31c2a"
}

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

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

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

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

Узкий вертикальный срез проверяет весь процесс

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

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

1. Добавьте ORD-CREATE-019 в спецификацию Markdown с ограничением, поведением при отсутствии, правилом сохранения и ожиданием совместимости. Если пробелы действительно нужно сохранять, напишите об этом. Иначе разработчики примут разные «полезные» решения.
2. Добавьте необязательное поле в схемы запроса и ответа. Используйте родное для контракта ограничение длины и оставьте свойство необязательным. Повторно сгенерируйте типы, не редактируйте сгенерированные файлы.
3. Добавьте примеры на неудобных границах: поле отсутствует, строка пуста, 280 символов, 281 символ, пробелы в начале и символ из нескольких кодовых точек. Решите, что считается длиной: кодовые точки Unicode, графемные кластеры или байты в кодировке. Одного слова «символы» для проверки недостаточно.
4. Запустите сравнение совместимости с базовой версией из рабочей среды, а не со случайно открытой локальной веткой. Затем выполните контрактный тест, который отправляет запрос, читает результат и указывает ORD-CREATE-019 в метаданных.
5. Если существующий трафик может нарушать новую схему, сначала разверните проверку во время работы в режиме наблюдения. Посчитайте и изучите ошибки до отклонения запросов, затем включите обязательную проверку, назначив ответственного и условие отката.

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

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

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

Агентам программирования нужны границы полномочий

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

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

task: implement ORD-CREATE-019
authority:
  intent: specs/orders.md
  interface: specs/orders.openapi.yaml
allowed_paths:
  - services/orders/
  - tests/contract/
forbidden_actions:
  - modify_requirement
  - edit_generated_files
verify:
  - ./bin/generate-api check specs/orders.openapi.yaml
  - ./bin/test-contracts requirement ORD-CREATE-019
output_schema: specs/agent-result.schema.json

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

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

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

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

В oleg.is я применяю подобные ограниченные процессы при перестройке инженерной работы вокруг Claude Code, Codex, инструментов MCP и многоагентных конвейеров. Технология здесь проста; больше всего труда требует решение о том, что агенты вправе менять и какие доказательства должно требовать руководство.

Порядок внедрения должен снижать цену ошибок

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

Сначала определите небольшой словарь: что команда называет замыслом, обязательным требованием, контрактом, доказательством и исключением. Это не руководство по стилю. Словарь не дает одному слову означать задачу для менеджера продукта, документ OpenAPI для разработчика серверной части и план тестирования для QA. Определения должны помещаться на одном экране.

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

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

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

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

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

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

Для долга спецификаций нужна политика удаления

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

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

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

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

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

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

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

Нужно также различать соответствие и правильность. Запрос может соответствовать JSON Schema и при этом списать деньги не с того клиента. Реализация может вернуть документированный код состояния, нарушив решение об авторизации. Валидаторы схем доказывают структурные утверждения. Контрактные тесты проверяют выбранное наблюдаемое поведение. Модульные тесты и тесты свойств исследуют внутренние инварианты. Телеметрия рабочей среды способна обнаружить входные данные и последовательности, которых никто не моделировал. Если назвать любой один слой спецификацией, появятся слепые зоны. Передайте каждое утверждение слою, который может его наблюдать, а идентификатор требования оставьте связью между ними.

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

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