Как мы собрали базу знаний для агента в git: MCP не хватило, свой индекс отставал
Мы делаем платформу, на которой проджект-менеджеры ведут клиентов. Почти всю работу внутри делает агент, поэтому результат упирается не в модель, а в документацию: что агент прочитал, то он и построил.
Документация лежала в трёх местах: спеки в репозитории, продуктовые обсуждения в Notion и Google Docs, митинг-ноуты отдельно. Человеку терпимо. Для агента это значит, что цельного контекста у него нет никогда: он видит спеку, но не видит обсуждения, из которого она выросла.
Мы прошли три подхода: коннекторы, свой поисковый индекс, файлы в git. Третий работает, и ради него пришлось написать свой редактор - я его автор, так что дисклеймер сразу.
Раз. MCP-коннекторы
Не агент идёт к документам, а документы к агенту: коннектор к Notion, CLI к Google Docs. Работает, но не как база знаний:
- Поиск чужой. Запрос формулирует модель, ранжирует внешняя система, проверить релевантность нечем.
- Сузить нечем. Локально агент делает grep и читает 40 строк. Через коннектор приезжает страница целиком: пять страниц - пять полных документов в контексте, из которых работают три абзаца.
- Нет истории. Приезжает текущая версия и ничего про то, что в ней новое.
- Спеки всё равно остались в репозитории. Две системы вместо одной.
MCP хорош для справки и плох для исходника. Тикет, статус, профиль - за этим ходить через коннектор правильно. То, по чему идёт работа, он не вытянет.
Два. Свой индекс на локальных эмбеддингах
Сделали то, что кажется правильным инженерным ответом. Выкачали Notion в .md, сложили рядом остальное, построили семантический индекс на локальных эмбеддингах - наружу ничего не уходит.
И это работало: агент перестал видеть спеку в вакууме и стал решать заметно лучше. Как способ довезти до него исходник - не сработало, по двум причинам:
- Лаг. Между правкой человека и тем, что видит агент, стоит цикл выкачки и переиндексации. Агент работает по вчерашней картине и об этом не знает.
- Агент - только читатель. Зеркало одностороннее: ни комментария, ни правки, ни пометки. Всё, что он сделал, живёт в чате и умирает вместе с сессией.
Мы построили агенту библиотеку, куда выдают книги, но не дают карандаш.
Индекс мы не выкинули. Он остался тем, для чего годится: семантическим поиском сразу по десяткам репозиториев и папок, чего один git grep не даёт. Перестал он быть другим - тем местом, откуда агент берёт документ, по которому работает.
Три. Всё в .md в репозитории
Спеки, продуктовые постановки, аналитика - одна база, доступная на запись и человеку, и агенту одинаково. Заработало сразу:
- Лага нет по устройству. Агент читает файл напрямую и сужает до строки.
- git log отвечает, почему код такой. Документ и код меняются одним коммитом.
- Видно, кто и когда правил. Не «вот текущая спека», а «этот абзац переписал менеджер вчера, соседний не трогали три месяца». Свежая правка весит больше старой, и заводить для этого ничего не пришлось.
- Агент может писать - комментарий, правку, пометку. Тем же способом, что человек, и это видно в истории.
И тут началась настоящая проблема
Схема правильная. Осталось, чтобы .md открыл не инженер.
VS Code с превью. Год так жили. Инженеру терпимо, остальным нет.
WYSIWYG-редакторы Markdown. Переписывают файл целиком. Правите одно слово - в git diff двести строк, потому что редактор переставил маркеры списков и выровнял таблицы по-своему. Такой пулл-реквест никто читать не станет.
Obsidian с плагином Git. Лучший из готового, сидели на нём. Отвалился на комментариях: мы уходили от Google Docs, но не от обсуждения прямо в тексте - это то, ради чего менеджер вообще открывает документ.
Поэтому написали своё, под свою же боль. Посмотрели на то, что получилось, и решили выложить в общий доступ. Notula - бесплатный WYSIWYG-редактор Markdown для docs as code, который правит файлы прямо в вашем git-репозитории. Три вещи, которых не хватало:
- Разметки не видно вообще, включая строку под курсором. Открывает не инженер.
- Файл не переписывается. Открыл, сохранил не тронув - байты те же. Это не обещание, а тест на 6000 реальных документов.
- Комментарии на абзацах, коммитятся рядом. Сами файлы остаются чистыми, без якорей внутри.
Есть CLI, поэтому Claude Code сидит в том же воркспейсе, что и человек: читает те же документы, отвечает в тех же тредах. Аккаунт не нужен, notula.org.
Что забрать себе
- Держите в репозитории то, по чему работает агент. MCP оставьте справочникам: тикетам, статусам, профилям.
- Зеркало решает поиск и не решает остального. Индекс поверх внешней базы - хороший поиск, но агент остаётся в нём читателем. Оставьте его поиском, а исходник держите там, куда агент может писать.
- Проверяйте редактор на round-trip до общих файлов. Открыть, сохранить, git diff. Тридцать секунд экономят месяцы мусора в пулл-реквестах.
- Комментарии - не украшение. Без них .md остаётся файлом для инженеров, а переезд затевался ради обратного.
Переезд оказался не технической задачей, а вопросом того, откроет ли документ человек без терминала.
Спорный тезис напоследок
У базы знаний появился второй читатель, и все решают для него задачу поиска: коннекторы, RAG, индексы. Задача решаемая, но не та. Настоящий вопрос - может ли этот читатель писать. Пока агент только читает, он справочный сервис: сессия кончилась, всё, что он понял, пропало. Как только пишет в тот же документ, что и человек, и это видно в истории, он участник работы.
У вас документацию в репозитории правят только инженеры, или менеджеры и аналитики тоже добрались? Если добрались - через что?