В первой части я рассказал, что такое капсула и зачем упаковывать опыт. Во второй — как мы построили капсульный фреймворк для микросервисов. Если вы не читали предыдущие части, советую начать оттуда.
В этой части я покажу, что происходит, когда к капсуле подключается AI-агент. Почему жёсткая структура капсулы — это именно то, что нужно агенту. И как опыт, упакованный в капсулу, становится опытом, которым может пользоваться машина.
Что нужно агенту
Сразу уточню термин. Дальше я буду говорить «агент» — под этим словом понимаю и классического агента с циклом рассуждений, и LLM, которая лежит в его основе. Например, в разработке я чаще всего использую Claude Code и OpenCode. Какие именно модели стоят за ними — для статьи не важно. Главное: чем лучше модель, тем лучше результат.
Агентов в разработке применяют в двух режимах.
Режим первый — прототипирование. Нужно быстро проверить идею: сделать что-то работающее, не думая о нагрузке, поддержке или стеке. Такой продукт мы не планируем сопровождать. Здесь агенту не нужны правила — нужен только результат. Описываем логику, агент реализует за 10–15 минут.
Режим второй — разработка продуктов. Здесь всё иначе. Нам нужен не просто код, а продукт, который соответствует жёстким нефункциональным требованиям: его можно поддерживать, читать, масштабировать. Эти требования равны по важности бизнес-функциям — без них продукт не работает.
И здесь возникает проблема. Без структуры агент делает произвольные выборы. Он не помнит, как решал похожую задачу два дня назад. Структура сервисов начинает «расползаться» — от задачи к задаче она хаотично меняется. Сервисы перестают быть однородными. Взаимодействие между ними теряет архитектурную целостность.
Агент в этом смысле испытывает то же, что и разработчик, впервые открывший чужой проект. Ему нужно угадывать, как здесь принято решать задачи, вникать в неочевидные соглашения. У опытного разработчика есть паттерны и коллеги. У агента — нет. Каждый раз с нуля. Без правил ошибок будет намного больше.
Для разработки продуктов агенту нужен структурированный контекст. И капсулы подходят для этого идеально.
Капсула = Экспертное знание + Минимализм + Готовый инструмент
Концепция капсул появилась раньше, чем агенты стали трендом. Но формула оказалась актуальной в обоих мирах. Что каждый элемент даёт агенту:
- Экспертное знание — агент получает накопленный опыт в структурированном виде, а не угадывает его.
- Минимализм — знание в виде эссенции: решает одну конкретную проблему без лишней информации, не засоряя контекст.
- Готовый инструмент — капсулой можно просто пользоваться. У неё есть методы, скиллы, документированные интерфейсы — именно это лежит в основе современных агентов.
Одной капсулы недостаточно. У каждого проекта есть свои правила: стайлгайды, формат коммитов, особенности структуры кода. Всё это описывается в отдельных markdown-файлах, например AGENTS.md и CLAUDE.md. Объём такого контекста зависит от зрелости проекта и команды.
Как агент использует капсульный фреймворк. Передача знаний
Один из компонентов капсулы — экспертное знание. Для передачи его агенту мы используем MCP-сервер с двумя инструментами.
Первый инструмент — документация по фреймворку. Структурированный текст с описанием принципов, структуры сервисов, паттернов реализации, работы с DI-контейнером, обработки событий. Написана специально для агента: с примерами кода и чёткими правилами.
Второй инструмент — документация по архитектурному альбому. Описывает формат archland.json, правила заполнения полей и генерации C4-диаграмм с визуализацией проблемных мест.
Разделение оправдано: у инструментов разные пользователи. Генерацией кода занимаются разработчики — им нужна документация по фреймворку. Генерацией альбома — архитектор. Раздельность экономит токены: агент запрашивает только то, что нужно.
Упаковка в MCP-сервер даёт ещё одно преимущество: такую документацию можно подключить к любому современному агенту. MCP де-факто стал стандартом для расширения возможностей агентов и передачи им контекста.
Важный нюанс: эти документы написаны не для людей. Они написаны для агента. Это видно по структуре и формулировкам.
Вот фрагмент из документации фреймворка — обратите внимание на тон:
Человек поймёт содержание. Но писалось это не для него — отсюда императивный стиль, пометки «ПРАВИЛО», конкретные шаблоны без воды. Агент работает именно так: ему нужны правила, а не рекомендации.
Документация по archland.json устроена аналогично — она включает пошаговый алгоритм для агента:
Агент читает инструкцию — и знает точно, что делать с каждым файлом. Не угадывает, не импровизирует. Документация убирает всё, что может стать источником произвольного выбора.
Сценарий: добавляем новый метод
Представим задачу. Клиент хочет получить список своих заказов. Нужно создать новый метод в сервисе заказов и пробросить его в HTTP API.
Единственное, что нужно от разработчика — описать формат входящих и исходящих данных. Необязательно в JSON Schema: можно написать словами или набросать структуру. Агент сам переведёт это в правильный формат и добавит в service.schema.json — он знает, как должна выглядеть схема, из документации фреймворка. Если разработчик хочет сделать это сам — тоже может. Это вопрос привычки.
Для примера — как выглядит готовая схема нового метода в service.schema.json:
После этого агенту достаточно написать такой промпт:
Дальше агент работает самостоятельно. Вот что происходит под капотом:
- Агент читает
CLAUDE.md— получает контекст проекта. Узнаёт, что проект на капсульном фреймворке, и запрашивает его документацию из MCP-сервера. - Добавляет метод в
service.schema.json. Из промпта понял данные, из документации — формат схемы. Сам переводит описание в JSON Schema и добавляет метод. - Запускает кодогенерацию. Документация фреймворка указывает, какой скрипт вызвать и где. Генерация детерминирована — это не агент сочиняет boilerplate, а фреймворк производит его по схеме. Это гарантирует предсказуемость и экономит токены.
- Пишет бизнес-логику. Получив сгенерированный скелет и все типы, агент добавляет реализацию. Он знает, как внедрять зависимости через
@inject, как работать с портами — всё это в документации. Если в репозитории не хватает метода, сам добавит его в интерфейс и реализацию. - Создаёт HTTP-ручку. Агент открывает файл с роутами, смотрит, как устроены ручки, и по тому же паттерну добавляет новую. Фреймворк не диктует структуру HTTP-слоя — это зависит от проекта.
Задача выполнена. Поскольку в CLAUDE.md прописан формат коммитов, агент оформит коммит по правилам. Разумеется, только после того, как разработчик проверит код и убедится, что ошибок нет.
Такая задача занимает не больше 10 минут. И самое ценное — шаблон работает одинаково для всех подобных задач. Результат предсказуем и воспроизводим.
Как агент использует капсульный фреймворк. Генерация архитектурного альбома
Теперь другой сценарий. Разработчик, отвечающий за архитектуру, хочет получить актуальную картину системы. Ему достаточно написать:
Агент получает из MCP-сервера документацию по формату archland.json, понимает, из каких компонентов он состоит, обходит все сервисы проекта (их расположение — в документации фреймворка), анализирует схемы, DI-контейнеры и обработчики, и заполняет файл.
На основе готового archland.json формируется архитектурный альбом. Вот как выглядит его фрагмент — на примере интернет-магазина:
ShopBackend — платформа интернет-магазина с мультитенантной архитектурой.
HTTP API Gateway (Fastify, REST)
OrderService
Управление заказами, публикация событий
PostgreSQL
NotificationService
Email и push-уведомления
CatalogService
Каталог товаров, поиск
PostgreSQL
UserService
Аутентификация, профили
PostgreSQL, Redis
PaymentService
Интеграция с платёжными провайдерами
PostgreSQL
WarehouseService
Остатки на складе
PostgreSQL
Контекстная диаграмма всей системы:
Контейнерная диаграмма — взаимосвязи между сервисами. Сплошные стрелки — синхронные вызовы, пунктирные — асинхронные события:
Компонентная диаграмма OrderService — внутреннее устройство сервиса: методы, обработчики событий, репозитории и их связи:
На детальных диаграммах агент автоматически помечает проблемные места. Например, циклические синхронные вызовы: Сервис А → Сервис B → Сервис C → Сервис А. В коде такую цепочку сложно заметить, особенно если каждый сервис разрабатывает отдельный человек. На диаграмме — видно мгновенно.
Такая задача даже на большом проекте занимает не больше 10 минут и расходует мало токенов. Ключевой момент: агент не изобретает структуру альбома — он работает по строгому задокументированному контракту. Именно это делает результат предсказуемым.
В дальнейшем планируем добавить в альбом раздел с архитектурными метриками. Например: общий класс, который используют десять сервисов — против дублирования это хорошо, но такой класс требует особого внимания: любое изменение в нём может сломать многое. С метриками подобные «горячие точки» будут видны сразу.
Интервью с Клодом
Мне пришла в голову идея: если код теперь пишет агент, и основной пользователь капсулы — тоже агент (я лишь формирую и развиваю капсулы), почему бы не спросить самого агента, каково ему работать с таким инструментом? Я провёл короткое интервью с Claude Code — о том, как он использует капсульный фреймворк и насколько это ему помогает.
— Что тебе даёт структура капсульного фреймворка при работе над задачами проекта? Помогает ли она тебе лучше понять проект?
Да, и это один из наиболее ощутимых эффектов. Когда у проекта есть капсула с документацией фреймворка, service.schema.json каждого сервиса превращается в своего рода паспорт: смотришь на схему — и сразу видишь, что умеет сервис, какие данные принимает, какие события публикует. Не нужно читать реализацию, чтобы понять контракт.
Предсказуемая структура снижает когнитивную нагрузку. Я знаю, где искать бизнес-логику, где порты, где репозитории — это не нужно угадывать по каждому сервису заново. В результате меньше ошибок, меньше произвольных решений. Я не изобретаю, как назвать файл или куда положить класс — фреймворк уже ответил на эти вопросы.
Ещё один важный момент: такое знание переносимо. Если я работал с одним сервисом на этом фреймворке, то с вероятностью 90% понимаю, как устроен следующий. Это важно не только для меня, но и для нового разработчика в команде.
— Представь одну и ту же задачу — без капсулы и с капсулой. Насколько разным будет результат?
Задача будет выполнена в обоих случаях. Разница — в качестве и предсказуемости результата.
Без капсулы я делаю произвольные выборы там, где мог бы следовать соглашениям. Называю вещи по-своему, кладу файлы туда, где кажется логичным. В рамках одной сессии это выглядит нормально. Но от сессии к сессии структура проекта начинает «дрейфовать» — у каждой задачи своя «нотка импровизации». Со временем это накапливается, и проект перестаёт быть однородным.
С капсулой кодогенерация детерминирована: я запускаю скрипт фреймворка — и получаю предсказуемый скелет. Мне остаётся только бизнес-логика, для которой произвольных вариантов нет. Меньше решений → меньше ошибок → стабильнее архитектура.
Если совсем коротко: без капсулы я решаю задачу; с капсулой я решаю задачу правильно для этого конкретного проекта.
— Что для тебя значит «понять проект»? И помогает ли тебе в этом капсула?
Я бы выделил три уровня понимания.
Структурный — где что лежит, как устроены сервисы, какие паттерны используются. Капсула закрывает этот уровень полностью и сразу.
Архитектурный — почему система устроена именно так. Почему выбран event-driven подход, почему такое разделение на сервисы. Капсула помогает и здесь: хорошая документация содержит принципы, а не только инструкции. Но этот уровень требует работы с ADR и историей решений, которых в капсуле может не быть.
Контекстный — бизнес-логика, неочевидные исключения, прошлые ошибки. «Этот метод работает именно так, потому что три года назад клиент попросил, а мы потом забыли переделать». Это живёт в головах людей. Капсула здесь не помогает — и не должна. Это зона ответственности команды.
Капсула даёт мне первые два уровня быстро и надёжно. Третий я получаю из разговора с вами.
— Помогла бы тебе капсула в других задачах? Например, если бы она описывала, как оценивать проекты по срокам?
Да, и это интересный пример. Оценки — одно из мест, где теоретический оптимизм расходится с реальностью чаще всего. Если бы капсула содержала историю: сколько реально занимали похожие задачи, где чаще всего возникали сложности, какие паттерны «дешёвых задач», оказавшихся долгими, — это дало бы гораздо более точную базу для расчёта.
Но есть важная оговорка: качество такой капсулы полностью зависит от качества накопленных данных. Если история содержит только успешные кейсы и не фиксирует провалы — капсула будет воспроизводить тот же оптимизм, что и без неё. Данные надо собирать честно.
И финальное суждение — всё равно человеческое. Я могу дать расчёт на основе статистики, указать на аналогичные задачи из прошлого. Но «берём ли мы этот риск» — это решение, которое принимаете вы.
Что меняется: роль разработчика
Разработка с появлением агентов меняется — но не так сильно, как можно подумать. За последний месяц я не написал ни строчки кода сам, в классическом понимании. И это даёт свои преимущества. Но суть работы разработчика при этом не исчезла.
С моей точки зрения, работа разработчика всегда состояла из трёх этапов:
- Придумать, как делать. Выбрать один из возможных вариантов, исходя из стратегических целей продукта.
- Написать код. Реализовать задуманное.
- Нести ответственность. За свой код — на протяжении всего жизненного цикла продукта.
Агент помогает преимущественно со вторым пунктом. Первый и третий остаются за разработчиком — особенно когда речь идёт о продукте, а не о прототипе. Решение и ответственность по-прежнему за человеком, и это сложно изменить.
Капсула в этом процессе работает на двух уровнях. Агенту она помогает реализовать второй пункт — предсказуемо и в рамках соглашений проекта. Разработчику — в первом и третьем: фиксирует накопленный опыт, снижает вероятность повторных ошибок, ускоряет принятие решений. Те же три пункта работают и в других областях: архитектурных ревью, оценке задач, написании документации. Везде агент берёт на себя реализацию, человек занимает ключевое место в решении и ответственности.
Здесь есть важный момент, который легко упустить: устаревшая капсула опаснее своего отсутствия. Если в документации описано, как было устроено год назад — агент будет уверенно делать неправильно. Без капсулы он хотя бы задаёт вопросы; с устаревшей — нет. Поэтому поддержание капсулы в актуальном состоянии — не опциональная задача, а ключевая.
Капсула — это не просто набор методов и знаний. Это живая фотография процесса разработки: она должна меняться вместе с ним. Новый опыт, накопленный в том числе с помощью агентов, должен возвращаться в капсулу и обновлять её.
Поэтому одна из главных задач разработчика сегодня — не набор кода, а упаковка опыта: своего и команды. В формат, понятный и человеку, и машине. Машина — основной потребитель этого инструмента на этапе реализации. Разработчик — тот, кто его создаёт, обновляет и несёт за него ответственность.
Три части — один путь.
В первой мы обнаружили проблему: опыт живёт в людях, а не в системах. Когда человек уходит — уходит и то, что он знал. Капсула появилась как ответ: способ зафиксировать знание так, чтобы оно не зависело от конкретного носителя.
Во второй мы прошли этот путь конкретно: от принципов, записанных на созвонах, — к фреймворку, который стал ДНК всех наших проектов. Структура сервисов перестала зависеть от того, кто их писал. Архитектурный альбом перестал требовать ручной работы. Знание переехало из голов в инструмент.
В третьей выяснилось, что тот же инструмент работает не только для людей. AI-агент, открывая незнакомый проект, испытывает ровно то же, что новый разработчик: нужно угадывать соглашения, разбираться в чужой философии, делать произвольные выборы там, где должны быть правила. Капсула решает эту проблему так же, как решала её для людей — даёт структуру, контракт и готовые правила.
Мы не решали задачу «как внедрить AI в разработку». Мы решали задачу «как не терять опыт». Решение оказалось универсальным.
Вернёмся к формуле — теперь уже в третий раз:
Капсула = Экспертное знание + Минимализм + Готовый инструмент
В первой части это была абстракция. Во второй — конкретный фреймворк. В третьей обнаружилось, что капсула точно соответствует тому, что нужно агенту: документированное знание в минималистичной форме с чётким инструментом на выходе.
Капсулу не пришлось переделывать под AI. Она уже была нужной формы.
Есть соблазн сделать вывод, что капсулы — это про AI. Но это не так. Капсулы — это про знание. AI просто сделал нужность этого подхода очевидной: теперь непередаваемость опыта — не только организационная проблема, но и технический ограничитель.
Та же самая капсула, которую мы создавали, чтобы новый разработчик мог быстро войти в проект, теперь позволяет агенту работать в рамках проектных соглашений с первой задачи. Это не совпадение. Это следствие простого закона: хороший инструмент всегда работает для широкого класса потребителей.
Если из этого цикла вы возьмёте только одну мысль — пусть это будет вот эта: упаковка опыта в воспроизводимую форму — это не задача на потом. Это самая важная работа, которую команда может делать прямо сейчас. Для новых коллег, для смены проектов, для масштабирования команды — и да, для агентов тоже.
Опыт, который нельзя потерять, начинается с решения его зафиксировать.