Недавно поймал себя на том, что не помню нюансы работы одного из наших сервисов внутри Jazari. Который я сам же и делал буквально месяца 3-4 назад. Слишком много контекста, слишком много всего происходит, и детали просто начинаешь забывать. В дополнение, забываешь контекст принятия решения, почему сделали именно так, а не иначе.

Начал разбираться с агентом, он не всегда схватывал весь процесс end-to-end, но в итоге мы все разобрали и поняли что надо не просто создать описание/спецификацию/документацию как оно работает, но и поддерживать ее в актуальном состоянии. И тут одних MD файлов в вашем проекте может быть недостаточно.

Причем человек протухшую доку обычно чует: увидел «обновлено 6 месяцев назад», насторожился, полез в код. У агента этого инстинкта нет. Он берет что дали и отвечает с одинаковой уверенностью хоть на свежем контексте, хоть на прошлогоднем.

Что мы делаем сейчас:
1. У нас есть отдельный репозиторий (агенты легко имеют туда доступ, даже когда ты работаешь с репозиторием бэка или мобилы, например), где мы начали описывать спецификации как что работает. К примеру, подписи для блокчейн транзакций, которые затрагивают и мобилу, и бэк, и ограничение сторонних провайдеров.

2. Мы начали активнее добавлять описание в Knowledge Catalog в Google Cloud. Это вообще мега-мощная штука будет, если получится использовать ее на полную катушку. Важно, что Knowledge Catalog доступен не только для разработческих агентов, но и для аналитических. Теперь качество запроса "покажи мне пользователей, которые отваливаются на шаге X в процессе онбординга" сильно выше!

3. Pre-commit hooks, пока только для перегенерации документации API, но дальше будем использовать как часть обновления документации.

Но честно: пока все это держится скорее на ручном усилии. Хуки закрывают только API, спеки обновляются, когда кто-то вспомнит, а Knowledge Catalog свежий ровно настолько, насколько мы дисциплинированны. Системного решения у меня пока нет.

Кто-то реально держит контекст для агентов свежим? Генерите автоматически из кода и схем? Ставите гейт в ревью? Или написали один раз и наблюдаете, как оно расходится с реальностью? Или пока никак и живёте с этим?