Вашему ИИ‑агенту нужна карта: LLM Wiki или README достаточно

vibe coding → agentic engineering → LLM wiki

В предыдущей статье про AI‑инструменты и агентов я разбирал инструменты, которые меняют то, как разрабатывается программное обеспечение. В её продолжении я утверждал, что роль разработчика смещается от написания кода к его направлению.

Эта статья делает следующий шаг: что происходит, когда AI‑агенты становятся способны строить всё более сложные кодовые базы и ориентироваться в них? Как сохранять знания, на которые они опираются, точными, находимыми и актуальными? Здесь и появляется идея LLM wiki.

Onboarding‑файл (например, CLAUDE.MD) говорит агенту, как себя вести: соглашения, правила слоёв, запрещённые паттерны. Чего он агенту не даёт — так это накопленного знания о вашей системе: почему в платёжном потоке есть та странная ветка, какая из одиннадцати интеграций тихо отклоняется от своего задокументированного контракта, какие части документации — ложь. Человек‑разработчик выстраивает это знание месяцами инцидентов и код‑ревью. Агент каждую сессию начинает с нуля.

В апреле 2026 года Андрей Карпаты опубликовал короткий gist под названием LLM Wiki, который предлагает один из ответов на эту проблему. Я реализовал его поверх платёжного ядра крупной платформы, над которой работаю. До этого я практиковал другой ответ: README‑ориентированный репозиторий, где каждый модуль документирует сам себя, а агенту прямо сказано, что именно читать.

[I] LLM Wiki Карпаты: идея

Gist описывает себя скромно: «Паттерн для построения персональных баз знаний с помощью LLM. Это файл‑идея, он рассчитан на то, чтобы его скопировали и вставили в вашего собственного LLM‑агента (например, OpenAI Codex, Claude Code, OpenCode / Pi и так далее)». Не продукт, не фреймворк — паттерн, который вы отдаёте уже имеющемуся у вас агенту.

Проблема, которую он называет

Карпаты начинает с режима отказа подхода по умолчанию — поиска по куче сырых документов в стиле RAG:

«Задайте тонкий вопрос, требующий синтеза пяти документов, — и LLM каждый раз приходится заново находить и собирать релевантные фрагменты. Ничего не накапливается».

Традиционная альтернатива — вики, поддерживаемая вручную, — проваливается по обратной причине: люди плохи в поддержке. Как сказано в gist, «утомительная часть ведения базы знаний — не чтение и не размышление, а бухгалтерия». Обновлять перекрёстные ссылки, устранять противоречия, держать индекс согласованным — ровно та работа, которую люди молча перестают делать со временем.

Три слоя, два файла, три операции

Предлагаемая структура минимальна:

raw/           неизменяемые исходные документы; raw/assets/ для вложенийwiki/          markdown-страницы — пишет и поддерживает только LLM CLAUDE.md схема: соглашения и инструкции для агента index.md каталог всех страниц с однострочным описаниемlog.md         журнал только на дозапись обо всём, что сделала вики

А агент выполняет над ней три операции:

Ingest. Появляется новый источник; LLM читает его, обсуждает с вами выводы, пишет страницу‑резюме — и, это важная часть, обновляет десять или пятнадцать существующих страниц новыми связями и исправлениями.
Query. Вы задаёте вопрос; LLM маршрутизируется через индекс, читает нужные страницы и синтезирует ответ со ссылками на источники. Хороший ответ и сам может быть подшит обратно как новая страница.
Lint. Периодическая проверка здоровья: противоречия, страницы‑сироты, устаревшие утверждения, недостающие перекрёстные ссылки.

«Вы никогда не пишете вики сами — LLM пишет и поддерживает её целиком». «Работа человека — курировать источники, направлять анализ, задавать хорошие вопросы. Работа LLM — всё остальное».

[II] Как я это реализовал: вики поверх платёжного ядра

Это не мысленный эксперимент — вики построена и используется ежедневно. Она работает поверх крупной платёжной платформы: DDD + CQRS монолит примерно с двадцатью ограниченными контекстами и около 37 000 PHP‑файлов. Она не пытается проглотить всю систему — она покрывает самую сложную часть, платёжное ядро, дистиллированное ровно в 70 страниц.

Она живёт в .claude/wiki/ и намеренно добавлена в gitignore: это персональный слой синтеза, а не командная документация — и не замена README модулей, а слой поверх них. Вызывается она явной слэш‑командой — /wiki, описанной ниже; ничто не подгружается в контекст автоматически.

Как она устроена

.claude/wiki/├── CLAUDE.md     конституция: правила источников, шаблоны страниц,│                 чек-лист линта — единственный файл, который правит человек├── index.md      маршрутизатор: «если вы ищете X -> страница Y»,│                 известные противоречия, известные пробелы├── log.md        журнал только на дозапись├── contexts/     7 страниц  — по одной на ограниченный контекст├── providers/    8 страниц  — реестр платёжных провайдеров├── concepts/     10 страниц — сквозные доменные понятия└── flows/        5 страниц  — платёжные сценарии от начала до конца

Индекс заслуживает отдельного упоминания. Это не оглавление — это маршрутизатор. Его главный раздел — буквально таблица записей «если вы ищете X, откройте страницу Y», за которой следуют список известных противоречий и список известных пробелов. Рабочий процесс запроса начинается именно там: выбрать от трёх до семи страниц, пройти по ссылкам максимум на один уровень глубже, синтезировать. А если у вики нет ответа, правило такое: сказать «вики этого не покрывает» и предложить поглотить источник — а не тихо импровизировать по коду.

Анатомия страницы

Каждая страница следует одному и тому же контракту, который обеспечивает файл схемы:

---title: Провайдер A — обработка картtype: providerstatus: activeverified: 2026-07-14verified_sha: 3f9c2e1sources: ...---

Страница открывается вводным абзацем, отвечающим на вопрос «зачем вы сюда пришли», использует один уровень заголовков, всегда заканчивается разделом «Открытые вопросы» и должна укладываться в 120 строк. Когда страница перерастает бюджет, правило — разбить её на две связанные страницы, а не растягивать. И каждой странице нужны минимум две входящие ссылки, чтобы знание оставалось достижимым, а не осиротевшим.

Команда /wiki

Всё это завёрнуто в одну кастомную слэш‑команду, которую я создал для агента, — /wiki, описанную в .claude/commands/wiki.md. Это единственная точка входа: вне её вики никогда не трогают. Три операции Карпаты выросли в семь подкоманд:

/wiki seed                 первичное наполнение вики из кодовой базы/wiki ingest <источник>    поглотить документ, план или заметку из памяти/wiki query <вопрос>       ответить из вики, с маркерами достоверности/wiki sync [ref]           сверить страницы с кодом, который они описывают/wiki verify <страница>    перепроверить одну страницу по её источникам/wiki lint                 набор из 17 проверок здоровья/wiki status               дешёвая сводка здоровья только по frontmatter

Каждая подкоманда начинается с одной и той же обязательной предполётной подготовки: прочитать схему (CLAUDE.md вики), прочитать индекс, посмотреть последние записи журнала — чтобы агент всегда действовал по правилам вики, а не по своим привычкам. Основную работу делают две подкоманды:

sync — запускается после каждого git pull и после завершения задачи, перед merge request. Для каждой страницы он сравнивает код между SHA, на котором страница проверялась в последний раз, и текущим HEAD, ограничиваясь объявленными источниками этой страницы. Каждая затронутая страница получает один из трёх вердиктов: unchanged (сдвигается только отметка о проверке), corrected (дифф сделал страницу неверной — текст исправляется) или uncovered (новое поведение, которое не описывает ни одна страница, — предлагается новая страница).
lint — семнадцать автоматических проверок, выполняемых двумя параллельными подагентами в режиме только для чтения: противоречия, сироты, битые ссылки, превышения бюджета. Проверка, которую я ценю больше всего, перезапускает команду каждого отрицательного утверждения и отмечает любой grep, который перестал возвращать пустой результат.

[III] Подход, который я уже применял: README‑ориентированные репозитории

Задолго до этого gist я практиковал documentation‑as‑code. Документация там прошла собственную миграцию: из Confluence в репозиторий, рядом с кодом, который она описывает. Confluence не исчез — теперь он держит курируемое зеркало избранных страниц для менеджмента, отрисованное из репозитория через плагин GitHub. Инженеры читают и правят markdown рядом с кодом; менеджеры читают Confluence; источник истины ровно один.

Четыре уровня документации

application/├── README.md                 73 строки   карта: современные модули├── ARCHITECTURE.MD          921 строка   как система работает на самом деле├── modules/│   ├── README.md            952 строки   слои, именование, DI, тесты, чек-листы│   └── {Module}/README.md  ~300 строк    бизнес-ценность, аннотированное│                                         дерево файлов, поток данных└── docs/

Каждый уровень отвечает на свой вопрос. Верхний README отвечает: «что где лежит и что является легаси». Архитектурный рассказ отвечает: «как это на самом деле работает от начала до конца». Руководство по соглашениям отвечает: «как мне собрать здесь модуль». А README каждого модуля отвечает: «что этот модуль делает и зачем он существует» — лучшие из них открываются бизнес‑ценностью, проходят по аннотированному дереву всех своих 62 файлов и завершаются мониторингом и конфигурацией.

CLAUDE.md как маршрутизатор, а не контейнер

Ключевое решение в этой схеме: onboarding‑файл не содержит знание. Он маршрутизирует к нему. CLAUDE.md проекта открывается фиксированным порядком чтения — «перед выполнением любой задачи прочитай следующую документацию» — указывая на четыре уровня выше, а затем делегирует вниз: «Прочитай README соответствующего модуля перед работой с кодом этого модуля». В итоге агент читает два‑три документа, релевантных задаче, а не всё дерево. Прогрессивное раскрытие — ещё до того, как я узнал, что для этого есть термин.

И маршрутизация работает в обе стороны. Тот же CLAUDE.md делает обновление документации частью самой задачи: «Поддерживай README в актуальном состоянии. После внесения изменений в приложение обнови соответствующий README.md». Так что, завершив изменение, агент сам обновляет README модуля, которого коснулся, — дифф документации попадает в тот же merge request, что и дифф кода, и оба ревьюятся вместе. Никакого отдельного «дня документации», никакой задачи написать документацию потом: документация двигается вместе с кодом — или не двигается вовсе.

[IV] Одна идея, два масштаба

Поставленные рядом, эти два подхода похожи. Знание живёт рядом с кодом, в обычных файлах, под контролем версий. Входной файл маршрутизирует агента вместо того, чтобы набивать всё в его контекст. Чтение прогрессивное: сначала индекс, затем те два‑три документа, которые важны. Если ваш кодовый агент хорошо индексирует репозиторий, обе схемы дают ему одну и ту же суперсилу — он перестаёт переоткрывать вашу систему и начинает с ней сверяться.

Настоящая разница не в формате. Она в ответе на два вопроса: откуда берётся знание и кто ведёт бухгалтерию?

README пишет разработчик, про один модуль, по коду, который у него перед глазами. Вики в понимании Карпаты синтезируется LLM из всех источников, до которых она может дотянуться:

 Код      ↓  История git   ↓ README-файлы   ↓ Architecture Decision Records   ↓ Issues / Pull Requests   ↓ Рабочие чаты        ↓ Записи видеозвонков / транскрипты   ↓  LLM — читает, синтезирует, связывает   ↓  Граф знаний / Вики

Что даёт такое сравнение

--------------------+---------------------------+---------------------------                    | README на модуль          | LLM Wiki--------------------+---------------------------+---------------------------Кто пишет           | разработчики              | пишет LLM,                    |                           | человек курируетИсточники           | код модуля                | код, история git, README,                    |                           | ADR, задачи и PRЕдиница знания      | один модуль               | межмодульный синтезУстаревание         | ручные обновления — дрейф | определяется механически                    |                           | (диффы SHA, линт)Структура           | фиксируется заранее       | растёт вместе со знаниемОптимальный случай  | текущий проект            | огромные, разнородные                    |                           | объёмы знаний--------------------+---------------------------+---------------------------

[V] Когда вики не нужна

С другой стороны, я готов признать, что отдельная LLM‑вики нужна не каждому проекту. Если вы работаете с кодовым агентом, который хорошо индексирует репозиторий, — Claude Code, Cursor, Codex — и ваш репозиторий хорошо структурирован — чистый модульный код, README на каждый модуль, ясные границы DDD и архитектурные документы, — то значительная часть знания, которое даёт вики, уже доступна через поиск по репозиторию.

Вики становится ценной, когда самого репозитория уже недостаточно, чтобы отвечать на сквозные вопросы. Она добавляет слой синтеза для знания, которое естественным образом не принадлежит ни одному отдельному модулю: связи между ограниченными контекстами, потоки от начала до конца, сравнения провайдеров, архитектурные противоречия и проверенные утверждения, охватывающие несколько источников.

Так что выбор на самом деле не «README или вики». Хорошо структурированный репозиторий — это фундамент. Вики — дополнительный слой, который становится полезен, когда сложность системы порождает знание, которым не может чисто владеть ни одна отдельная часть кодовой базы.

Схема по умолчанию, которую я рекомендую

Для модульного проекта обычного размера я бы не начинал с вики. Я бы начал вот с этого:

docs/├── architecture/│   ├── overview.md         карта системы: контексты и границы│   └── payment-flow.md     потоки от начала до конца├── decisions/              ADR — «почему», а не только «что»├── modules/                по странице на модуль├── integrations/           внешние сервисы и их контракты└── development/            соглашения, как добавить модульAGENTS.md / CLAUDE.md       правила — и маршрутизация

Заключение

Уберите форматы — и оба подхода окажутся одной философией. Знание живёт рядом с кодом, в обычных файлах, версионируется как код. Входной файл — CLAUDE.md, index.md — это маршрутизатор, а не контейнер.

Лестница, как я её сейчас вижу:

Любой проект: README, который стоит прочитать, и CLAUDE.md, который маршрутизирует.
Модульные проекты: дерево docs/ — архитектура, решения, страницы модулей — с правилами «прочитай X, прежде чем трогать Y», вшитыми в файл агента.
За порогом сложности: вики, поддерживаемая LLM, с метаданными проверки, синтезирующая то, что не содержит ни один отдельный документ.

С чего начать

Превратите свой CLAUDE.md в маршрутизатор. Порядок чтения, правила «прочитай X, прежде чем трогать Y», указатели вместо содержимого. Если он длиннее страницы — значит, он держит знание, место которому в другом файле
Создайте скелет docs/. architecture/, decisions/, modules/, integrations/, development/ — даже с тремя файлами внутри эта структура говорит и людям, и агентам, где живёт знание
Напишите ADR для решений, о незаписанности которых вы уже жалеете. «Почему» — единственная часть вашей системы, которую агент не может вывести заново из кода
Перестаньте перечислять то, что может вывести команда. Указывайте на ls, дампы роутов, конфиги. Списки дрейфуют; файловая система — нет
За порогом — засейте вики поверх самой сложной подсистемы. Скопируйте gist Карпаты своему агенту, направьте его на тот единственный домен, где каждый ответ живёт в пяти местах, и дайте ему написать те семьдесят страниц, которые вы не напишете никогда
Сделайте свежесть механической. Привяжите каждую синтезированную страницу к коммиту, относительно которого она была проверена, и сделайте «дифф прочитан» условием переноса этой привязки. База знаний, которую нельзя проверить на устаревание, — это фабрика слухов с хорошим форматированием

Источники

ссылка на оригинал статьи https://habr.com/ru/articles/1063946/