Меня зовут Антон Богун, я старший разработчик ПО в Axenix. В прошлой статье мы говорили о Doc as Code как об инженерной практике: документация живет в Git, проходит review, проверяется автоматически и становится частью процесса разработки. Это важная база, но сегодня у нее появляется следующий уровень применения.
Разработчик подключает ИИ-агента уже не к абстрактной документации, а к собственному проекту: к кодовой базе, OpenAPI спецификациям, Markdown страницам, release notes, задачам в трекере и интеграционным схемам. От агента ждут не пересказа документации, а понимания текущего поведения системы.
Именно здесь возникает новая проблема. Метод API может называться так же, путь может остаться прежним, request body может почти не измениться, но поведение системы уже стало другим. Например, заказ больше не создается сразу в финальном статусе, часть заказов уходит на дополнительную проверку, после создания публикуется событие, а обработка продолжается в другом сервисе через брокер сообщений.
Для человека такие изменения часто понятны из задачи, pull request, обсуждения или кода. Для ИИ-агента это неочевидно, если код, спецификация, документация и задачи не связаны между собой.
Doc as Code отвечает на вопрос: как хранить и проверять документацию. Но для ИИ-агента важнее следующий вопрос: как понять, что изменилось в поведении системы и где это отражено.
ИИ-агенту нужен контекст проекта, а не просто набор файлов
Когда мы говорим «дадим ИИ-документацию», часто подразумевается, что достаточно открыть агенту доступ к репозиторию, где лежат openapi.yaml, README и несколько Markdown страниц. Но в реальном проекте этого мало.
Агент может увидеть файлы, но не понять связи между ними. Он может найти метод в коде, но не понять, какая страница его описывает. Может найти страницу документации, но не понять, соответствует ли она текущей версии кода. Может увидеть задачу, но не связать ее с изменением поведения API.
Представим не абстрактный токен, а бизнес метод:
POST /v1/orders
страница «Заказы»
schema CreateOrderRequest / Order
release notes 1.1.0
задача «Изменить правила создания заказа»
код обработчика создания заказа
Если эти элементы никак не связаны, агенту приходится угадывать. Он может увидеть POST /v1/orders и ответить по старому описанию: «метод создает заказ в статусе NEW». Но в новой версии поведение могло измениться: если заказ требует дополнительной проверки, он создается в статусе PENDING_VALIDATION, а дальнейшая обработка запускается событием.
Поэтому ИИ нужна не просто документация. Ему нужен связанный контекст проекта: код, спецификация, страницы документации, схемы, задачи, версии и связи между ними.
MCP как способ доставить инженерный контекст агенту
MCP, или Model Context Protocol, можно рассматривать как способ подключить ИИ-агента к внешним источникам данных и инструментам. В контексте разработки это не только документация, но и весь инженерный контур проекта.
Упрощенно схема выглядит так:
ИИ-агент
➜ MCP
➜ проектный контур
➜ актуальный инженерный контекст
Под проектным контуром здесь можно понимать:
кодовую базу;
OpenAPI спецификации;
Markdown документацию;
модель сервисов;
HTTP методы;
события;
топики;
задачи в трекере;
release notes;
связи между всеми этими объектами.
То есть MCP нужен не для того, чтобы просто «скормить ИИ больше текста». Его ценность в том, что агент получает доступ к структурированному источнику правды и может двигаться по связям внутри проекта.
Для технической документации это принципиальное отличие. Агенту полезнее получить не случайный фрагмент Markdown, а структуру:
сервис
➜ HTTP метод
➜ request schema
➜ response schema
➜ связанная страница документации
➜ связанная задача
➜ release notes
➜ версия
С таким контекстом агент может не только отвечать на вопросы, но и выполнять проверки: где документация устарела, где изменилась схема, где появился новый сценарий поведения, где нет связанной задачи или release notes.
Context7 как понятный пример подхода
Перед внутренними API удобно посмотреть на более простой пример - публичную документацию библиотек. Здесь хорошо видна разница между агентом без управляемого контекста и агентом, который получает документацию через отдельный слой.
Без такого слоя агент действует примерно так: получает вопрос, ищет ответ в знаниях модели, при необходимости просит приложить документацию или пытается ориентироваться по большому набору файлов. В prompt попадает много лишнего текста, а риск ответа по старой версии остается.
С Context7 флоу другой: разработчик задает вопрос по библиотеке, агент через MCP запрашивает актуальные фрагменты документации, получает только нужные разделы и уже по ним формирует ответ.
вопрос разработчика
➜ Context7
➜ актуальная документация библиотеки
➜ короткий контекст для ответа
За счет этого меняется не только качество ответа, но и сам принцип расхода контекста. Агенту не нужно тащить в prompt весь массив документации. Он может получить нужные фрагменты точечно. Ниже тот же принцип будет виден уже на примере AxenAPI и внутреннего проекта, где сравнение показало разницу по входному контексту примерно на 16%.
Для внутренних корпоративных API нужна похожая идея, только источником контекста становится не публичная документация, а собственный проект компании. Внутренние сервисы не лежат в открытом интернете и не попадают в обучающие данные модели. Их контекст находится в Git, OpenAPI, Markdown, Confluence, Swagger, Jira, GitHub Issues, схемах событий и внутренних договоренностях.
Поэтому внутренним API нужен свой Context7 подобный слой. Не внешний справочник по библиотеке, а управляемый слой контекста поверх собственного проекта.
От репозитория с документацией к слою связей
Допустим, у команды уже есть репозиторий с документацией и спецификациями. В нем лежат OpenAPI файлы, страницы по API, схемы моделей, release notes и, возможно, рядом находится кодовая база проекта.
docs/orders.md
docs/release-notes.md
specs/openapi.yaml
models/order.schema.json
src/orders/handler.*
Если подключить к такому проекту ИИ-агента без дополнительной систематизации, он чаще всего будет работать обычным поиском по тексту. Найдет вхождения через grep, откроет похожие файлы, сравнит названия методов, страниц и моделей. Иногда этого достаточно, но результат зависит от структуры репозитория и аккуратности названий.
Проблема в том, что grep находит совпадения, но не объясняет смысл связи. Он может показать, что POST /v1/orders встречается в спецификации и на странице orders.md, но не скажет сам по себе, какая страница является основной, какая задача объясняет изменение поведения и какие события продолжают сценарий после HTTP вызова.
Поэтому здесь нужна систематизация. Не вместо Git и не вместо документации, а поверх них - слой, который связывает метод, страницу, схему, задачу, событие и версию. Чем меньше агент ищет вслепую, тем меньше лишнего контекста он тратит и тем устойчивее становится ответ.
Как AxenAPI добавляет порядок
AxenAPI можно рассматривать как такой слой порядка над репозиторием с документацией и спецификациями. Он связывает инженерные артефакты между собой и дает агенту не просто набор файлов, а карту проекта.
В одном контуре оказываются:
API спецификации;
визуальная модель сервиса;
HTTP методы;
события;
топики;
документационные страницы;
Git репозиторий;
задачи в трекере;
связи между документацией и объектами системы;
контекст для ИИ-агента через MCP.
В обычном режиме агент, подключенный только к репозиторию, видит код, openapi.yaml, Markdown страницы и release notes. Но он не всегда понимает, какая страница относится к какому методу и какие изменения в коде влияют на поведение API.
AxenAPI добавляет слой связей:
сервис связан с HTTP методами;
HTTP метод связан со схемами request и response;
страница документации связана с методом;
задача связана со страницей документации;
событие связано с топиком и сервисом.
Для ИИ-агента это означает, что он получает не просто набор файлов, а карту проекта.
Функционально AxenAPI можно разложить на несколько блоков.
Repository manager подключает Git репозиторий, где живут спецификации и документация. Это позволяет работать с ветками, сохранять изменения и встраивать документацию в привычный Git процесс.
Modeler показывает систему как карту объектов: сервисы, HTTP методы, события, топики и связи. API перестает быть только YAML файлом и становится графом.
Specification / JSON Editor сохраняет связь с OpenAPI или Swagger как с исходным контрактом. Там остаются paths, schemas, examples, version и другие элементы спецификации.
Documentation позволяет создавать и редактировать страницы документации поверх Git.
Link object связывает страницу документации с объектом модели: сервисом, HTTP методом, событием или топиком.
Именно связь объектов становится ключевой для ИИ сценариев.
Какие данные агент может получить через AxenAPI MCP
Имеется набор инструментов, через которые агент может работать не только с текстом, но и с моделью проекта.
Например, для работы с сервисами доступны:
getGlossaryForServices - получить список сервисов;
getServiceInfo - получить информацию о конкретном сервисе;
getServiceHttpMethods - получить HTTP методы сервиса, в том числе с фильтрацией по конкретному методу.
Для событий и брокеров:
getGlossaryForTopics - получить список топиков;
getTopicListeners - узнать, какие сервисы слушают или публикуют сообщения в топик;
getBrokerTopicListeners - получить слушателей по типу брокера, например Kafka, JMS или RabbitMQ;
getEventInfo - получить информацию о событии и местах его использования;
getEventJsonSchema - получить JSON Schema события.
Для документации и задач:
getDocContent - получить содержимое страницы документации;
createTaskInTracker - создать задачу в трекере;
linkTaskToPage - связать задачу со страницей документации;
getTasksForPage - получить задачи, связанные со страницей;
getPagesLinkedToTask - получить страницы, связанные с задачей.
Такой набор инструментов хорошо показывает идею AxenAPI. Агент работает не только с файлами, а с сервисами, методами, событиями, топиками, задачами и документацией как с единой моделью.
Небольшая проверка на практике
Эту идею можно проверить не только на уровне архитектуры, но и на простом сценарии работы агента.
В одном из тестов агенту нужно было получить информацию по задаче и собрать связанный контекст для аналитика или разработчика. В варианте без MCP в чат вручную передавалась карточка задачи, а агенту был доступен весь репозиторий документации. В варианте с AxenAPI MCP агент получал только номер задачи и сам забирал карточку, связанную документацию и контекст через инструменты MCP.
По медиане трех прогонов вариант с полным MCP использовал меньше входного контекста: около 47.8k input tokens против 56.9k в baseline. Разница составила примерно 16%.
Этот результат не стоит воспринимать как универсальное обещание экономии токенов в любом проекте. Время ответа у MCP сценария было выше из-за вызовов инструментов, а итог зависит от качества связей, структуры документации и ограничений промпта. Но тест хорошо показывает практическую ценность подхода: агенту не обязательно загружать весь массив документации в контекст, если он может точечно получить задачу, связанные страницы, методы и схемы через структурированные инструменты.
Для разработчика это меняет сам сценарий работы. Вместо того чтобы вручную прикладывать документы и объяснять, где искать контекст, он может передать агенту идентификатор задачи. Дальше агент сам собирает инженерный контекст из трекера, документации и модели проекта.
Link object как ключевой механизм
Без связей агент видит набор файлов:
openapi.yaml
orders.md
release-notes.md
some-task-description.md
Он может прочитать эти файлы, но не всегда поймет, какая страница описывает конкретный метод, какая задача объясняет изменение поведения и какие схемы участвуют в сценарии.
Со связями картина становится другой:
«Заказы» ➜ POST /v1/orders
«Заказы» ➜ GET /v1/orders
«Release notes 1.1.0» ➜ POST /v1/orders
«Изменить правила создания заказа» ➜ страница «Заказы»
Такая связь превращает документацию из текста в машиночитаемый контекст. Агент может понять:
какой метод изменился;
где описано новое поведение;
какая версия содержит изменение;
какая задача объясняет причину изменения;
какие схемы участвуют в сценарии.
Главная ценность здесь не в том, что страница существует. Главная ценность в том, что система знает, к какому объекту эта страница относится.
Сценарий: разработчик спрашивает, почему изменилось поведение API
Представим, что разработчик подключил ИИ-агента к собственному проекту и спрашивает:
Почему после вызова POST /v1/orders заказ не всегда создается в статусе NEW?
Без связанного контекста агент может открыть старую страницу документации и ответить слишком обще. Например: «метод создает заказ». Но это не отвечает на вопрос о поведении.
С AxenAPI MCP агент может собрать контекст последовательно.
Сначала он получает спецификацию метода:
getServiceHttpMethods("OrderService", "POST /v1/orders")
Так он видит request body, response, схемы CreateOrderRequest и Order.
Затем агент получает страницу документации:
getDocContent("/orders/api.md")
После этого он может проверить информацию о сервисе:
getServiceInfo("OrderService")
Если создание заказа связано с событием, агент может запросить схему события:
getEventJsonSchema("OrderService", "OrderCreated")
Если страница связана с задачами, агент может получить их:
getTasksForPage("/orders/api.md")
После этого ответ агента может быть уже не пересказом документации, а объяснением поведения:
Метод POST /v1/orders остался тем же, но в версии 1.1.0 изменилось правило создания заказа. Если заказ требует дополнительной проверки, он создается не в статусе NEW, а в статусе PENDING_VALIDATION. Это отражено в документации «Заказы», схеме Order и задаче на изменение бизнес правила.
Это и есть ключевой сценарий. Агент помогает понять, почему система ведет себя иначе, опираясь на спецификацию, документацию, задачи и модель сервиса.
Сценарий: агент проверяет, отражено ли изменение поведения в документации
ИИ полезен не только для ответов разработчикам. Он может помогать контролировать полноту документации перед релизом.
Допустим, команда изменила поведение POST /v1/orders и добавила новый статус PENDING_VALIDATION.
Агент может проверить:
изменился ли OpenAPI;
обновлена ли страница «Заказы»;
есть ли описание нового поведения;
добавлен ли пример ответа;
обновлены ли release notes;
есть ли задача в трекере;
связана ли задача со страницей документации.
Возможный вывод агента:
Метод POST /v1/orders содержит новый сценарий обработки заказа, но на странице «Заказы» нет описания условия перехода в статус PENDING_VALIDATION. Нужно обновить раздел «Создание заказа», добавить пример ответа и связать изменение с release notes 1.1.0.
Здесь ИИ не просто генерирует текст. Он проверяет полноту инженерного контекста. Такой сценарий полезен для разработчиков, аналитиков, архитекторов и технических писателей.
Асинхронные интеграции: что происходит после HTTP вызова
REST API - только часть поведения системы. В реальных проектах бизнес процесс часто продолжается через Kafka, Artemis, RabbitMQ, JMS, очереди, события и схемы сообщений.
Например, заказ создается через POST /v1/orders, а после этого публикуется событие OrderCreated. Дальше его могут читать платежный сервис, сервис уведомлений или сервис аналитики.
Для такого сценария агенту важно понимать не только HTTP метод, но и дальнейший интеграционный поток:
какое событие публикуется;
в какой топик оно попадает;
какие сервисы его читают;
какая JSON Schema у события;
где описан этот поток.
Через AxenAPI MCP агент может запросить:
getTopicListeners("order_topic")
getBrokerTopicListeners("KAFKA")
getEventJsonSchema("OrderService", "OrderCreated")
getEventInfo("OrderCreated")
Так агент видит не только API вызов, но и дальнейшее поведение системы. Он может объяснить, что после создания заказа публикуется событие, какие сервисы его потребляют и какая схема сообщения используется.
Для ИИ-агента такие связи не менее важны, чем REST методы. Если он понимает интеграционный поток, он может отвечать не только на вопрос «как вызвать API», но и на вопрос «что произойдет дальше».
Трекер и CI/CD: как превратить изменение поведения в управляемый процесс
Если меняется поведение метода, одной правки OpenAPI может быть недостаточно. Нужно обновить страницу документации, release notes и задачу, где описана причина изменения.
Через MCP агент может:
создать задачу на обновление документации через createTaskInTracker;
привязать ее к странице через linkTaskToPage;
получить связанные задачи через getTasksForPage;
проверить, что у изменения поведения есть документационное сопровождение.
Пример правила:
Изменилось поведение метода POST /v1/orders, но страница «Заказы» и release notes не обновлены - релиз нельзя считать готовым.
Так документация перестает быть справочником, который обновляют вручную после разработки. Она становится частью процесса изменения поведения системы:
изменение кода
➜ изменение спецификации
➜ обновление документации
➜ связь с задачей
➜ review
➜ публикация
Связь спецификации, документации и задач делает документацию частью поставки, а не постфактум описанием того, что уже сделали.
Заключение
Doc as Code сделал документацию частью инженерного процесса. Но когда к проекту подключается ИИ-агент, этого становится мало. Агенту нужен не просто Markdown и OpenAPI, а связанный контекст: код, спецификации, страницы, события, задачи, версии и связи между ними.
MCP добавляет механизм доступа к такому контексту. AxenAPI в этой схеме интересен как инструмент, который строит карту проекта вокруг API документации: сервисы, методы, события, топики, страницы и задачи становятся связанными объектами.
Главный фокус здесь не в том, чтобы ИИ писал документацию вместо инженеров. Важнее другое: ИИ должен понимать текущее поведение системы и помогать команде проверять, что это поведение отражено в спецификациях, документации и задачах.
Будущее технической документации не просто в Git и не просто в генерации текста. Оно в проверяемом, версионном и связанном инженерном контексте, с которым ИИ-агент сможет работать безопасно и предсказуемо.
