12 шагов: чтобы ИИ-агент читал вашу документацию

Шаги идут от замера к правилу. Не начинайте с переписывания документов: сначала посчитайте, что происходит сейчас, иначе нечего будет сравнивать.

1. Выпишите все документы базы знаний в одну таблицу: имя файла, тема, дата последней правки, кто отвечает за содержание. Результат: нет строки «разное» и нет файлов, о которых никто не может сказать, зачем он нужен.
2. Найдите точку входа — файл или поле, которое агент получает в каждом запуске. Проверьте фактом: откройте 5–10 подряд журналов сессий, точка входа должна упоминаться в каждом. Если такого файла нет, создайте его: это единственный документ, существование которого обязательно.
3. Выгрузите журналы за 2–4 недели и посчитайте по каждому документу число обращений. Результат: третья колонка в таблице. Считать можно вручную или поиском по имени файла в тексте журналов.
4. Отметьте, из каких документов есть ссылки на другие. Файл, на который не ссылается никто, помечайте как «сироту». Результат: у каждого документа либо входящая ссылка, либо метка «сирота».
5. Сравните две группы: документы со входящей ссылкой и «сироты». Вы увидите свою версию той же картины: 12,3 обращения к упомянутым файлам против 1,2 к неупомянутым (Habr, https://habr.com/ru/articles/1088144/). Результат: своя цифра разрыва, а не чужая.
6. Впишите в точку входа ссылки на документы, без которых агент выдаёт неверный результат. Ограничение: не больше 5–7 ссылок. Точка входа — не оглавление, а короткий список условий, который читается за минуту.
7. Формулируйте ссылку как условие действия, а не как название файла: не «pricing.md», а «если в задаче есть цена, срок или скидка, сначала открой pricing.md». Результат: каждую ссылку можно прочитать как инструкцию «когда открывать».
8. Разбейте длинные документы, если ссылка ведёт на файл, где нужная часть спрятана в середине. Один документ — одна тема. Результат: по названию файла понятно, что внутри, без открытия.
9. Разберитесь с «сиротами»: удалите, объедините с профильным документом или поставьте входящую ссылку. Оставлять файл «на будущее» нельзя — по наблюдению из разбора, он останется непрочитанным. Результат: в таблице ни одной «сироты».
10. Прогоните через агента одну реальную задачу, которая раньше давала ошибку: подготовку коммерческого предложения или ответ на возражение. Результат: в журнале видно, что агент открыл документ, на который вы сослались.
11. Сверьте результат руками: цифры, сроки и цены в ответе должны совпадать с профильным документом дословно. Если расходятся — ссылка стоит из точки входа, но сам документ противоречит другому.
12. Введите правило приёмки: новый документ не появляется в базе без входящей ссылки из точки входа или из другого документа. Результат: правило записано там, где его видит человек, который пополняет базу.
13. Повторяйте замер раз в месяц: доля документов с нулём обращений падает или держится на нуле.

Почему это работает: точки входа агент видит всегда, остальное читает по ссылке. Дело не в том, что файлы плохо написаны, а в том, что у агента нет привычки ходить по всей папке. Он читает то, на что ему явно указали, — и это ваш главный рычаг управления.