В первой части я рассказал, что такое капсула и зачем упаковывать опыт. В второй части — как мы построили капсульный фреймворк для микросервисов. Если вы не читали предыдущие части, советую начать оттуда.
В этой части я покажу, что происходит, когда к капсуле подключается AI-агент. Почему жёсткая структура капсулы — это именно то, что нужно агенту. И как опыт, упакованный в капсулу, становится опытом, которым может пользоваться машина.
Серия «Разработка через капсулы»:
Часть I: Опыт, которого нельзя потерять: что такое капсула и зачем она нужна
Часть II: Капсульный фреймворк: как мы упаковали архитектуру микросервисов в ДНК проектов
Часть III: Капсулы и AI-агенты: как передать опыт разработчика машине ← вы здесь
Что нужно агенту
Сразу оговорюсь об одном термине. Дальше я буду часто говорить «агент» — и в этом контексте слово объединяет и агента в классическом понимании (инструмент с циклом рассуждений), и LLM, которая лежит в его основе и является его мозгом. Например, для разработки я сейчас чаще всего использую Claude Code и OpenCode. Какие именно модели лежат в их основе — для контекста этой статьи не принципиально. Важна лишь очевидная закономерность: чем лучше модель, тем лучше результат.
Агентов в разработке применяют в двух принципиально разных режимах.
Режим первый — прототипирование. Нужно проверить теорию: сделать что-то работающее, не думая о нагрузке, поддержке или технологическом стеке. Такой продукт мы в принципе не планируем сопровождать. Здесь агенту не нужны никакие особые правила и рамки — нужен только результат. Описываем примерную логику, агент реализует её за 10–15 минут.
Режим второй — разработка продуктов. Этот режим кардинально отличается. Нам нужен не просто работающий код, а продукт, который помимо бизнес-функций выполняет жёсткие нефункциональные требования: его можно поддерживать, читать, масштабировать. Эти требования стоят на одной ступени с бизнес-функционалом — одно без другого не работает.
И здесь возникает проблема. Без структуры агент в каждой задаче делает произвольный выбор. Он не помнит, как был решён похожий вопрос два дня назад. Структура сервисов начинает расползаться — от задачи к задаче она хаотично «эволюционирует» в нечто непредсказуемое. Сервисы перестают быть однородными. Взаимодействие между ними перестаёт укладываться в единую архитектурную картину.
Агент в этом смысле испытывает ровно то же, что разработчик, впервые открывший незнакомый проект. Ему нужно начинать с чистого листа, угадывать как именно здесь принято решать те или иные задачи, вникать в неочевидные соглашения. У опытного разработчика есть накопленные паттерны и, возможно, знакомые коллеги. У агента этого нет — каждый раз с нуля. Без правил и рамок ошибок будет кратно больше.
Для разработки продуктов агенту нужен структурированный контекст. И капсулы подходят для этого идеально.
Капсула = Экспертное знание + Минимализм + Готовый инструмент
Концепция капсул появилась у нас раньше, чем применение агентов в разработке стало трендом. Но формула оказалась актуальной в обоих мирах. Что каждый элемент даёт агенту:
Экспертное знание — агент получает накопленный опыт в структурированном и упакованном виде, а не угадывает его из контекста.
Минимализм — знание в виде эссенции: решает одну конкретную проблему без лишних ответвлений и лишней информации, не засоряет контекстное окно.
Готовый инструмент — капсулой можно просто пользоваться. У неё есть методы, скиллы, задокументированные интерфейсы — именно это лежит в основе современных агентов.
При этом одной капсулы недостаточно. У каждого проекта есть свои правила, которые к капсуле не относятся: стайлгайды, формат коммитов, специфика организации кода. Всё это описывается в отдельных markdown-файлах, с которыми работает выбранный агент. У нас это AGENTS.md и CLAUDE.md. Такого контекста может быть достаточно много — это зависит от команды и зрелости проекта.
Как агент использует капсульный фреймворк. Передача знаний
Один из компонентов капсулы — экспертное знание. Для передачи его агенту мы используем MCP-сервер с двумя инструментами.
Первый инструмент — документация по самому фреймворку. Структурированный текст с описанием принципов, структуры сервисов, паттернов реализации методов, работы с DI-контейнером, обработки событий. Написана специально для агента: с примерами кода и чёткими правилами.
Второй инструмент — документация по архитектурному альбому. Описывает формат archland.json, правила заполнения каждого поля и правила генерации C4-диаграмм с визуальным представлением проблемных мест.
Разделение на два инструмента оправдано: у них разные пользователи. Генерацией кода занимаются разработчики — им нужна документация по фреймворку. Генерацией альбома занимается разработчик, отвечающий за архитектуру. Раздельность экономит токены: агент запрашивает только то, что нужно для конкретной задачи.
Упаковка в MCP-сервер даёт ещё одно преимущество: такую документацию можно подключить к любому современному агенту. MCP де-факто стал стандартным протоколом для расширения возможностей агентов и предоставления им необходимого контекста.
Важный нюанс: эти документы написаны не для людей. Они написаны для агента. Это заметно в структуре и формулировках.
Вот фрагмент из документации фреймворка — обратите внимание на тон:
# Фреймворк nsc-toolkit: Руководство для генерации кода Этот документ структурирован как набор правил и шаблонов для автоматической генерации корректного кода. ## Ядро фреймворка: класс метода (BaseMethod) Правила реализации: - Обязательно объявите статическое свойство settings, скопированное из service.schema.json. - Основная логика реализуется в методе handler. - Внедряйте зависимости через конструктор с декоратором @inject. - Используйте this.logger для логирования. - Используйте this.emitter для генерации событий. ПРАВИЛО: Создайте метод для каждого RPC-вызова из service.schema.json. ПРАВИЛО: К контейнеру должны быть привязаны только актуальные и используемые зависимости.
Человек, читающий это, поймёт содержание. Но писалось это не для него — отсюда императивный стиль, явные пометки «ПРАВИЛО», конкретные шаблоны без воды. Агент работает именно так: ему нужны правила, а не рекомендации.
Документация по archland.json устроена аналогично — она включает пошаговый алгоритм для агента:
Алгоритм генерации для каждого сервиса: Шаг 1. Базовая информация: - Прочитать service.schema.json → name, description - Записать пути: describePath, folderPath Шаг 2. Анализ DI-контейнера: - Прочитать service.ts - Для каждой container.bind() создать Dependency объект - Проанализировать теги для type и external Шаг 3. Анализ методов: - Для каждого класса в methods/: прочитать service.schema.json для описания проанализировать код на вызовы зависимостей и генерацию событий Шаг 4. Анализ подписок: - Для каждого класса в processing/: определить ключ DI из inversion.types.ts проанализировать метод start() для определения сервиса-источника Шаг 5. Собрать все данные в единый объект archland.json
Агент читает эту инструкцию — и знает точно, что делать с каждым файлом. Не угадывает, не импровизирует. Документация убирает из его работы всё, что может стать источником произвольного выбора.
Сценарий: добавляем новый метод
Представим конкретную задачу. Клиент хочет получить список своих заказов. Нужно создать новый метод в сервисе заказов и пробросить его в HTTP API.
Единственное, что нужно от разработчика — описать формат входящих и исходящих данных метода. Необязательно в формате JSON Schema: можно написать просто словами или набросить структуру в произвольном виде. Агент сам переведёт это в правильный формат и добавит в service.schema.json — он знает, как должна выглядеть схема, из документации фреймворка. Если разработчик хочет сделать это самостоятельно — тоже никто не запрещает, это вопрос привычки и предпочтений.
Для примера — как выглядит готовая схема нового метода в service.schema.json:
"ListOrders": { "action": "ListOrders", "description": "Получение списка заказов пользователя", "request": { "type": "object", "properties": { "credentials": { "type": "object", "properties": { "user_id": { "type": "string" }, "space_id": { "type": "string" } }, "required": ["user_id", "space_id"] } }, "required": ["credentials"] }, "response": { "type": "object", "properties": { "result": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": "string" }, "product_id": { "type": "string" }, "quantity": { "type": "number" }, "created_at": { "type": "string" } }, "required": ["order_id", "product_id", "quantity", "created_at"] } } } } }, "required": ["result"] } }
После этого агенту достаточно написать такой промпт:
Создай новый метод ListOrders в сервисе @services/order. Метод принимает: user_id из credentials. Возвращает: список заказов, каждый с полями order_id, product_id, quantity, created_at. Пробрось метод в @services/gate в набор ручек @services/gate/routes/orders.ts.
Дальше агент работает самостоятельно. Вот что происходит под капотом:
Агент читает
CLAUDE.md— получает специфический контекст проекта. Узнаёт, что проект написан на капсульном фреймворке, и запрашивает его документацию из MCP-сервера.Добавляет метод в
service.schema.json. Из промпта агент понял формат входящих и исходящих данных, из документации — как должна выглядеть схема. Он самостоятельно переводит описание в корректный JSON Schema и добавляет новый метод в файл.Запускает кодогенерацию. Документация фреймворка описывает, какой скрипт нужно вызвать и где. Сама генерация детерминирована — это не агент сочиняет boilerplate, а фреймворк производит его по схеме. Это гарантирует предсказуемый результат и экономит токены.
Пишет бизнес-логику. Получив сгенерированный скелет метода и все типы, агент добавляет реализацию. Он знает, как внедрять зависимости через
@inject, как работать с портами — всё это описано в документации. Обнаружив, что в репозитории не хватает метода, сам добавит его в интерфейс порта и в реализацию.Создаёт HTTP-ручку. Агент открывает файл с роутами, смотрит, как они устроены, и по тому же паттерну добавляет новую. Фреймворк не диктует структуру HTTP-слоя — это зависит от проекта и от пользователей публичного API.
Задача выполнена. Поскольку в CLAUDE.md прописан формат коммитов, агент оформит коммит по правилам. Разумеется, только после того как разработчик просмотрит код и убедится, что ошибок нет.
Такая задача занимает не больше 10 минут. И самое ценное — что этот шаблон работает одинаково для всех подобных задач. Предсказуемо и воспроизводимо.
Как агент использует капсульный фреймворк. Генерация архитектурного альбома
Теперь другой сценарий. Разработчик, отвечающий за архитектуру, хочет получить актуальную картину системы. Ему достаточно написать:
Сгенерируй archland.json и архитектурный альбом проекта.
Агент получает из MCP-сервера документацию по формату archland.json, понимает из каких компонентов он состоит, обходит все сервисы проекта (их расположение описано в документации фреймворка), анализирует схемы, DI-контейнеры и обработчики, и заполняет файл.
На основе готового archland.json формируется архитектурный альбом. Вот как выглядит его фрагмент — на примере абстрактного интернет-магазина:
ShopBackend — платформа интернет-магазина с мультитенантной архитектурой.
Сервис | Роль | БД |
|---|---|---|
Gate | 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 просто сделал нужность этого подхода очевидной: теперь непередаваемость опыта — не только организационная проблема, но и технический ограничитель.
Та же самая капсула, которую мы создавали, чтобы новый разработчик мог быстро войти в проект, теперь позволяет агенту работать в рамках проектных соглашений с первой задачи. Это не совпадение. Это следствие простого закона: хороший инструмент всегда работает для широкого класса потребителей.
Если из этого цикла вы возьмёте только одну мысль — пусть это будет вот эта: упаковка опыта в воспроизводимую форму — это не задача на потом. Это самая важная работа, которую команда может делать прямо сейчас. Для новых коллег, для смены проектов, для масштабирования команды — и да, для агентов тоже.
Опыт, который нельзя потерять, начинается с решения его зафиксировать.
