Як зрозуміти, що AI-агент втратив контекст: state-canary в AGENTS.md і CLAUDE.md

Найдорожча помилка AI-агента — не та, на якій він спотикається і просить допомоги. Дорога помилка — та, яку він робить упевнено: посилається на функцію, якої немає, «згадує» обмеження, якого ви не давали, переписує те, що п’ять ходів тому домовилися не чіпати. Тон відповіді не змінюється. Змінюється лише якість — а ви дізнаєтеся про це на рев’ю, коли вже витратили годину.

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

Ця стаття — про дешевий прийом спостережуваності (observability), який робить таку втрату видимою: state-canary — рядок стану, який агент друкує на початку кожної відповіді прямо за інструкцією з AGENTS.md або CLAUDE.md. Після статті у вас буде copy-paste блок, який можна покласти в проєкт сьогодні, і протокол дій на випадок, коли канарка спрацювала.

Якщо базову пам’ять агента у вас ще не вибудувано, почніть з AI-агентів у робочому процесі розробника — там розібрано патерн AGENTS.md/CLAUDE.md, на якому стоїть усе подальше.

Кому це корисно — і коли не варто морочитися

Прийом не універсальний, і чесніше окреслити межу одразу.

І навпаки — не витрачайте на це час, коли:

• ставите коротке разове запитання або розв’язуєте задачу на 5–10 хвилин;
• агент узагалі не змінює код (пояснення, рев’ю, пошук);
• важливіше перевірити факти, ніж відстежити контекст, — там працює не канарка, а тести й джерела.

Проблема: агент упевнений, але вже не пам’ятає домовленостей

Небезпечна не сама помилка, а її невидимість. Агент тримає рівний тон незалежно від того, спирається він на актуальний контекст чи на його уривки. Отже, потрібен зовнішній індикатор — щось дешеве й завжди на виду, що ламається раніше, ніж ламається результат.

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

Чому втрачається робочий контекст

Сучасні моделі Claude і Codex можуть добре працювати, коли потрібний контекст фізично перебуває у вікні. Але частина упевнених помилок у довгих сесіях виникає не через «дурість моделі», а через те, що робочий контекст витіснений, розмитий або став гірше використовуватися. Механізмів кілька.

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

Компакція та сумаризація. Claude Code стискає довгу історію — командою /compact або автоматично при заповненні вікна. Тут потрібна точність, бо узагальнення «/compact втрачає CLAUDE.md» неправильне. Project-root CLAUDE.md переінʼєктується після компакції; а от вкладені CLAUDE.md у підкаталогах самі не повертаються, доки агент знову не прочитає файл у цій директорії. І головне — інструкції, що жили лише в розмові, плюс деталі поточної задачі можуть випасти з ефективного робочого стану, навіть коли кореневу пам’ять перечитано. Тому активну задачу я тримаю не в чаті, а в окремому markdown-файлі і перечитую його після reset або compact.

Context rot. Навіть без жорсткого обрізання точність падає в міру зростання контексту — документація Anthropic про контекстне вікно прямо описує деградацію recall зі збільшенням обсягу. Падіння плавне: немає точки, де «все зламалося», і саме тому оком його не помітити.

Lost in the middle. Інструкція може фізично бути у вікні, але стояти в його середині. Моделі надійніше відтворюють те, що на початку і в кінці контексту, ніж затиснуте посередині, — це ефект, описаний у дослідженні «Lost in the Middle». Важливе правило, оточене великим обсягом тексту, дотримується гірше.

Рівень 1. Найпростіша канарка

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

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

## Output format

Start every response with: "Олексію,"
No exceptions, even for one-line answers.

Поки звертання на місці — верхні інструкції файлу ще дотримуються. Ось як виглядає зрив на практиці:

Хід 4:  Олексію, оновив роути, ось дифф...
Хід 19: Готово. Виправив конфіг, перегенерував кеш...
        ^ звертання зникло — час перевірити, що ще з'їхало

Важливо: тримайте цю інструкцію короткою. Codex збирає ланцюг інструкцій із кількох AGENTS.md-файлів, і в project guidance є обмеження розміру. Канарка має бути одним рядком, а не окремим регламентом.

Цього вже достатньо, щоб насторожитися. Але префікс з імʼям фіксує лише факт збою, а не його зміст.

Чому ім’я — лише перший рівень

Ім’я дає бінарну відповідь: правило дотримується чи ні. Воно не скаже, що саме з’їхало — задача, межа дозволеного чи карта проєкту. Щоб канарка ставила діагноз, у неї треба покласти стан.

Рівень 2. State-canary: task / scope / constraint

Нехай агент друкує один рядок, що відображає активний контекст:

Before answering, print exactly one line:

[state: task=<task-slug>; scope=<allowed-area>; constraint=<main-constraint>]

If any field is unclear, write "unknown".
Do not invent missing state.

Три поля обрані не випадково: task відповідає на «над чим ми», scope — «де можна чіпати код», constraint — «чого робити не можна». Ось як це читається в реальній задачі:

[state: task=paywall-refactor; scope=WordPress/Timber templates only; constraint=no vendor patching]

Знайшов місце, де paywall-логіка все ще зав'язана на vendor override...

Якщо на наступному ході constraint стане unknown або scope виросте сам собою — ви побачите це раніше, ніж агент полізе правити код вендора. Правило Do not invent missing state тут ключове: хай краще чесно напише unknown, ніж намалює правдоподібне поле за інерцією.

Нормальний хід:

[state: task=paywall-refactor; scope=WordPress/Timber templates only; constraint=no vendor patching]

Перевіряю лише шаблони Timber, vendor не чіпаю.

Підозрілий хід:

[state: task=paywall-refactor; scope=unknown; constraint=unknown]

Я можу виправити vendor-файл напряму...

Ось це і є момент зупинки: агент ще говорить упевнено, але маркер уже показує, що робочі межі задачі втрачено.

Чому не turn counter

Спокусливо додати в маркер лічильник ходів — виглядає акуратно й «спостережувано». Я його не використовую: модель може вести лічбу механічно, скидати її чи підганяти, і при цьому контекст уже деградував. task, scope і constraint підробити за інерцією важче — тому їхня діагностична цінність вища за гарну цифру.

Як читати сигнал

Цінність state-canary в тому, що різні поломки маркера означають різне й потребують різних дій.

Що канарка ловить, а що ні

State-canary — інженерний датчик, а не доказ. Межа проста і її важливо тримати в голові:

• Ловить context drift, instruction drift і втрату стану задачі — тобто випадки, коли інструкції з’їхали з ефективного контексту.
• Не ловить factual hallucination: якщо агент упевнено бреше за коректного маркера, джерело — навчальний пріор моделі, а не втрата контексту.
• Не замінює тести, інструменти, перевірку джерел і code review. Це ранній сигнал поверх них, а не замість них.

Коли потрібен не canary, а hook

Якщо правило має не просто відображатися у відповіді, а гарантовано виконуватися в конкретний момент — наприклад, запускати тести перед комітом або забороняти запис у певні файли, — використовуйте hooks чи автоматичні перевірки. Canary показує, що агент пам’ятає обмеження; hook змушує середовище виконати дію незалежно від того, що агент «пам’ятає».

Рівень 3. Протокол відновлення

Маркер зник, змінився сам собою чи показав unknown. Головне, чого я не роблю, — не намагаюся полагодити довгу сесію ще одним довгим промптом: це лише додає токени, не прибираючи деградацію. Замість цього — скидання й відновлення з markdown:

If the state marker disappears, changes unexpectedly, or shows "unknown":
1. Stop the current task.
2. Summarize current state into docs/analysis/<task>.md.
3. Start a fresh session.
4. Re-read AGENTS.md/CLAUDE.md and the task markdown.
5. Continue from the last verified step.

Тому мої активні задачі живуть у docs/analysis/<task-slug>.md: файл слугує і вихідним аналізом, і точкою відновлення. Після /clear агент перечитує його й піднімає нитку за один хід — без переграшу всього листування.

Готовий блок для AGENTS.md / CLAUDE.md

Скопіюйте в кореневий AGENTS.md або CLAUDE.md і підставте свої значення:

## Agent state canary

At the start of every response, print exactly one line:

[state: task=<current-task>; scope=<allowed-area>; constraint=<main-constraint>]

Rules:
- Keep it to one line.
- Use "unknown" if unsure.
- Do not invent missing state.
- If the user changes task, update the task field.

If the marker disappears, changes unexpectedly, or shows "unknown":
1. Stop the current task.
2. Summarize state into docs/analysis/<task>.md.
3. Start a fresh session.
4. Re-read this file and the task markdown.
5. Continue from the last verified step.

FAQ

Чи не зламає маркер відповіді агента?

Ні, якщо це один рядок. Агент друкує його першим, далі відповідає як зазвичай. Ви або не помічаєте рядок, або одразу бачите аномалію.

Чи працює це поза Claude — з Codex або Cursor?

Так, якщо інструмент регулярно підхоплює проєктні інструкції з AGENTS.md, CLAUDE.md чи аналога. Це не system-level гарантія: наприклад, Claude Code сам пише, що CLAUDE.md — не системний промпт, а інструкція, якої модель намагається дотримуватися. Тому canary й потрібна як спостережуваний сигнал, а не як жорсткий захист.

А якщо агент «лінується» і пропускає маркер за цілого контексту?

Буває. Тому одиничний пропуск — привід насторожитися, а не скидати сесію. Сигнал — маркер, що зник на два-три ходи поспіль або став unknown.

Чи потрібна канарка в коротких сесіях?

Ні. На 20–30 ходах у невеликому проєкті деградація малоймовірна. Цінність зростає на довгих багатоетапних задачах.

Як відрізнити втрату контексту від звичайної помилки?

За патерном: агент перестав слідувати одразу кільком правилам, перепитує вирішене, плутає шляхи до файлів. Три-чотири сигнали разом — уже не випадковість.

Джерела та що почитати далі

• agents.md — відкритий стандарт AGENTS.md, «README для агентів».
• OpenAI Codex: AGENTS.md — Codex читає AGENTS.md перед роботою і будує з нього ланцюг інструкцій.
• Claude Code: Memory — поведінка CLAUDE.md і project memory.
• Anthropic: Context windows — деградація recall зі зростанням контексту (context rot).
• Lost in the Middle (Liu et al., 2023) — чому середина довгого контексту відтворюється гірше.
• Google: Helpful, people-first content — чому такий матеріал варто писати з досвіду, а не під пошук.

Схожі статті

• AI-агенти в робочому процесі розробника — базова структура пам’яті агента через AGENTS.md і CLAUDE.md.
• Claude Code субагенти й оптимізація токенів — як ізоляція контексту в субагентах знижує ризик деградації основної сесії.