ШІ-агенти читають CLAUDE.md, але не завжди виконують інструкції. Український розробник пояснив, як краще писати для них документацію

Відео про це Сулімовський опублікував на YouTube.

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

Сулімовський посилається на дослідження науковців Пекінського університету Zhijun Gao та Jing Chen, опубліковане на arXiv у серпні. Вони проаналізували 557 реальних сесій із coding-агентами та понад 33 000 pull request’ів, створених агентами.

З’ясувалося, що ШІ-агенти дуже часто «зазирають» у CLAUDE.md і схожі файли з інструкціями. Коли їм потрібно було знайти інформацію, до таких файлів вони зверталися у 33% випадків. Тому важливо, що саме там написано. Якщо інструкція застаріла, суперечлива або її можна зрозуміти по-різному, агент може підхопити її й діяти відповідно.

Саме тому Сулімовський радить ставитися до змін у CLAUDE.md майже як до змін у коді. Адже один невдалий рядок може впливати вже на наступні сесії агента.

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

Тож одного рядка «після змін обов’язково запусти тести» може бути недостатньо, щоб бути впевненим, що агент справді це зробить. Тому для критичних вимог Сулімовський радить не обмежуватися текстом. Якщо правило можна перетворити на тест, linter, hook, runnable example або перевірку в CI — краще зробити саме так. Наприклад, замість інструкції «дані мають відповідати цій схемі» можна дати формальну схему та валідатор, який автоматично покаже, чи все справді гаразд.

Також розробник пропонує не дивитися на фразу агента «усе перевірено», а дивитися на логи. Чи запустився тест? Чи був він успішним? Якщо запуск був невдалим— чи виправив агент проблему й запустив його повторно?

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

Тож Сулімовський радить зробити шлях для агента максимально прямим. Наприклад, написати щось на кшталт: «перед зміною API відкрий testing.md, знайди секцію Integration Tests і виконай її». Якщо ж певна інформація потрібна агенту майже в кожній задачі, її можна одразу завантажувати в контекст, а не змушувати модель щоразу самостійно шукати потрібний файл.

Окрема проблема виникає при troubleshooting. Після збоїв читання документації було першою реакцією агента лише приблизно у 5% випадків. Частіше він ішов читати код, повторював попередню дію або одразу намагався щось виправити.

Тому розробник радить винести основні кроки прямо в інструкції для агента: яку команду запустити для діагностики, як безпечно відкотити зміни та що перевірити після цього. Ще краще — оформити це як готову команду або скрипт.

До того ж ШІ-агенти документацію не лише читають, а й доволі активно редагують. Серед понад 33 000 проаналізованих pull request’ів зміни документації були у 41,5%. Серед файлів, які агенти змінювали найчастіше, опинилися AGENTS.md, CLAUDE.md та copilot-instructions.md.

Тож агент може змінити файл із правилами — а в наступній сесії вже отримати власну правку як частину вхідного контексту. Через це Сулімовський радить відділяти тимчасові плани та чернетки агента від постійних правил. А зміни в CLAUDE.md та AGENTS.md — окремо перевіряти, бо вони можуть впливати на те, як агент поводитиметься далі.

Раніше dev.ua писав про інше дослідження файлів CLAUDE.md та AGENTS.md. Тоді дослідники проаналізували близько 532 000 таких файлів і з’ясували, що в них часто трапляються зайві, суперечливі або застарілі інструкції, які можуть погіршувати роботу ШІ-агента. 

/

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