Вікі, трекер і граф коду замість RAG для AI-агентів
Питання, на яке відповідає кожне налаштування агента
AI-агент для коду починає кожну сесію, нічого не знаючи про ваш проєкт. Він не знає архітектури, домовленостей команди чи рішення, яке ви ухвалили минулого місяця. Перш ніж він почне писати код, цю прогалину треба чимось заповнити.
Ми дивимося на це під одним кутом: команда агенції, яка робить сайти й застосунки для клієнтів. Зазвичай це кілька проєктів одночасно, і в кожного свій стек, своя історія та рішення, які погодив клієнт. Задача агента — змінити реальний код і не зламати те, про що домовилися.
Найпоширеніша відповідь — RAG (retrieval-augmented generation, генерація з пошуком): система знаходить текст, схожий на потрібний, і вставляє його в промпт. Наше налаштування з CRUX іде іншим шляхом. Агент отримує три джерела — вікі проєкту, трекер задач і граф коду — і сам вирішує, що з них читати.
У статті пояснюємо, чому так, і де RAG усе ж кращий.
Як працює RAG, простими словами
RAG-конвеєр ріже документи, а часто й код, на шматки по кілька сотень слів. Кожен шматок перетворюється на embedding — список чисел, що передає його зміст, — і зберігається у векторній базі. Коли надходить питання, система знаходить кілька найближчих шматків і вставляє їх у промпт.
Для бота підтримки це працює добре. Але для агента, який змінює реальну систему, тут є відомі слабкі місця. Шматок втрачає оточення: заголовок над ним, виняток у наступному абзаці. Старий і актуальний текст, схожі за змістом, конкурують, і пошук не знає, котрий правдивий сьогодні. Агент не бачить, чого йому не дали. А ще хтось має підтримувати сам конвеєр: нарізку, embeddings, переіндексацію, базу.
Три джерела, які агент читає сам
У нашому налаштуванні кожне джерело відповідає на своє питання:
- Трекер відповідає на «що» і «що було раніше». У задачі — запит словами самої людини, коментарі та артефакти, які на ній залишили попередні агенти.
- Вікі відповідає на «як» і «чому». Це Obsidian-сховище: звичайні Markdown-файли в git, сторінки пов'язані через
[[wikilinks]], вхідна точка —index.md. Концепції, фічі, рішення й конвенції, одна тема на сторінку. Докладніше — у статті Вікі проєкту: пам'ять, яку AI-агенти вміють читати й писати. - Граф коду відповідає на «де» і «що від цього залежить». Ми використовуємо GitNexus — інструмент з відкритим кодом, який індексує кодову базу в граф знань: символи, виклики, залежності й потоки виконання. Агент звертається до нього через MCP-інструменти: хто викликає цю функцію, які потоки через неї проходять, що може зламатися, якщо її змінити. Замість «знайди код, схожий на запит» він отримує точну відповідь зі структури коду. Перш ніж брати його в роботу, перевірте ліцензію.
Сучасні агенти для коду, як-от Claude Code, мають довге контекстне вікно та інструменти для роботи з файлами. Вони відкривають індекс вікі, переходять за посиланнями, шукають grep-ом, читають цілі сторінки й запитують граф — так само, як працюють із кодом. Ніщо не відібрано заздалегідь за оцінкою схожості. Якщо агенту треба більше, він читає більше. Якщо менше, він зупиняється: у контекстному вікні лише те, що потрібно цій задачі, а не всі шматки з високою оцінкою. Невеликий контекст допомагає агенту не розпорошуватися.
Ось п'ять причин, чому нам це подобається більше за RAG.
1. Це легко налаштувати
Вікі — тека з Markdown-файлами в git. GitNexus будує індекс локально однією командою analyze. А трекер у вашої команди вже є.
Не треба ні конвеєра embeddings, ні векторної бази, ні суперечок про те, як різати текст, ні переіндексації за розкладом. Коли відповідь хибна, ви відкриваєте Markdown-файл і виправляєте речення, а не налагоджуєте оцінки схожості. Покрокове налаштування — у статті Як за 30 хвилин створити вікі проєкту для AI-агентів, а відкритий набір obsidian-skills вчить Claude Code писати Obsidian Markdown.
2. Людина контролює процес у звичних інструментах
RAG — прихований крок. Ніхто не перевіряє, які шматки потрапили в промпт, і ніхто не може їх виправити.
У нашому налаштуванні люди стежать за роботою агента там, де працювали завжди: у задачах, коментарях, статусах і рев'ю pull request. Кожен агент публікує результат як артефакт у задачі: відповіді з інтерв'ю, вимоги, план, опис зміни. На контрольних точках, де хибний поворот ще дешево виправити, людина схвалює чи виправляє його, перш ніж на нього спиратимуться наступні кроки. Цей ланцюжок ми описали в статті Досить писати промпти: навіщо AI-агентам робочий процес.
Тож контекст, з яким працює агент, і рішення, ухвалені дорогою, видно і їх можна змінити. Якщо артефакт хибний, людина виправляє його просто в задачі, і всі наступні агенти читають уже виправлену версію.
3. Методи, що працювали до AI, працюють і далі — тож ми взяли Agile
Ми не вигадували нової методології для AI. Епіки, сторі, задачі, чіткі критерії приймання, невеликі інкременти, рев'ю коду й ретроспективи існували задовго до агентів.
Добре написана задача допомагала розробнику-людині зрозуміти, що треба зробити. Агенту вона допомагає так само. Чіткий критерій приймання веде краще за будь-який знайдений абзац, а невеликий інкремент тримає помилку маленькою і легкою для рев'ю.
Поверх цього працює структурований робочий процес. Кожен статус задачі має свого агента, скіли й правила, а наступна сесія стартує з готового шаблону в один клік. Ніхто не вигадує промпт для кожної задачі, сесії для різних задач ідуть паралельно, і розробка рухається швидше.
4. «Чому цей код написаний саме так?»
На це питання RAG відповідає найгірше. Текст, схожий за змістом, рідко пояснює конкретний рядок.
У нашому репозиторії кожне повідомлення коміту містить ключ задачі, а git-хук відхиляє коміт без нього. Коротка інструкція в CLAUDE.md, файлі правил агента, пояснює, як цим користуватися. Коли агенту треба зрозуміти, навіщо існують певні рядки, він запускає на них git log -L або git blame, бере з коміту ключ задачі й відкриває задачу.
Так він отримує початковий запит, обговорення в коментарях і артефакти — тобто намір, що стоїть за кодом. Це одна git-команда й одне читання задачі, і результат точний. Жоден пошук за схожістю так не вміє.
5. Зв'язки між задачами показують сусідство
Задачі пов'язані: блокує, заблокована, батьківська, пов'язана. Агент іде за цими зв'язками так само, як за wikilinks. Він бачить, що зробили перед цією задачею, що на неї чекає і які раніші задачі торкалися тієї самої частини системи. Саме там часто й ховаються справжні обмеження, а пошук top-k просто не знає, що їх треба шукати.
Вікі лишається правдивою, бо її доглядають
Самостійне читання допомагає, лише якщо прочитане правдиве. У нашому конвеєрі після рев'ю коду останнім кроком іде агент-куратор вікі. Він читає реальну зміну й переписує кожну сторінку, яку вона зробила хибною, тож сторінка описує поточний дизайн, а не журнал змін. Історія живе в git. Люди читають і виправляють ті самі файли в Obsidian.
Надійне джерело змінює й поведінку агента. Якщо запит непомітно суперечить рішенню, яке команда ухвалила раніше, агент натрапляє на сторінку цього рішення, поки читає матеріали до задачі. Він бачить суперечність і ставить уточнювальне питання, а не будує на хибному припущенні.
Поруч
| RAG | Вікі + трекер + граф коду | |
|---|---|---|
| Хто вибирає контекст | Пошук за схожістю, ще до старту агента | Сам агент, під час роботи |
| Що читає агент | Шматки по кілька сотень слів | Цілі сторінки, задачі й точні відповіді графа |
| Навантаження на контекст | Фіксований top-k, корисний чи ні | Лише те, що потрібно задачі |
| Актуальність | Як на момент останньої переіндексації; старе й нове конкурують | Сторінки вікі переписують після кожної зміни; граф перебудовують з коду |
| Налаштування | Нарізка, embeddings, векторна база, переіндексація | Markdown у git, одна команда analyze, ваш трекер |
| Контроль людини | Прихований крок, який ніхто не перевіряє | Артефакти в задачах, які люди схвалюють чи виправляють |
| «Навіщо цей код?» | Здогадка зі схожого тексту | Коміт, потім ключ задачі, потім задача |
| Для чого добре | Великі безладні масиви, які ніхто не впорядковуватиме | Задачі, дизайн, рішення й структура проєкту |
Коли ми все ж узяли б RAG
У багатьох випадках RAG — саме той інструмент, що потрібен:
- Масив даних величезний або неструктурований. Тисячі звернень до підтримки, роки листування в чатах, полиця PDF-файлів. Жоден агент усього не прочитає, і ніхто не перетворить це на вікі.
- Ніхто не доглядатиме за вмістом. Вікі, яку ніхто не оновлює, застаріває. А пошуковий індекс по сирих матеріалах хоча б чесно є тим, чим є.
- Пошук іде по багатьох проєктах. «Хто вже розв'язував таке?» серед десятків репозиторіїв — це задача пошуку.
- Модель не має інструментів для файлів. Звичайна чат-модель, яка не вміє відкривати файли, потребує, щоб текст для неї хтось вибрав.
А ще агенція часто вбудовує RAG у продукт клієнта: бот підтримки, пошук по документах клієнта. Це функція продукту, і там RAG доречний. Ця стаття про інше: як агенти вашої власної команди розуміють проєкт, який вони будують.
Обидва підходи можуть співіснувати
Це не вибір «або-або». Команда може тримати RAG над сирими архівами — старими зверненнями до підтримки чи розшифровками дзвінків — а вікі, трекер і граф коду залишити джерелом правди. Агент шукає в архіві зачіпки, а потім перевіряє у вікі, що діє сьогодні. Якщо вони розходяться, перемагає вікі. А якщо в архіві знайшлося щось справжнє, куратор переносить це на сторінку.
Ціна нікуди не зникає, вона переміщується
Читання не безкоштовне: агент витрачає токени на цілі сторінки й задачі. Але читає він лише те, що потрібно задачі, зазвичай кілька коротких сторінок, задачу і кілька запитів до графа. Фіксований top-k шматків заповнює контекст незалежно від того, чи вони допомагають, і кожен зайвий шматок — шум, який агенту доводиться обходити. Дуже допомагає, коли сторінки короткі й кожна про одну тему.
Натомість ви економите на конвеєрі й отримуєте контроль. Трекер зберігає задачу та її історію, вікі — поточний дизайн і рішення, граф — точну структуру коду, а зв'язок коміту із задачею веде від коду назад до наміру. Що читати, агент обирає своїми інструментами. RAG вибирає за нього.