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

Я фрилансер. Не работаю над Enterprise проектами, не знаю как LLM себя ведут в больших разработках, командах. Все мой опыт - это проекты не более 4 месяцев по длительности, не превышали 60к строк кода.

С 2024 года, когда LLM стали (плюс/минус) пригодны для генерации кода и решения рабочих задач, я начал тащить их в свои проекты. Сначала кусками: помочь с функцией, разобрать ошибку, прикинуть архитектуру, или вообще не соглашаться на проект. Очень быстро понял: если не будет в этом процессе норм и правил - будет только бардак и проекты я буду закрывать медленнее, чем если бы писал код руками. Модель уходит в дебри, забывает решения, ломает то что работало, переписывает по сто раз одно и то же, циклы ошибок. Поэтому, я начал формулировать тезисы. Сначала в голове, потом записывать.

Полгода назад собрал это всё в полноценную методичку. На Хабре уже писал об этом подходе — там объяснял, почему это не вайбкодинг и почему я не люблю этот термин. В целом это Test + Spec Driven Development. Но доки в первую очередь.

Сейчас выпустил вторую версию, так как индустрия очень быстро движется - приходится адаптироваться. Sub-agents, MCP, context engineering, формализованные Skills — всё это уже не передовое, а становится основами разработки при помощи LLM. Мою предыдущую версию это не отменяет, фундамент тот же и он дополняется.

Полная методичка по AIDD (AI Driven Development) лежит в репозитории — технический документ со всей структурой, форматами, чек-листами и определениями. Кому копать — добро пожаловать.

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

1. Архитектурное мышление важнее кодинга

"Архитектурное мышление важнее навыков кодинга. Человек принимает решения на уровне 'что делаем и как это устроено', нейросеть решает 'как это написать в коде'."

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

Скорость генерации LLM - это плюс и минус одновременно. Если архитектурное направление выбрано правильно, модель раскатывает решение в десять раз быстрее, чем ты руками. Если неправильно - точно так же быстро раскатывает кривое решение, но это уже не баг в одной функции! Это раздувание неправильного направления как опухоли. За день модель напишет тебе на полпроекта кода, который придётся перерабатывать.

Архитектура не "по-прежнему важна", а она стала точкой отказа. Чем сложнее проект - тем с большей скоростью LLM уйдет в неверном направлении.

2. AIDD не работает без человека-оркестратора

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

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

AIDD это противоположность: человек принимает решения, выстраивает структуру, определяет границы, проверяет результат. LLM - мощный инструмент, скорее даже - УСИЛИТЕЛЬ. Но решение какой контекст подать, как поделить работу между агентами, где провести границы модулей - это не делегируется. Структурно, а не "пока модели слабые". Мне нравится термин усилитель - так как LLM именно усиливает навыки разработчика. Если у него есть глубокое понимание чем он занимается и как оно должно работать - эти сильные стороны будут усилены (извиняюсь за однокоренные). Но так же - если у человека есть пробелы в знаниях, ошибочное видение архитектуры, халатное отношение к производству - отрицательные черты так же будут УСИЛЕНЫ

Можно ли без понимания архитектуры сделать продукт через LLM? Можно. Маленький, простой, с ограниченной логикой. Лендинг, минибот, сценарий из трёх шагов. Это и есть вайбкодинг. Работает ровно до того уровня, пока сложность не вылезет за пределы того, что модель удерживает сама. У меня есть опыт, где заказчики на середине пути со мной попрощались (спустя 4 месяца разработки) и решили что они дальше сами справятся при помощи Клода и Кодекса. Ну и ладно. Но спустя 3 месяца тишины - они вернулись и поняли что были не правы. Успели наклепать около 10 ботов и 3 сайта SaaS. Но архитектура, методы деплоя, устройство серверов - на нулевом уровне.

Про скорость разработки: я пользуюсь трекингом времени - по часам каждый проект и отдельные его части. За год я собрал статистику и пришел к выводу, что при адекватном подходе LLM ускоряет доставку проекта до заказчика от 3 до 5 раз. Зависит от типа проекта, количества ручного тестирования. 

Без человека никак. Не потому что модели плохие, а потому что задача "понять, что пошло не так в архитектуре системы" требует понимать систему. Модель видит свой контекст. Человек видит проект.

3. Никакого кода в спеке. Включая псевдокод

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

Раньше казалось — ну напишу for user in users: if user.active..., типа намекну что я имею в виду. Просто пример, не настоящий код.

Нельзя!

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

Дальше начинаешь подправлять. Модель думает что её псевдокод правильный (ты же его написал!) и сопротивляется изменениям. Приходится ругаться, объяснять и тратить время на упертого матричного джуна.

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

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

Наша работа - описать намерение, а у LLM - реализовать. У них нет намерения)

4. Контекст ограничен

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

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

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

И тут ещё момент. Если есть длинная стабильная спека, которая редко меняется — её можно кэшировать через prompt caching! Современные API это поддерживают, и неизменная часть промпта перестаёт пересчитываться при каждом запросе, на длинных проектах разница ощутимая.

5. Не трогать работающее. Все LLM хотят улучшать

"Без этого указания нейросеть почти всегда начинает 'улучшать' и 'адаптировать' старый код. Это недопустимо."

Все LLM хотят что-то улучшить. Ну вот без разницы — Opus, Sonnet, Codex, GPT-5, Gemini. Все! Они находят какие-то тонкости в соседнем коде и начинают его переписывать. "Я тут заодно отрефакторил", и эти улучшения начинают идти как лавина!

Это раздувает всё подряд. А раздувание кода — больше шансов на нестыковку. Раздувание контекста — меньше места под актуальную задачу. По итогу просто добавление еще одного middleware превращается в переделку трёх соседних модулей, которые до этого нормально ОТЛИЧНО. Поэтому навязанное исповедание минимализма! Минимализм кода и формулировок. Минимализм изменений. Чем меньше LLM трогает — тем меньше места, где что-то может сломаться.

Это надо проговаривать моделям явно, конкретно. Каждый раз. "Ты добавляешь новую функцию. Существующий код не меняешь. Там всё работает." Без этого — найдёт повод залезть. Они пытаются быть полезными умницами, но слишком сильно пытаются...

6. Sub-agents: изоляция по модулям важнее изоляции по ролям

"Изоляция по модулям важнее, чем изоляция по ролям."

Это уже про вторую версию методички. В первой я писал про разделение по ролям — архитектор, разработчик, фиксер. Для каждого создаю свой чат, свой контекст и задачи. Правильно для одного агента в моменте. Но индустрия пошла дальше, и я тоже. Параллельные sub-agents — норма. Запускаешь несколько одновременно, они работают независимо, а вот Claude Code уже сам их запускает, по 3-4 агента. Тут роль перестаёт быть главным критерием изоляции. Главным становится модуль.

Один модуль = один агент в моменте. Два агента не должны параллельно копаться в одном модуле, пусть даже у них разные роли. Это гарантированный конфликт — пока один пишет, другой меняет под ним основу, архитектор адаптирует доки, а там уже возникли новые ошибки (или наоборот - решения). На больших модулях — платежи, сложные внешние интеграции, что-то с серьёзной архитектурой — допустимо пускать цепочку из разных ролей. Сначала архитектор спроектировал, потом кодер реализовал. Но последовательно, не параллельно - один за другим.

На простых вещах вроде небольшого бота с парой хэндлеров — не заморачиваемся. Один агент справится.

Решение нельзя делегировать модели! Вообще! Где границы модулей, какие задачи реально параллелятся, кого с кем не сводить — это архитектурная работа человека.

7. Параллельность умножает не только скорость, но и ошибки

"Параллельность умножает не только скорость, но и масштаб ошибок. Без человека-оркестратора три агента создадут проблем втрое больше, чем один."

Соблазнительно подумать "запущу пять агентов и буду в пять раз быстрее". Это очень... ПРОБЛЕМАТИЧНО. И не из-за моделей, а из за человека - у него так же есть лимит на внимание и контекстное окно.

У меня комфортный потолок — три параллельных окна. Три ещё нормально удерживаю: помню кто над чем работает, какая ошибка где обсуждалась, что в каком окне уже решили. Если же четвёртое — тогда я уже начинаю плыть. Пишу агенту "помнишь, мы вот ту ошибку с авторизацией решали?" — а он не помнит. Потому что мы её в другом окне решали с другим агентом)

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

Мозг человека однопоточен в решении задач. Ему нравится делать сразу несколько дел ради самоудовлетворения продуктивностью, но это иллюзия. Свой потолок надо знать.

8. Context engineering vs Prompt engineering

"Prompt engineering — это уровень предложения. Context engineering — уровень архитектуры взаимодействия."

Разные дисциплины, которые часто путают.

Prompt engineering — про то, как сформулировать одно сообщение модели. Чтобы оно было однозначным, чётким, без воды. Короче, уровень отдельного запроса.

Context engineering — про управление всем окном на длинной дистанции. Что грузить, что выгружать, как разбивать между агентами, когда чистить, как кэшировать. Уровень архитектуры взаимодействия с моделью на протяжении всего проекта.

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

Еще из серии про промпты и контекст — общаться с LLM на английском. Все большие модели обучены на массиве интернета, который преимущественно англоязычный. Качество ответов и сгенерированного кода выше - это просто статистика обучающей выборки.

Туда же — минимализм формулировок. Не лить воду, не добавлять "если можешь, пожалуйста, постарайся". Модель не обижается (вероятно).
Чёткая короткая инструкция работает лучше длинной вежливой просьбы.
Хотя я в прошлом году читал статью про то, что вежливость общения с LLM повышает продуктивность на 30%.

9. Слепая зона: тесты клиентской стороны

"LLM прекрасно покрывает тестами backend, базу, очереди, внешние интеграции. Но почти никогда не покрывает хэндлеры самого бота."

Регулярно сталкиваюсь с проблемой отсутствия тестирования клиентской стороны! Test Driven Development - это одна из осей, на которых держится качество проекта. Не потому что, тесты тестируют корректность поведения, а потому что тесты - это якорь истинности для LLM. 

И вот мой опыт: делаю телеграм-бота, LLM сама пишет тесты на бэкенд, на работу с PostgreSQL, на Redis, на Celery, на внешние API. Показывает требуемое (мною) покрытие в 75%. А вот хэндлеры самого бота - обработка команд, FSM, реакции на кнопки — без тестов. Просто пропускает нагло. И по итогу я требую от него реальное покрытие и вижу - 22%.

С небольшими веб-сервисами иногда то же самое. С мобильными приложениями интересный паттерн: тесты "глобальной работы функций" модель пишет, а тесты на конкретные кнопки и переходы - увы! То есть всё что точечное и приземлённое, с чем человек реально взаимодействует руками - пропускается. Что глобальное и абстрактное - покрывается.

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

Что делаем - явно прописываем в спеке этапа, какие тесты должны быть, включая клиентскую сторону. Не полагаемся на дефолтное поведение модели! она по дефолту туда не пойдет.

В методичке у меня в шаблоне phase-N.md теперь есть отдельный раздел "План тестирования" - без него LLM закрывает бэк и кажет вам: "ГОТОВО".

10. MCP не заменяет ручную проверку. Это двусторонняя проблема

"MCP не заменяет ручную проверку. LLM через MCP всё равно пропускает вариации и второстепенные элементы."

Я делал мобильное приложение на Flutter, подключил Figma через MCP, с таким посылом: пусть LLM сама считает макеты и сверстает экраны. Это экономит время, не приходится вручную тыкать каждый компонент. Я конечно не фронтэндер, я уверен, что не знаю основных фич по верстке, но просто рассказываю о своем опыте.

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

У меня нетривиальный взгляд на проблему. Так как сама проблема двусторонняя.

Да, LLM ещё не научились хорошо работать с такими источниками, возможно, MCP-сервер для Figma настроен не оптимально. Это вопрос технологии.

Но ещё вопрос — а готовы ли сами Figma-макеты к тому, чтобы их через LLM считывали? Раньше дизайнер думал "как макет передать разработчику-человеку": Человек разберётся с любой структурой - поковыряется во фреймах, поймёт что главное, что вариация и где модалка. У LLM такой гибкости пока нет - ей нужна структура макета, заточенная под автоматическое чтение.

Это новая компетенция, которая ещё не сформировалась, дизайнеры скоро должны будут учиться делать Figma так, чтобы она нормально переносилась через MCP. Так же как разработчики научились писать спеки, заточенные под LLM. 

Аналогия - как сейчас все больше требуется оптимизация SEO-части сайтов именно под поиск нейросетями. Так же сдвиг парадигмы.

Коротко про Skills

В методичке у меня три типа Skills. Короткий и важный момент:

  1. Самописные slash-команды (/discover, /implement, /fix). Хранишь в .claude/commands/, переезжают с проектом. Твои инструменты под твои процессы.

  2. Anthropic Skills как формальный механизм. Уже не просто промпт, а пакет из инструкций, кода и ресурсов, который агент подгружает автоматически. Ну для случая именно Claude Code. 

  3. Готовые из реестров. Имеет смысл искать готовое, прежде чем писать своё, адаптировать под текущий проект, контекст.

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

Итог: ответственность всегда на человеке

"Воспроизводимость = Полнота документации × Покрытие тестами × Качество декомпозиции × Дисциплина человека. Если любой множитель близок к нулю — воспроизводимость стремится к нулю."

В первой версии методички формула была из трёх множителей. Я добавил четвёртый — дисциплину человека.

Всякие sub-agents, MCP, Skills, верификации, разделения по модулям — это же просто инструментарий. Полезный, реально ускоряет работу в разы, однако работает только пока человек держит ответственность за результат.

Можно поставить агента на blue team в кибербезе — модели уже это умеют, как и в атаке, но если случится утечка — отвечать же будет не агент, а человек, который его поставил. Можно сделать классную аналитику с RAG, она будет давать рекомендации, и часто правильные. Но заказчики хотят работать с человеком. Потому что с человека можно спросить. С LLM спросить нельзя — это умножение матриц, не больше и не меньше.

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

Спрос будет именно с разработчика.

Еще раз: полная методичка — тут. А в канале - всякий поток сознания.