Времена меняются, и известное изречение Линуса Торвальдса «Talk is cheap. Show me the code» сегодня можно переформулировать: «Code is cheap. Show me the spec». Меня зовут Алекс Гусев, и я хочу объяснить, почему теперь именно спецификация, а не код, становится главным артефактом разработки.

Agent Driven Software Management и Spec-Driven Development

Я разрабатываю подход под названием ADSM (Agent Driven Software Management), который формализует мой личный опыт в методологию Spec-Driven Development (SDD). В рамках этой публикации я покажу, как SDD в виде ADSM применяется к созданию простого приложения — помощника по формированию плейлистов в Spotify.

Также я продемонстрирую, что происходит, когда один и тот же агент (Codex, GPT-5.4) генерирует код на основе одной и той же спецификации, но с разным уровнем reasoning: high, medium и low.

Предыстория: от идеи к автоматизации

Для семейного мероприятия понадобился плейлист на 4–5 часов. ChatGPT успешно составил список из 100 треков — с названиями и исполнителями. Оставалось только перенести их в Spotify. Раньше это делалось вручную, но теперь такие задачи легко автоматизировать с помощью ИИ-агентов.

Я не пишу «вайбкод», но зато практикую SDD. На создание первой версии приложения ушло чуть больше двух часов чистого времени.

До начала проекта я не знал о возможностях API Spotify. ChatGPT подсказал ссылку developer.spotify.com и объяснил, как зарегистрировать приложение.

Оказалось, что аутентификация реализуется через OAuth. Для этого нужен домен и TLS-сертификат. Домен был, сертификат — через Let’s Encrypt. Я пишу только на JavaScript, поэтому выбор языка и платформы был очевиден: TeqFW.

Разработка с агентом

Я создал приватный репозиторий на GitHub, склонировал его локально и добавил в контекст (./ctx/spec/) типовые шаблоны для node.js-приложений на основе библиотеки @teqfw/di.

Час я провёл в диалоге с Codex-агентом в VSCode: обсуждали запуск, конфигурацию, зависимости. Агент фиксировал всё в контексте проекта (./ctx/docs/).

Затем я попросил агента создать:

• package.json;
• bootstrap-файл ./bin/cli.mjs;
• головной скрипт ./src/Main.mjs.

После этого — две итерации:

1. Интеграционные тесты и код для получения и сохранения токена аутентификации через веб-сервер.
2. Загрузка и парсинг текстового файла с треками, поиск в Spotify и создание плейлиста (всё с интеграционными тестами).

Соответствие формату ES6-модулей я проверял с помощью скилла teq-esm-validator.

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

Детерминированность: не кода, а функционала

В комментариях на Хабре часто звучит мнение, что LLM-агенты неприменимы, потому что не дают детерминированного результата. Но программирование всегда было отчасти искусством.

«Детерминированность результата» ≠ «Детерминированность кода»

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

Эксперимент: три версии, один контекст

Я опубликовал код, созданный агентом (GPT-5.4, high reasoning) — версия 1.0.0. Контекст я намеренно удалил.

Затем попросил того же агента (но с уровнем reasoning medium) удалить папки ./src/ и ./test/ и, на основе неизменного контекста из ./ctx/, сгенерировать код с нуля — версия 2.0.0.

То же самое — с low reasoning: версия 3.0.0.

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

Результат: код во всех трёх версиях разный. Но приложение работает одинаково.

Ошибки и их детерминированность

Все три версии «затупили» при добавлении треков в плейлист. Dry-запуск проходил успешно, треки находились, но при добавлении агент использовал устаревший API Spotify. Пришлось вручную указывать на ошибку — трижды.

Если бы я не стремился к чистоте эксперимента, я бы добавил в контекст требование использовать новый API. Но я сознательно оставил контекст неизменным. Это показало: ошибки в прочтении контекста тоже детерминированы.

Третья версия (low reasoning) не смогла корректно запустить веб-сервер: он стартовал, но приложение сразу его останавливало, не дожидаясь получения токена. На уровнях high и medium такой проблемы не было.

Объём контекста vs объём кода

Я потратил месяцы на создание спецификаций для своего стиля разработки (./ctx/spec/code/platform/teqfw/). Эта документация переиспользуется во всех моих проектах.

На описание конкретного продукта ушло пара часов. А на генерацию кода каждой версии — около 10 минут. При этом на каждую версию уходило примерно 4% недельной квоты plus-подписки ChatGPT.

Соотношение объёма контекста и кода впечатляет:

• Файлы в ctx: 53
• Каталоги в ctx: 15
• Строк в ctx: ~10 000
• Файлы в src (v1–v3): 18–23
• Строк в src: ~1 500

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

Скиллы как корректоры поведения агента

Моя платформа TeqFW использует позднее связывание: все зависимости внедряются через конструктор. В ./src/ нет ни одного статического импорта — это нетрадиционный подход, и агенты с ним справляются плохо.

Когда агенты упорно генерировали код со статическими импортами, я создал скилл teq-esm-validator — тоже с помощью Codex по методологии ADSM. Теперь достаточно указать в промпте: «используй скилл» — и проблема почти исчезает.

Заключение: код как производный артефакт

Я сравниваю поведение LLM-агентов с дождевой водой: она течёт по рельефу, собирается в ручьи и стремится к океану. Агент идёт по пути наименьшего сопротивления.

В этой аналогии:

• Контекст — плотины и каналы;
• Скиллы и тесты — насосы и шлюзы, поднимающие воду на новый уровень.

Основные затраты — на построение инфраструктуры. Но зато потом вода (код) почти всегда попадает туда, куда нужно.

Код — не конечный продукт. Это производный артефакт взаимодействия когнитивного контекста и агента.

Именно поэтому контекст проекта (53 файла в ./ctx/) важнее кода (18–23 файла в ./src/). Когда есть контекст, агент сгенерирует нужный код за минуты — даже для экзотической платформы вроде TeqFW.

Код всех трёх версий — дешёв. Изучайте его. А если хотите увидеть контекст — пишите в личку. Дам бесплатно, в обмен на обратную связь о применимости подхода в ваших проектах.

И немного прекрасного

ИИ-агенты легко генерируют «бойлерплейт» и делают ненужными тонны зависимостей в node_modules.

Они спокойно хардкодят Web API и перехардкодят при изменениях. В моём приложении всего:

• 2 зависимости для runtime (мои библиотеки);
• 2 зависимости для dev-режима (типы Node.js).

В наше время известное изречение Линуса Торвальдса "Talk is cheap. Show me the code." можно переиначить в виде "Code is cheap. Show me the spec." Меня зовут Алекс Гусев и в этой публикации я постараюсь показать, почему я так считаю.

У меня есть несколько статей на Хабре, объединённых общей темой:ADSM(Agent Driven Software Management). По сути, это моя попытка формализовать свой личный опыт в Spec-Driven Development (SDD) в какое-то подобие методологии. Под катом я поделюсь результатами применения SDD-подхода (в его ADSM виде) к разработке простого приложения - помощника в создании плейлистов в Spotify. И покажу, что будет, если на базе одного и того же контекста (спецификации) сгенерировать код одним и тем же агентом (Codex, GPT-5.4) с разным уровнем reasoning'а (high, medium, low).

Предыстория

Нам для одного из семейных мероприятий понадобился плейлист на 4-5 часов на определённую тему. ChatGPT хорошо справился с задачей и выдал список из 100 музыкальных произведений с названиями и авторами. Оставалось сформировать плейлист для Spotify. Раньше мы делали это вручную и времени уходило порядком, но сейчас такие вещи легко поддаются автоматизации через ИИ-агентов.

Я уверен, что кто-то может навайбкодить подобное приложение за полчаса, а то и за десять минут. Но во-первых, я не умею вайбкодить, во-вторых, я умею SDDевелопить. Поэтому, на создание первой версии приложения у меня ушло 2 часа чистого времени.

До того, как я занялся реализацией этого проекта, я вообще был не в курсе о каких-либо возможностях интеграции Spotify с внешними приложениями. ChatGPT подсказал мне адресhttps://developer.spotify.com/и объяснил, что и где нужно прописать, чтобы зарегистрировать своё приложение.

Оказалось, что аутентифицироваться в Spotify нужно по протоколу OAuth. А для этого нужно иметь свой домен и TLS-сертификат. Домен у меня был, сертификат делается через Let's Encrypt. Я уже давно пишу только на JavaScript, поэтому выбор ЯП был безальтернативен. Как и выбор платформы - только TeqFW, только хардкор!

Создал приватный репозиторий на GitHub'е, склонировал на локалку. Добавил в контекст (./ctx/spec/) типовой код для nodejs-приложений на базе моей библиотеки@teqfw/di. Где-то около часа с небольшим я в VSCode обсуждал в диалоге с Codex-агентом детали будущей реализации - как запускать, как конфигурировать, какие зависимости тянуть. Агент всё это аккуратно фиксировал в контексте проекта (каталог./ctx/docs/). Затем я попросил агента создать./package.json, bootstrap-файл./bin/cli.mjsи головной скрипт приложения./src/Main.mjs. После чего попросил создать в две итерации: 1) интеграционные тесты и код для получения и сохранения токена аутентификации через веб-сервер; 2) загрузку и парсинг текстового файла с музыкальными композициями, поиск произведений в Spotify и формирование плейлиста (тоже интеграционные тесты и исходники). Соответствие формата es6-модулей требованиям своей платформы я верифицировал по скиллуteq-esm-validator.

Я проверял работу приложения по частям (каркас - просто запуск; получение токена аутентификации; разбор файла и поиск композиций; создание плейлиста и добавление в него найденных композиций). Итого, чуть больше, чем через два часа чистого времени в моём Spotify этим приложением был создан новый плейлист из 80+ композиций. Остальные композиции из списка не были обнаружены в Spotify.

Последствия

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

"детерминированность результата" != "детерминированность кода"

Для демонстрации этой идеи я опубликовал оригинальный код, созданный Codex-агентом (GPT-5.4, high reasoning) подверсией 1.0.0. Только код, контекст я специально вырезал. Затем я попросил Codex-агента (GPT-5.4, medium reasoning) удалить папки./src/&./test/и на основе того же самого, неизменённого контекста из папки./ctx/создать с нуля тесты и исходники (для экономии я оставил прежниеpackage.jsonи boostrap-файл). Получиласьверсия 2.0.0. Затем то же самое проделал на GPT-5.4, low reasoning -версия 3.0.0.

Удали все файлы из каталоговsrc,test. Подними вpackage.jsonверсию до 3.0.0. Ознакомься с документами контекста (./ctx/). Посмотри, как запускается приложение. Создай интеграционные тесты для продукта (ctx/spec/code/platform/teqfw/quality/testing/overview.md). После этого создай полнофункциональный код продукта (согласно правилам платформы TeqFW), проверь по интеграционным тестам. Проверь код вsrc/через скиллteq-esm-validator. Исправь найденные ошибки и снова проверь по интеграционным тестам. Собери юнит-тесты для проверки исходников (ctx/spec/code/platform/teqfw/quality/testing/unit.md). ОбновиREADME.mdс учётом, что это третья версия приложения, созданная агентом Codex GPT-5.4 на reasoning-уровне Low. Не надо поднимать прошлую реализацию из git-истории. Проектируй с нуля. В этом смысл этой итерации.

Вот сводка по созданным исходникам, сделанная агентом:

Файлы в src

Каталоги в src

Строк всего

Комментарии

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

У меня ушло довольно много времени (месяцы) на создание спецификаций для моего стиля разработки (./ctx/spec/code/platform/teqfw/) и я всё ещё продолжаю развитие этой документации. Но это часть контекста, переиспользуемая между всеми моими проектами. И мне потребовалось пару часов на описание продукта (создание документов в пространстве./ctx/docs/). Но на генерацию тестов и кода каждой из версий у агента ушло в районе 10 минут. И что интересно, вне зависимости от reasoning-уровня у меня ушло порядка 4% недельной квоты от plus-подписки на ChatGPT на генерацию каждой из версий.

Все три версии затупили с созданием плейлиста в Spotify. Dry-запуск они проходили и треки искались, но при попытке добавления треков в плейлист все три раза агент использовал устаревший API и приходилось ему каждый раз указывать на эту ошибку. Если бы я не старался делать более-менее чистый эксперимент, я бы внёс в когнитивный контекст требование использовать новый API от Spotify, но я специально выполнял генерацию кода на одном и том же контексте. Так что помимо детерминированности результирующего функционала также проявилась и детерминированность ошибок прочтения контекста агентом.

Третья версия, которая делалась low-reasoning агентом, не справилась с запуском веб-сервера. Вернее, справилась - веб-сервер стартовал, но приложение сразу же его глушило, не дожидаясь получения токена аутентификации от Spotify. На уровнях high & medium такой проблемы не возникло.

Для понимания соотношения объёма документов контекста (ctx) к результирующему коду (см. таблицу выше):

Файлы в ctx

Каталоги в ctx

Строк всего

Что касается объёма в байтах, то сводка такая:

Файлы в ctx

src v1 (high)

src v2 (medium)

src v3 (low)

Да, это моя осознанная позиция: документы контекста по объёму должны быть в разы больше результирующего кода.

Отдельно нужно выделить скиллы. Моя платформа использует позднее связывание исходников в момент выполнения. Все зависимости внедряются через конструктор. А это значит, что во всех файлах из каталога./src/нет статических импортов. Ни одного. Это довольно нетрадиционный подход к JS-кодированию и агенты очень плохо в него умеют.

Когда я столкнулся с упорным желанием агентов создавать классический исходный код (с ранним связыванием кода при помощи статических импортов), мне пришлось сделать свой скилл -teq-esm-validator. Его, кстати, тоже делал Codex-агент по той же методологии ADSM. После этого было достаточно в промпте указать, что нужно использовать этот скилл для проверки исходников, и проблема со связыванием очень сильно уменьшилась. По крайней мере, в этом проекте с плейлистом в Spotify она не возникла ни разу.

Заключение

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

Основные затраты в таком подходе - это инфраструктура (те самые плотины, каналы, шлюзы). Но зато потом, после создания этой инфраструктуры, вода в большинстве случаев попадёт туда, куда было задумано строителями. Код в моём представлении - это не конечный артефакт, а производный. Результат взаимодействия когнитивного контекста и агента.

Именно исходя из этих соображений я и считаю, что контекст проекта (те самые 53 файла в./ctx/), важнее самого кода (18-23 файла в./src/). Ведь когда у тебя есть контекст, агент тебе сделает нужный код в течение минут. Даже такой экзотический, как TeqFW.

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

И немножко прекрасного. ИИ-агенты спокойно вытягивают "бойлерплейт" и делают ненужными множественные зависимости в./node_modules/:

Им ничего не стоит захардкодить Web API и перехардкодить его в случае изменений. В моём приложении всего две зависимости для режима runtime (мои собственные библиотеки) и ещё две зависимости для dev-режима (разрешение типов Node.js).