От Vibe Coding к разработке, основанной на спецификациях.

Путешествие от идеи до работающего фитнес-приложения, длившееся 4,5 часа, с участием агентов LLM.

Делиться

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

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

Вокруг концепции «вайб-кодирования» было много шумихи, но, похоже, профессиональные инженеры уже отходят от неё и всё больше склоняются к разработке, основанной на спецификациях. Даже Андрей Карпати, который в феврале 2025 года ввёл термин «вайб-кодирование», всего год спустя признал, что эта эпоха подходит к концу и мы вступаем в эру агентной инженерии — управления агентами на основе подробных спецификаций под контролем человека.

Сегодня (спустя год) программирование с использованием LLM-агентов все чаще становится стандартным рабочим процессом для профессионалов, но с более строгим контролем и тщательностью. Цель состоит в том, чтобы извлечь выгоду из использования агентов, не жертвуя при этом качеством программного обеспечения. Многие пытались придумать для этого более подходящее название, чтобы отличить его от vibe-кодирования, и лично мне сейчас больше всего нравится «агентная инженерия»:
– «Агентный» потому, что по умолчанию в 99% случаев вы не пишете код напрямую, а управляете агентами, которые это делают, и осуществляете надзор.
– «Инженерное дело» используется для того, чтобы подчеркнуть, что в нем есть искусство, наука и экспертные знания. Это то, чему можно научиться и в чем можно совершенствоваться, и это имеет свою собственную глубину, совершенно иную.

В этой статье я хотел бы применить подход разработки, основанный на спецификациях, на практике в новом проекте, следуя лучшим практикам из курса JetBrains по DeepLearning.AI «Разработка, основанная на спецификациях, с использованием программных агентов».

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

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

Программирование, основанное на атмосфере, против разработки, ориентированной на спецификации.

Многие из нас уже знакомы с методом кодирования Vibe: вы пишете короткий запрос (например, «Пожалуйста, добавьте диаграмму DAU в мое веб-приложение»), ждете, пока агент внесет изменения, запускаете его локально и проверяете, соответствует ли результат вашим ожиданиям.

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

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

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

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

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

Разработка, основанная на спецификациях (Spec-Driven Development, SDD), гораздо ближе к традиционным инженерным практикам. Вместо того чтобы сразу переходить к реализации, мы начинаем с тщательного обдумывания: принятия архитектурных решений, определения требований и их документирования в структурированной спецификации в формате Markdown, хранящейся в репозитории и обновляемой по мере развития проекта. Это создает важный сдвиг: мы отделяем спецификацию (что мы создаем и почему) от реализации (фактического кода).

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

Рабочий процесс SDD

Типичный рабочий процесс разработки, основанный на технических характеристиках, обычно состоит из следующих этапов.

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

• В разделе «Миссия» объясняется «почему»: зачем мы создаем этот проект, каковы его ключевые цели и особенности?
• В документе Tech Stack описываются технические решения, а также процессы развертывания и обновления.
• Дорожная карта описывает этапы проекта, запланированные функции и постоянно обновляется по мере развития проекта.

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

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

1. Понимание того, что мы хотим создать, и составление подробной технической спецификации.
2. Внедрение изменений.
3. Проверка корректности работы реализации.

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

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

Теперь, когда мы рассмотрели теорию, давайте применим её на практике.

Здание

Довольно теории, пора приступать к разработке. Чтобы лучше понять, как разработка, основанная на спецификациях, работает на практике, я решил применить её к реальному проекту с нуля.

Я начал с создания нового репозитория для этого проекта (и, конечно же, потратил полчаса на выбор названия и логотипа): repository. Я также задокументировал свое первоначальное видение продукта в файле README.md .

Одно из преимуществ подхода SDD заключается в том, что он в значительной степени не зависит от выбора LLM, агента или IDE, поэтому вы можете работать с любой удобной для вас конфигурацией. Для этого проекта я буду использовать Visual Studio Code с плагином Claude Code, поскольку это позволяет мне использовать Claude в качестве агента, а также просматривать все изменения кода непосредственно в редакторе.

Создание конституции

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

 We are building Trainlytics, a personal fitness tracking web app built for people who want more control, flexibility, and insights than standard fitness apps provide. Find the full requirements in README.md. Let's create a "constitution" in a specs directory that consists of the following parts: - mission.md - what and why we are building; the main mission of the product - tech-stack.md - core technical decisions - roadmap.md - project phases broken down in implementation order IMPORTANT: You must use your AskUserQuestion tool to get my feedback.

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

В итоге агент создал три файла, которые мы запрашивали.

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

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

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

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

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

Первый этап разработки функций

Теперь пришло время перейти к первому этапу разработки функций.
Согласно нашему плану развития, мы начнем с MVP: Core Activity Logging (основная система регистрации активности). По завершении этого этапа пользователь должен иметь возможность входить в систему как на компьютере, так и на мобильном устройстве, записывать пробежку и тренировку в спортзале, а также просматривать обе записи в своей истории с подробной информацией.

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

 Find the next phase in specs/roadmap.md and create a new branch, ask me about any steps in the specs that are not fully clear. Then create a new directory in the format YYYY-MM-DD-feature-name under specs/ for this feature, with the following files: - plan.md - a structured list of numbered task groups - requirements.md - scope, key decisions, and context - validation.md - how we define success and confirm the implementation can be merged Use specs/mission.md and specs/tech-stack.md as guidance. 

Совет : стоит начать новую сессию с четким контекстом в вашем агенте LLM.

Агент довольно быстро подготовил технические условия.

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

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

 Take the next task group from 2026-05-04-phase-1-mvp/plan.md and implement it. Use requirements.md and validation.md for guidance. Once done, update the status in both the plan and validation documents.

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

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

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

После нескольких попыток с агентом нам удалось запустить приложение локально, и оно заработало. Мы уже можем добавлять различные упражнения и типы активности, а также регистрировать как кардио-, так и силовые тренировки.

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

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

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

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

После завершения всех проверок мы можем создать и объединить запрос на слияние.

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

Перепланирование

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

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

 Let's revise our plan in roadmap.md. I would prioritise the next phases as follows: 1. Strength session templates I can live without planning, but I need templates, because I often struggle to remember all the exercises in a session. The idea is: - If a template already exists in the log, show all stats (exercises, sets, reps, weight, etc.). Allow editing these values and committing changes - If anything is changed, ask whether the user wants to update the template 2. UI improvements The current design is not yet sleek enough, so I'd prioritise a round of UI improvements: - Add the logo and product motto to the website - Add a settings tab to manage activity types and exercises - Create a single screen to log both cardio and strength sessions - Improve the history screen with richer activity details - Allow adding titles to activities (strength/cardio sessions) and segments - Support specifying time, not only date - Add more color to the interface (I like shades of blue) - For cardio exercises, adjust units to: minutes, kilometers, and min/km pace 3. Basic analytics Add simple analytics to the history screen showing weekly stats at the top of the page (eg total minutes and calories split between cardio and strength).

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

Давайте попросим агента сделать это за нас.

 Please review plan.md, update roadmap.md to reflect completed work, and create a CHANGELOG.md file with a concise summary of the changes.

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

следующий этап

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

До сих пор мы писали все подсказки вручную, но эти рабочие процессы также можно автоматизировать в качестве «навыков» в Claude Code или других агентах программирования LLM.

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

Установить его можно следующим образом.

 uv tool install specify-cli --from git+https://github.com/github/spec-kit.git specify version # to check that it works

Далее необходимо инициализировать навыки в Claude. Для этого создается папка .specify/ и устанавливаются команды с косой чертой в папку .claude/commands/

 specify init . --integration claude # there are 30 integrations with agents so specify the one you're using

Вы поймете, что все получилось, когда увидите команды speckit в коде Клода.

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

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

Честно говоря, мне немного больше нравится подход, предложенный JetBrains, потому что он сохраняет больше контекста в самой структуре. Но, как всегда, универсального решения нет, и Spec Kit может работать лучше в зависимости от вашего конкретного случая. Также удобно, что у вас уже реализован рабочий процесс SDD.

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

Краткое содержание

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

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

Однако универсального подхода здесь не существует.

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

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

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

Ссылка

Данная статья вдохновлена кратким курсом «Разработка на основе спецификаций с использованием программных агентов» от DeepLearning.AI.

Мария Мансурова Посмотреть все от Марии Мансуровой

Источник: towardsdatascience.com