Вікі проєкту: пам'ять, яку AI-агенти вміють читати й писати

Агенти все забувають між сесіями

Якщо ви щодня працюєте з AI-агентом для коду, ви знаєте, як це буває. Відкриваєте нову сесію, а агент нічого не знає про проєкт. Він не знає, чому ви обрали саме цю базу даних і що минулого тижня один модуль видалили.

Тож агент або читає пів кодової бази, щоб відновити картину, а це довго й дорого, або вгадує, і це ще гірше.

Код показує агенту, що є, але не пояснює, як усе має працювати і чому. Нам потрібне було одне місце, яке відповідає на питання «як це має працювати?» і яке агент прочитає за секунди.

Таке місце — вікі проєкту.

Що таке наша вікі насправді

Жодного окремого сервісу. Наша вікі — це дві речі:

Obsidian-сховище (vault). Тека зі звичайними Markdown-файлами у власному git-репозиторії. У нашому репозиторії коду вона лежить у docs/wiki/. Сторінки посилаються одна на одну через [[wikilinks]], тож колеги теж читають вікі в Obsidian, а виправлення, яке зробила людина, кожен агент побачить уже в наступній сесії.
Скіли, які вчать агента читати й писати вікі. Скіл — це короткий файл з інструкціями, який Claude Code підвантажує, коли він потрібен. Ми використовуємо відкритий набір obsidian-skills: obsidian-markdown (wikilinks, callouts, frontmatter), obsidian-bases, json-canvas, obsidian-cli і defuddle (перетворює вебсторінку на чистий Markdown). А правила, що потрапляє у вікі і як сторінки змінюються, записані у звичайному файлі правил — про нього нижче.

Вікі — це просто файли, тому агент читає її тими самими інструментами, що й код.

Патерн: «LLM Wiki» від Karpathy

Саму форму вигадали не ми. Андрій Карпати описав її у своїй нотатці LLM Wiki. У ній три шари:

Сирі джерела. Те, що дає людина: специфікація, нотатки зі зустрічі, стаття. LLM їх ніколи не редагує.
Вікі. Сторінки, які LLM пише й підтримує актуальними.
Схема. Один файл з правилами (у нас це CLAUDE.md), який пояснює агенту, як організована вікі і як її вести.

І три операції: ingest (додали джерело — LLM оновлює всі сторінки, яких воно стосується), query (поставили питання — отримали відповідь з посиланнями на сторінки) і lint (перевірка здоров'я: биті посилання, суперечності, застарілі твердження).

У нас це виглядає приблизно так:

docs/wiki/
├── CLAUDE.md      # правила: як агенти читають і ведуть вікі
├── index.md       # мапа: один рядок на сторінку
├── hot.md         # що змінилося за останні 7 днів
├── log.md         # короткий журнал кожного проходу куратора
├── concepts/  features/  decisions/  conventions/
└── sources/       # сирі матеріали від людини, не редагуються

Трекер плюс вікі: повна картина

Агент, який бере задачу, має два питання: що мені зробити? і як влаштована система і які правила тут діють? Відповіді він бере з двох джерел.

Трекер відповідає на «що». У задачі — запит словами самої людини. Кожен попередній етап нашого процесу (інтерв'ю, вимоги, декомпозиція) залишає на ньому свій артефакт. Про ці етапи ми розповідаємо в статті Досить писати промпти: навіщо AI-агентам робочий процес.
Вікі відповідає на «як». Концепції, фічі, рішення й конвенції описують систему та її правила.

Разом вони дають агенту повне джерело контексту, і що саме читати, агент обирає сам. Ми не вклеюємо в промпт заздалегідь зібраний набір файлів. Агент відкриває index.md (мапу) і hot.md (зміни за тиждень), вибирає сторінки, потрібні саме для цієї задачі, і далі йде за посиланнями. Кілька кілобайтів тексту замість довгої мандрівки кодом.

Агент-розробник сприймає вікі як специфікацію, і для нього вона лише для читання. Куратор вікі — останній крок. Після рев'ю коду агент-куратор читає реальний diff і виправляє кожну сторінку, яку зміна зробила неправдивою. Потім відкриває pull request у репозиторій вікі, а людина його мерджить.

Коли агент помічає вашу помилку

Надійний контекст не лише економить час. Він дає агенту змогу помітити, що помиляється людина.

Тут головну роль грають сторінки рішень. Сторінка рішення, або ADR (architecture decision record), — це коротка нотатка: що ми вирішили, чому і від чого відмовились. Наприклад: «усі часові мітки зберігаємо в UTC, а в локальний час переводимо лише в інтерфейсі». І через пів року вона відповідає на питання «чому зроблено саме так?».

Тепер уявіть запит, який непомітно суперечить рішенню, ухваленому командою місяць тому. Можливо, людина про нього забула, а можливо, справді передумала. Без вікі агент просто зробив би, що сказано. З вікі він натрапляє на сторінку рішення, поки читає матеріали до задачі, і бачить суперечність. Тому він зупиняється, називає це рішення і питає, що має переважити: змінити рішення чи це була описка в запиті?

Корисна будь-яка відповідь. Помилка, яку впіймали рано, — це зміна, яку не доведеться відкочувати. А якщо команда справді передумала, оновлюється сторінка рішення, і наступний агент читатиме вже нове правило, а не старе.

Правило, яке тримає вікі корисною: переписуй, а не дописуй

Цього ми навчилися на власних помилках. Спочатку кожна задача додавала на сторінку власний розділ: «додано в задачі X», «змінено в задачі Y». Нічого не губилося, тож здавалося, що це безпечно. За кілька місяців одна сторінка розрослася приблизно до 540 KB. Вона досі описувала давно видалені компоненти як живі, і агент вірив кожному слову.

Тепер правило просте. Сторінка описує систему такою, якою вона є сьогодні. Якщо зміна робить речення хибним, куратор переписує саме це речення. Історія живе в git і в log.md, а не на сторінці. Ще кілька правил тримають вікі компактною:

Кожна сторінка менша за 30 KB. Більшу стискають або ділять на кілька.
Коли код видаляють, його сторінка стає короткою заглушкою «deprecated» з посиланням на заміну. Старі посилання далі працюють.
План, який ще не реалізований, — це сторінка рішення з позначкою «accepted, not yet implemented», а не сторінка поточного стану.
Перед відкриттям pull request скрипт-лінтер перевіряє розміри, frontmatter і посилання.

У підсумку маємо кілька сотень коротких сторінок: кожна про одну тему, і всі правдиві сьогодні.

Корисно й людям

Новий колега може відкрити те саме сховище, почати з індексу й пройтися графом. Тімлід може прочитати сторінку рішення й зрозуміти, чому щось зроблено саме так.

Створіть свою

За цим не стоїть жодних особливих інструментів. Це Obsidian-сховище в git-репозиторії, obsidian-skills для Claude Code і один короткий файл з правилами. Покрокове налаштування ми розібрали в статті Як за 30 хвилин створити вікі проєкту для AI-агентів.