Документацию к программе с ИИ-агентами пишут до кода: у нас её столько же, сколько кода

Что требовать от подрядчика? Описание того, как программа должна работать. Руководство пользователя объясняет кнопки, но не задаёт требования.

По коду агент видит, что работает сейчас. Какое поведение вы одобрили, а какое возникло случайно, он не узнает. Это записывают до поручения.

В GitHub Spec Kit сначала определяют, что строить, затем планируют реализацию. Так устроен Spec-Driven Development: результат согласуют до работы.

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

Зачем столько документов? Инженер ведёт машину агентов на vibecoding.ru. Исполнитель получает запись правил вместо устных договорённостей.

На публичной странице /open стоят 387 тысяч строк спеков против 391 тысячи строк кода. Страницу просмотрели 7 октября 2026; это её опубликованный показатель.

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

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

В курсе «Агентная разработка»есть урок «Руль, окно и сторож». Документы задают замысел, пульт показывает состояние, проверки замечают расхождение.

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

Инструкция не гарантирует исполнения. У Anthropic она задаёт контекст, а не принудительную настройку. Проверяемое требование полезно закрепить тестом.

Наш файл правил для агентовзадаёт порядок работы. Связи с входом и проверками мы добавляли после расхождений. Вот три записи машины.

Как не получить устаревшее описание? Включить его в очередную правку. При смене поведения меняются правило, реализация и способ проверить результат.

Агент поможет описать текущее устройство по коду. Но ошибку он тоже способен описать как норму. Как должно быть, решает ответственный за продукт.

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

Как оценить описание без чтения кода? Попросить исполнителя показать изменённое правило и проверку поведения. Название документа ничего не доказывает.

Возьмём образец требования к форме заявки, не историю клиента. Фраза «форма работает» оставляет непонятным, что считается успешной отправкой.

Из описания ниже можно собрать поручение. Порядок постановки задач агенту разобран отдельно. Здесь проверяем связь поручения с правилом.

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

Попросите указать, что проверено и что осталось спросить у бизнеса. Фраза «агент всё задокументировал» не закрывает эти вопросы. Нужен ваш ответ.

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

Если хотите определить, чего не хватает вашей разработке, начните с теста для руководителя. Он даёт следующий шаг для вашей ситуации.

На странице разработки по подписке есть сценарий «Программист пропал» с файлом «Как устроен ваш код.md». Его состав виден до заказа.

Тариф «Один проект» стоит 250 000 ₽ в месяц на 7 октября 2026. Он включает один продукт с одним потоком работы.