AI Docs Toolkit — инструмент для организации разработки с ИИ-агентами. Он объединяет инструкции по работе, структуру проектной документации и программные средства её проверки. Требования, решения, планы и результаты проверок хранятся в репозитории и связываются между собой, чтобы человек и агент могли использовать их при выполнении задач.
Задача и моя роль
Задача Toolkit — поддерживать документацию как рабочий контекст разработки: фиксировать ожидаемое поведение системы, сохранять принятые решения между сессиями и отслеживать, какие связанные материалы нужно проверить при изменениях. Идея сформировалась из опыта работы над Huginn and Muninn.
Я определял цели проекта и участвовал в выборе архитектуры и правил работы. Структуру документации и решения прорабатывали вместе с агентом: он предлагал варианты, оформлял часть архитектурных решений и писал код.
Реализованные возможности
Структурирование документации. Типы документов, идентификаторы, владельцы и явные связи позволяют организовать требования, бизнес-правила, архитектурные решения, контракты и документацию модулей. Инструкции описывают внедрение подхода в новый или существующий проект.
Поддержание каскада изменений. Инструкции задают порядок проверки и обновления связанных слоёв: от требований и бизнес-правил через решения, контракты и документацию модулей к критериям приёмки, тестам и реализации. Граф связей и заданное сопоставление файлов кода с модулями помогают определить затронутые документы.
Локальное планирование. Задачи, планы, решения и результаты проверок ведутся в Markdown. Процесс включает уточнение требований, проектирование и ревью до реализации, выполнение и закрытие работы. Сохранённый план можно передать другому агенту для ревью; объём планирования соразмерен задаче.
Сохранение и подбор контекста. Ключевые требования и решения остаются в файлах репозитория. Инструменты подбирают документы по идентификатору, модулю, функциональности или изменённым документам и сообщают причины выбора, исключения и пробелы.
Программные проверки. Валидатор проверяет метаданные, ссылки, обязательные разделы и отдельные элементы планирования и закрытия задач. Правила заданы в коде и учитывают статус записи: например, при закрытии задачи проверяется наличие итоговых наблюдений и чек-листа закрытия.
Инструкции для обсуждения и ревью. Правила описывают предложение вариантов, рекомендации и работу с блокирующими вопросами. Отдельные инструкции помогают разбирать входящие запросы и проверять изменения относительно принятой документации.
Устройство и интеграция
Toolkit поставляется как Python-пакет со схемами, шаблонами, инструкциями,
CLI ai-docs и опциональным MCP-сервером. Документы пишутся в Markdown,
а YAML front matter хранит метаданные для инструментов.
CLI — полноценный основной интерфейс Toolkit. Через него можно инициализировать структуру документации, вести записи планирования, выполнять проверки, строить граф связей, анализировать влияние изменений и собирать контекст. Одни и те же команды доступны разработчику, агенту с терминалом и сценариям автоматизации. Их можно сочетать с Git, поиском файлов и запуском тестов.
MCP предоставляет агенту дополнительный способ доступа к функциям Toolkit: инструменты вызываются с заданными параметрами без сборки командной строки. Оба интерфейса используют общее ядро, поэтому логика проверок, анализа связей и подбора контекста не дублируется. В текущей реализации через MCP доступны проверки, граф связей, анализ влияния, подбор контекста и чтение планов.
Одна из целей переноса повторяемых операций и проверок в код — экономить контекст агента. Вместо пошагового воспроизведения проверок по инструкции агент вызывает нужную функцию через CLI или MCP и работает с результатом. Проверки контролируют структуру документов и отдельные признаки выполнения процесса. Качество требований, архитектуры и реализации требует содержательного ревью.
Общие инструкции поставляются через пакет; проектные дополнения хранятся отдельно, а переопределения общих правил оформляются явно. Обновление предусматривает просмотр изменений управляемых файлов и последующие проверки.
Применение и текущее состояние
По моим наблюдениям, программные проверки вместе с уточнёнными инструкциями сделали работу агента заметно стабильнее. При работе только по текстовым инструкциям он иногда пропускал смену статуса или обязательные проверки. После доработки механизма такие случаи стали редкими, а в последнее время я их уже не припоминаю.
Я использую Toolkit практически во всех своих проектах, прежде всего для планирования работ с агентом. Доработки вношу по результатам практического применения: уточняю инструкции и существующие механизмы, когда в работе возникают новые потребности.