Коли одного AGENTS.md вже недостатньо. Досвід побудови Cascade Context Mapping

💡 Усі статті, обговорення, новини про тестування — в одному місці. Приєднуйтесь до QA спільноти!

Мене звати Євген Герасимов, я Automation QA Team Lead у Helsi — великому SaaS-продукті в healthcare-домені. Останній рік я активно використовую AI-агентів у роботі: спочатку для простих речей, на кшталт написати тест або пояснити шматок коду, потім — для складніших задач. Чим ширше я почав використовувати агентів, тим більше контексту їм було потрібно. Під час виконання задач я помічав помилки, які робить агент, і додавав це в його інструкції. Додавав правила, приклади коду, уточнення щодо модулів і тестових підходів. Часто сам агент допомагав створювати для себе цю документацію. З часом вона почала розростатися, і я почав розділяти її на окремі скіли. Так я прийшов до підходу, який для себе назвав Cascade Context Mapping: способу організувати документацію репозиторію так, щоб агент не читав усе підряд, а рухався по зрозумілому маршруту.

Спочатку все виглядало логічно

Коли я тільки починав інтегрувати агентів у роботу, усе стартувало досить просто. Першу версію файлу AGENTS агент згенерував сам: базові правила, загальний опис проєкту, кілька орієнтирів для роботи з кодом. Спочатку цього вистачало. Потім я почав поступово розширювати файл: додавати правила написання тестів, опис модулів, структуру директорій, принципи роботи з даними, домовленості команди. З кожною новою задачею хотілося зафіксувати ще одне правило, щоб агент наступного разу не помилявся.

Паралельно я почав додавати окремі скіли для конкретних задач. У них прописував правила, процедури, приклади коду, типові кроки для API-тестів, UI-тестів, білдерів та інших повторюваних сценаріїв. На той момент це виглядало логічно: є новий патерн — додаєш інструкцію або додаєш правило існуючу. Перший час такий підхід працював.

Потім почали проявлятися обмеження

Наш продукт — мікросервісна система з великою кількістю функціональних модулів. У різних сервісів свої сутності, свої API, свої правила поведінки. З боку автоматизації картина схожа: UI й API-тести, різні патерни, перевикористовувані компоненти, спільні бібліотеки, доменні правила, які стосуються тільки окремих частин системи.

З часом я почав помічати, що агент іноді все одно робить помилки, які вже ніби були зафіксовані в правилах. Або тягне в одну задачу правила з кількох доменних областей і починає змішувати їх між собою. Мав написати тест для одного модуля, але враховував поведінку іншого. Мав оновити один API-тест — підтягував стандарти не того сервісу.

Проблема була не в тому, що правила не працювали взагалі. Вони працювали, але не завжди передбачувано. Що більше інструкцій я додавав, то важче ставало контролювати, які саме з них агент застосує в конкретній задачі. Спочатку я працював переважно з Claude Code. Пізніше переключився на Codex, а вже після цього перевірив той самий підхід у Gemini CLI. Інструменти відрізнялися в деталях, але загальний патерн залишався тим самим. У якийсь момент стало очевидно що проблема в тому, що я поступово навчив систему тягнути в контекст занадто багато всього.

Кастомні скіли допомогли, але ненадовго

Наступний крок теж здавався логічним: розбити один великий файл на кастомні скіли під різні типи задач. Окремий скіл для API-тестів, окремий для UI, окремий для білдерів. Кожна задача отримує свій набір правил, агент не читає зайвого.

Стало краще. Але з часом вилізла інша проблема. Деякі правила природно повторювались у кількох скілах. Наприклад, як писати контролер для API-тесту або як реалізовувати білдер. Спочатку це не боліло. Але коли правило змінювалось, я оновлював його в одному місці й забував про копії в інших. У результаті одне й те саме правило могло існувати у трьох версіях одночасно: актуальна — у стандарті, дві застарілі — у скілах. Агент читав той файл, який першим потрапляв у контекст, і працював за ним. Іноді це була правильна версія, іноді ні.

Тоді я сформулював для себе друге правило: інструкції не можна копіювати «для зручності». Кожне правило має жити рівно в одному місці, а скіли мають на нього посилатися.

Context Explosion і дублювання

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

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

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

Як з цього почав складатися каскад

Поворотний момент стався, коли я подивився на дублювання правил як на окрему проблему. Якщо одне й те саме правило потрібне у двох скілах, його не треба копіювати двічі. Краще винести правило в окремий файл, а в скілах залишити посилання.

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

З цього я почав перебудовувати всю документацію. Спочатку скіл став головним робочим елементом для конкретної задачі. Під ним з’явилися вторинні інструкції: спільні стандарти, правила написання коду, доменні особливості, описи сутностей, інфраструктурні нотатки. Так поступово й вималювався каскад: не один великий файл і не набір розрізнених інструкцій, а структура, де контекст відкривається рівнями.

AGENTS у цій схемі став вхідною точкою — картою контексту, яку агент читає на старті сесії, щоб зрозуміти, куди рухатися далі. Саме тоді я сформулював для себе головну думку — агенту не потрібна вся інформація про проєкт одразу. Йому потрібен зрозумілий маршрут до правильної інформації.

Що таке Cascade Context Mapping

Якщо коротко, Cascade Context Mapping — це метод організації документації репозиторію для команди й AI-агентів. Не набір випадкових Markdown-файлів, а маршрутизована структура: що читати спочатку, куди йти далі, де живе конкретне правило і хто за нього відповідає.

Головна ідея проста: не давати агенту весь контекст одразу, а дати маршрут до нього. Спочатку агент отримує короткий опис проєкту й навігацію. Потім визначає тип задачі. Після цього відкриває тільки ті інструкції, які справді потрібні. Усе інше залишається поза контекстом.

Схематично це виглядає так:

Я назвав це каскадом, бо контекст відкривається шар за шаром. Якщо я пишу UI-тест для конкретного модуля, агент не читає правила інших сервісів. Якщо задача стосується однієї сутності, документація про решту не потрапляє в контекст. Це схоже на те, як людина заходить у новий проєкт: ніхто не читає весь репозиторій з першого рядка. Спочатку потрібна карта, потім конкретний модуль, потім деталі.

Як це влаштовано на практиці

CCM складається з кількох шарів. У кожного є своя відповідальність. Root Router — головна точка входу. У різних інструментах це може бути файл CLAUDE, GEMINI або AGENTS. Важливо, щоб він був коротким і стабільним: опис проєкту, карта доступних скілів, правила навігації. Без великих чеклістів і шаблонів реалізації.

Primary Skills — інструкції для конкретних типів задач: додати API endpoint, створити UI-компонент, написати тест, оновити документацію. Скіл відповідає на питання: коли його використовувати, які стандарти прочитати, у якому порядку працювати і як перевірити результат. Самі правила він не дублює, а посилається на них.

Shared Standards — правила, які використовуються в багатьох скілах: TypeScript style, API contracts, test strategy. Саме тут мають жити речі, які раніше легко розповзались копіями по різних файлах.

Domain Rules — бізнес-логіка на рівні продуктових зон: authentication, billing, notifications. Вони потрібні, коли задача вимагає розуміння бізнес-контексту, але цей контекст не належить одному конкретному артефакту.

Entity Rules — правила для ключових бізнес-сутностей: поля, зв’язки, ризики, типові помилки при роботі з ними.

Infrastructure Notes — середовище, CI/CD, бази даних, env variables. Не загальний README, а відповідь на конкретне питання: що треба знати, щоб коректно запустити або перевірити задачу.

Manual Commands — повторювані workflows для агента або CLI: pre-push review, migration audit, flaky test analysis, release checklist. Вони теж не мають дублювати правила, а мають підвантажувати потрібні стандарти через посилання.

Головне правило тут одне — кожне знання має мати своє місце. Якщо правило вже є у стандартах, скіл ставить посилання, а не копіює його. На практиці це дуже схоже на ownership matrix: стабільні правила проєкту живуть у root-router або shared standards, процедура створення артефакту — у відповідному skill, бізнес-логіка — у domain/entity файлах, інфраструктура — в infrastructure notes, повторювані workflow — у manual commands. Це звучить бюрократично, але в реальності навпаки зменшує хаос. Коли з’являється нове правило, не треба думати «куди б його ще скопіювати». Треба відповісти на прості питання: кого воно стосується, як часто змінюється і чи не дублює вже існуюче правило.

Cascade Rule

У центрі CCM є просте правило руху по контексту.

Агент не починає з глобального пошуку по всьому репозиторію. Спочатку він читає root-router, обирає primary skill, відкриває Required Context, за потреби підключає related skills, і тільки після цього шукає в коді вже в конкретній області.

Тобто порядок такий:

root-router

-> primary skill

-> required standards / domain / entity / infrastructure

-> targeted code search

-> implementation

-> verification

Це важлива відмінність. У звичайному підході агент часто починає з широкого пошуку й сам намагається зрозуміти, що важливо. У CCM документація спочатку звужує простір задачі, а вже потім агент іде в код. Звісно, якщо задача містить точну назву файлу, класу, методу, endpoint або текст помилки — прямий пошук має сенс. Але для широких запитів на кшталт «як додати API endpoint» або «як працює billing flow» краще спочатку пройти маршрутом.

Чому це працює: JIT і ручний RAG

Коли я почав розбиратися, чому такий підхід дає кращий результат, побачив у ньому поєднання двох знайомих ідей.

Just-in-time — отримувати знання або ресурси тоді, коли вони потрібні, а не наперед. Агент не читає всю документацію на старті. Він отримує контекст у момент, коли задача цього вимагає.

RAG (Retrieval-Augmented Generation) — але тут є важлива різниця. Класичний RAG — це інфраструктура: векторна база, embedding search, pipeline для підвантаження релевантних фрагментів. Це має сенс, коли контексту дуже багато: тисячі документів, великі кодові бази, корпоративні knowledge bases. CCM працює на іншому масштабі. По суті, це ручний RAG через структуру файлів. Агент сам доходить до потрібного контексту через зрозумілу маршрутизацію. Без векторної бази, без окремого pipeline, без додаткової інфраструктури. Для невеликих і середніх проєктів, де контекст ще можна структурувати вручну, це дає більше контролю. RAG автоматизує пошук релевантного контексту. CCM робить цей контекст передбачуваним ще до пошуку.

CCM за межами коду: генератор тест-кейсів

Зараз ми будуємо власний інструмент генерації тест-кейсів для тестувальників. Архітектура контексту там побудована за тим самим принципом каскаду, тільки замість інструкцій для агента описані сутності продукту і бізнес-логіка.

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

Це стало підтвердженням, що CCM — не просто спосіб розкласти файли в репозиторії. Це принцип організації знань для AI: неважливо, що саме генерується — код, тести чи тест-кейси.

Що змінилося на практиці

Я не проводив формальних вимірювань токенів і не хочу робити вигляд, що маю точні цифри. Але є речі, які бачу в роботі щодня.

Агент рідше плутає правила різних модулів. Оновлення правила в одному місці справді оновлює правило, а не програє застарілому дублю в іншому файлі. Документацію стало простіше підтримувати.

І найважливіше для мене що кількість ітерацій після генерації коду скоротилась приблизно вдвічі. Це не лабораторна метрика, але в реальній роботі вона дуже відчутна. За рахунок того що агент не перевантажений контекстом він генерує код більш точно

Висновок

CCM — не фреймворк і не академічна методологія. Для мене це практичне поєднання знайомих принципів: single source of truth, separation of concerns, just-in-time loading. Просто застосоване до задачі, з якою стикається кожен, хто працює з AI-агентами у великих проєктах. Я не відкрив нічого принципово нового. Я просто пройшов через кілька конкретних помилок: один великий файл, потім розрізнені скіли з дублями, потім неконсистентність між правилами. І врешті знайшов структуру, яка працює в реальній щоденній роботі. Можливо, через рік агенти з коробки стануть настільки кращими, що частина цих проблем зникне сама. Але зараз я все більше переконуюся: організація знань для AI — це окрема інженерна задача. І її варто вирішувати свідомо.