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

Почему теперь нужно объяснять подробнее

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

Их аргументы, как правило, строятся на двух распространённых заблуждениях:

• Заблуждение 1: техническая документация проще кода, который по ней создаётся.
• Заблуждение 2: написание документации по своей сути более вдумчиво, чем написание кода.

Ниже я покажу на примерах, почему эти утверждения не выдерживают критики.

Завуалированный код

Возьмём проект Symphony от OpenAI — оркестратор агентов, который, по заявлению разработчиков, был сгенерирован на основе технической спецификации (файл SPEC.md).

Однако сама «спецификация» выглядит не как описание требований, а как псевдокод, записанный в Markdown. Например, в ней содержится текстовое описание схемы базы данных:

4.1.6 Live-сессия (метаданные сеанса работы с агентом)
Состояние, отслеживаемое, когда запущен подпроцесс ИИ-агента.
Поля:
session_id (строка, <thread_id>-<turn_id>)
thread_id (строка)
turn_id (строка)
codex_app_server_pid (строка или null)
...

Или описание логики многопоточности:

8.3 Управление многопоточностью
Глобальный лимит: available_slots = max(max_concurrent_agents - running_count, 0)
Лимит на состояние: max_concurrent_agents_by_state[state] если есть (ключ состояния нормализован)
в остальных случаях использовать глобальный лимит
Среда выполнения подсчитывает задачи по их текущему отслеживаемому состоянию в словаре running.

Есть даже разделы, явно добавленные для управления генерацией кода:

6.4 Список полей конфигурации (памятка)
Этот раздел намеренно расширен, чтобы агент мог быстро реализовать слой конфигурации.
tracker.kind: строка, обязательная, сейчас linear.
tracker.endpoint: строка, по умолчанию https://api.linear.app/graphql, когда tracker.kind=linear…

А в некоторых местах приведён код, почти дословно:

16. Образцы алгоритмов (безразличные к языку)
16.1 Запуск сервиса

Такой документ — не альтернатива коду. Это уже код, только замаскированный под спецификацию.

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

Технические документы проще кода, который по ним создаётся

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

Перевод коммуникации между машиной и человеком на родной язык последнего мало того что приведёт к значительному увеличению нагрузки на первую, но и вовсе не гарантирует, что жизнь человека станет проще. Греческая математика зашла в тупик, потому что оставалась в рамках устного и начертательного подхода. Мусульманская «алгебра» загнулась, вернувшись к риторическому стилю. А современный мир смог развиться только когда Западная Европа освободилась от оков средневековой схоластики — тщетной попытки достичь точности с помощью слов.

Инженерная точность требует символьных систем — кода. Можно лишь переупаковать эту работу, но не избежать её.

Нестабильность генерации

Даже если спецификация подробна, это не гарантирует корректной генерации кода. Я попробовала воспользоваться подходом из README Symphony:

Реализуй Symphony в соответствии со следующим техническим документом: https://github.com/openai/symphony/blob/main/SPEC.md

Попросила Claude Code создать реализацию на Haskell. Результат оказался неработоспособным: код содержал ошибки, а сам агент зависал на простых задачах, например:

Создай новый пустой репозиторий. Не нужно создавать проект GitHub. Просто создай пустой репозиторий git.

Это показывает: даже при подробной спецификации генерация кода нестабильна. «Тщетная попытка обеспечить словесную точность» (по Дейкстре) не заменяет код.

Проблема не в Symphony. Даже у стандарта YAML, с его детальной спецификацией и тестами, большинство реализаций не полностью соответствуют описанию.

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

Создание спецификации должно быть более вдумчивым, чем написание кода

Это утверждение тоже спорно. На практике составление спецификаций часто превращается в формальность. Цель — быстрее запустить продукт, а не вдумчиво проанализировать архитектуру.

Вот фрагмент из раздела 10.5 спецификации Symphony:

Контракт расширения linear_graphql:
Назначение: выполнить сырой GraphQL-запрос к Linear или мутацию, используя настроенную в Symphony авторизацию трекера для текущей сессии.
Доступность: имеет смысл, только когда tracker.kind == "linear", и настроена валидная аутентификация Linear.
Предпочтительная форма ввода: {"query": "single GraphQL query or mutation document", "variables": {"optional": "graphql variables object"}}
...

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

Такой «слоп» возникает, когда приоритет — скорость, а не качество. Даже если писал человек, результат будет поверхностным.

Заключение

Спецификации не были призваны экономить время. Если вы оптимизируете под скорость — пишите код сразу.

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

Эта статья, по сути, родилась как развёрнутая версия фрагмента комикса, который вы видите выше.

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

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

Все встреченные мной аргументы сторонников этой идеи обычно опираются на два распространённых заблуждения:

• Заблуждение 1:техническая документация проще кода, который по ней создаётся.

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

• Заблуждение 2:написание документации должно быть более вдумчивым, чем написание кода.

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

И ниже я на конкретных примерах распишу, почему считаю эти заявления заблуждениями.

Завуалированный код

Начну с проектаSymphonyкомпании OpenAI, который преподносится как пример проекта, сгенерированного на основе технической документации.

Symphony — это оркестратор агентов, который по заявлениям его разработчиков был сам сгенерирован из «специцикации» (SPEC.md). Я специально взяла «спецификацию» в кавычки, так как представленный файл больше походит на псевдокод в Markdown. Если заглянуть в этот документ поглубже, то мы увидим, что он содержит, например, текстовое описание схемы базы данных:

4.1.6 Live-cессия (метаданные сеанса работы с агентом)Состояние, отслеживаемое, когда запущен подпроцесс ИИ-агента.Поля:session_id(строка,-)thread_id(строка)turn_id(строка)codex_app_server_pid(строка или null)last_codex_event(строка/перечисление или null)last_codex_timestamp(временная метка или null)last_codex_message(краткое содержание)codex_input_tokens(целое число)codex_output_tokens(целое число)codex_total_tokens(целое число)last_reported_input_tokens(целое число)last_reported_output_tokens(целое число)last_reported_total_tokens(целое число)turn_count(целое число)Количество запусков агента за время работы текущего воркера.

…Или текстовое описание кода:

8.3 Управление многопоточностьюГлобальный лимит:available_slots = max(max_concurrent_agents - running_count, 0)Лимит на состояние:max_concurrent_agents_by_state[state]если есть (ключ состояния нормализован)в остальных случаях использовать глобальный лимитСреда выполнения подсчитывает задачи по их текущему отслеживаемому состоянию в словареrunning.8.4 Повторные попытки и увеличение задержкиСоздание записи о повторной попытке:Сбросить существующий таймер повтора для той же задачи.Сохранить попытку, идентификатор, ошибку,due_at_msи дескриптор нового таймера.Формула использования задержки:Обычные повторные попытки после корректного завершения воркера выполняются с фиксированной задержкой в 1 000 мс.Повторные попытки, вызванные сбоем, выполняются с задержкой, вычисляемой по формулеmin(10000 * 2^(attempt - 1), agent.max_retry_backoff_ms).Максимальная задержка повтора ограничивается установленным значением (по умолчанию 300000 / 5 м).Обработка поведения повторов:Получение активных кандидатов-задач (не всех задач).Поиск конкретной задачи поissue_id.Если не найдена, освободить её.Если найдена и всё ещё среди кандидатов:При наличии доступных слотов запустить.В противном случае вернуть в очередь с сообщением об отсутствии свободных слотов оркестратора.Если найдена, но уже неактуальна, освободить.

… Или разделы, добавленные конкретно для тонкого контроля генерации кода моделью:

6.4 Список полей конфигурации (памятка)Этот раздел намеренно расширен, чтобы агент мог быстро реализовать слой конфигурации.tracker.kind: строка, обязательная, сейчасlinear.tracker.endpoint: строка, по умолчаниюhttps://api.linear.app/graphql, когдаtracker.kind=linear…

… Или непосредственно код1:

16. Образцы алгоритмов (безразличные к языку)16.1 Запуск сервиса

Мне кажется, несправедливо позиционировать такой подход как альтернативу коду, когда по факту технический документ уже читается как код (а местами им и является).

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

Этот пример я привела, так как, на мой взгляд, Symphony хорошо отражает первое заблуждение:

Технические документы проще кода, который по ним создаётся

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

Дейкстра писал, почему это неизбежно:

Теперь мы знаем, что выбор интерфейса — это не просто распределение (фиксированного объёма) труда, поскольку сюда необходимо прибавить работу, связанную с взаимодействием через этот интерфейс. Мы также поняли — и это развеяло наши иллюзии — что изменение интерфейса может легко увеличить объём работы с обеих сторон (и порой намного). Отсюда и предпочтение так называемых «узких интерфейсов». Поэтому перевод коммуникации между машиной и человеком на родной язык последнего мало того что приведёт к значительному увеличению нагрузки на первую, но и вовсе не гарантирует, что жизнь человека станет проще.Если оглянуться на историю математики, то мы увидим обоснования для такого сомнения. Греческая математика зашла в тупик, потому что оставалась в рамках устного и начертательного подхода. Мусульманская «алгебра» после робкой попытки перейти к символике загнулась, вернувшись к риторическому стилю. А современный цивилизованный мир смог развиться — к худшему или лучшему — только когда Западная Европа освободилась от оков средневековой схоластики (тщетной попытки достичь точности с помощью слов.) Всё благодаря тщательным, или как минимум сознательно выстроенным системам символов, которыми мы обязаны таким фигурам, как Виета, Декарт, Лейбниц и позднее Буль.

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

Нестабильность

К тому же, генерация кода на основе спецификаций не гарантирует его надёжной работы! Я даже попробовала использовать подход, предложенный вREADMESymphony:

Попросите ИИ-агента создать Symphony на любом языке программирования:

Реализуй Symphony в соответствии со следующим техническим документом:https://github.com/openai/symphony/blob/main/SPEC.md

Я попросила Claude Code разработать Symphony на языке Haskell2, и ничего толкового не вышло. Результат можете посмотреть в моём репозиторииGabriella439/symphony-haskell repository.

В коде не только присутствовало множество багов (которые я потом просила Claude исправить, и все эти исправления есть в истории коммитов), но даже когда что-то «работало» (то есть не было сообщений об ошибках), агент просто молча, без какого-либо прогресса, зависал над следующим тикетом Linear:

Создай новый пустой репозиторийНе нужно создавать проект GitHub. Просто создай пустой репозиторий git.

Иными словами, «тщетная попытка обеспечить словесную точность» (говоря словами Дейкстры) всё равно не приводит к надёжной генерации рабочей реализации.3

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

Разработчики Symphony могли бы попробовать исправить эту нестабильность, расширив спецификацию, но она и без того длинная — примерно 1/6 от размера реализации на Elixir. Если продолжить её расширять, то получится как в истории Борхеса «О точности в науке»:

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

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

Тогда почему же я называю следующее утверждение заблуждением:

Создание спецификации должно быть более вдумчивым, чем написание кода

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

На деле спецификация Symphony читается как сгенерированный ИИ слоп. Особо ярким примером этого являетсяРаздел 10.5. Вот его фрагмент:

Контракт расширенияlinear_graphql:Назначение: выполнить сырой GraphQL-запрос к Linear или мутацию, используя настроенную в Symphony авторизацию трекера для текущей сессии.Доступность: имеет смысл, только когдаtracker.kind == "linear", и настроена валидная аутентификация Linear.Предпочтительная форма ввода:{"query": "single GraphQL query or mutation document","variables": {"optional": "graphql variables object"}}запрос должен быть непустой строкой.запрос должен содержать ровно одну операцию GraphQL.переменные необязательны, и при их наличии должны являться объектом JSON.Реализации могут дополнительно принимать сырую строку GraphQL-запроса в качестве сокращённого ввода.Выполнять по одной операции GraphQL за вызов инструментов.Если переданный документ содержит несколько операций, отказать в вызове инструмента по причине недопустимого ввода.ВыборoperationNameнамеренно вынесен за рамки этого расширения.Повторно использовать установленную конечную точку Linear и параметры аутентификации из активной конфигурации рабочего потока/среды выполнения Symphony; не требовать от агента считывания сырых токенов с диска.Семантика результата инструмента:успешный транспорт + отсутствие ошибок GraphQL верхнего уровня ->success=trueприсутствуют ошибки GraphQL верхнего уровня ->success=falseс сохранением тела ответа GraphQL для отладкинедопустимый ввод, нет авторизации или сбой при транспорте ->success=falseс содержанием ошибкиВернуть ответ GraphQL или содержание ошибки в виде структурированного вывода инструмента, который модель сможет проанализировать в рамках сессии.

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

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

Заключение

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

Если говорить в более общем ключе, то здесь применяется известный принцип «мусор на входе — мусор на выходе» (garbage in, garbage out, GIGO). Просто нет такой реальности, где вы можете скормить агенту документ, в котором не хватает деталей и ясности, и ожидать от него качественного восполнения этих пробелов. Агенты не умеют читать наши мысли, и даже если научатся, этого будет недостаточно, когда в самой голове неразбериха.

• Я специально не стала форматировать этот фрагмент кода, чтобы сохранить Markdown-формат в стиле GitHub, в каком этот код приводится в оригинальном документе. Все подобные фрагменты оформляются как прямой текст (один из многих признаков, что они сгенерированы ИИ). По факту это является примером того, что модель воспринимает документ буквально, не улавливая суть изложенного запроса. Уверена, было как-то так: человек попросил ИИ преобразовать изначальный набросок проекта в текстовую спецификацию, и ИИ решил, что форматирование фрагментов кода в таком виде делает их более текстовыми.↩
• Мне многие пишут «результат был бы качественней, если бы ты попросила сгенерировать его на более популярном языке, а не Haskell». На что я отвечаю: «Если у агента сложности с генерацией кода на Haskell, это говорит о его неспособности уверенно обобщаться на данные, выходящие за рамки обучающей выборки».↩
• Если вам кажется, что я что-то сделала не так, можете повторить эксперимент сами.↩