Чому AGENTS.md та CLAUDE.md робить агента тупим?

Суперечливість у підходах до файлів контексту для AI-агентів: автоматична генерація проти ручного написання

Автор відео розпочинає з трьох фактів, які на перший погляд суперечать один одному. Дослідники зі Швейцарського федерального технологічного інституту (ETH Zürich) протестували автоматично згенеровані файли контексту (Agent MD, Clot MD) на AI-агентах і виявили, що в п'яти з восьми тестів агенти працювали краще без цих файлів, ніж з ними, причому витрати зростали більш ніж на 20%. В інтернеті поширена думка: «видаліть Agent MD, видаліть Clot MD, не запускайте init — менше краще». Водночас Борис Чорний — творець claude code, який, до речі, сам не написав жодного рядка коду з листопада 2025 року — щодня використовує claude.md. Таким чином, постає питання: хто з них помиляється? Автор збирається розібратися в цьому, заглиблюючись в agentic engineering.

Чому дослідження ETH Zürich і практика Бориса Чорного обидві правильні

Після вивчення десятків джерел — відео, статей, подкастів, досліджень — автор робить висновок, що всі вони кажуть приблизно одне й те саме, але дехто не договорює. Типова ситуація: розробник відкриває claude code, запускає init, модель сканує весь репозиторій і видає файл на 400 рядків, де написано, що проект використовує React Router — «дякую, капітане». Це даремна інформація, яку claude і так знайде за 10 секунд. Дослідження ETH Zürich тестували саме такі автоматично згенеровані файли, і вони дали -3% до успішності та +20% до витрат. Однак автор наголошує, що існує друга частина їхнього висновку, яку чомусь ігнорують: файли, написані розробником вручну, дали +4% до успішності виконання задач. Різниця між найкращим і найгіршим підходом становить 7%, що для бенчмарку (реальний баг з GitHub, який агент має виправити) є дуже багато. Дослідження під назвою «Evaluate on Angd» тестувало не лише claude code, а й Codex, Quency-агенти, і результати були однаковими. Отже, проблема більшості матеріалів не в тому, що вони кажуть (автоматично згенерований дамп шкодить), а в тому, що вони не розповідають про рукописний файл — мінімальний, але дуже точний, з конвенціями, яких немає в коді. Саме такий файл використовує засновник claude code.

Як працює Борис Чорний: реальний підхід до claude.md

Автор аналізує публічне інтерв'ю з Борисом Чорним, де той детально описує свій робочий процес. Цікаво не стільки те, що він говорить, скільки те, що з цього випливає. Його claude.md має близько 2500 токенів (100-150 рядків) — це не 400, але й не порожній файл. Три ключові речі, які він робить:

1. Оновлює claude.md після кожної помилки в коді. Він прямо каже: «Апдейтьте ваш claude.md — тоді ви не будете робити помилки знову». Таким чином файл зростає від конкретного болю, а не від чогось уявного.
2. Видаляє весь файл, коли той роздувається, і починає заново. Тобто не claude.md не потрібен, а це гігієна підтримки — він просто генерує його наново.
3. Його claude.md у git, і вся команда оновлює його кілька разів на тиждень. Це живий документ, така ж частина проекту, з якою працюють всі.

Структура claude.md: чотири рівні контексту

Автор пояснює ієрархію файлів claude.md. Коли ви запускаєте claude code, модель отримує весь контекст одразу як один великий текст — вона не читає його по частинах. Існують чотири рівні зверху вниз:

1. Managed (корпоративний) — той, який для вас складає IT-відділ великої компанії. Більшості розробників він недоступний, бо вони не використовують enterprise-підписку.
2. User (персональний) — для всіх проектів одного користувача. Наприклад, «пиши коментарі українською, краще англійською».
3. Project claude.md — у корені репозиторію. Його комітять у git, ділять з командою. Саме тут живе 98% того, що потрібно.
4. Локальне claude.md — ваше особисте. Тут може бути URL до вашого sandbox-сервера або порт, який ви використовуєте. Додайте в .gitignore вручну і використовуйте самостійно.

Автор демонструє свій реальний claude.md з проекту, який складається з фронтенду і бекенду. У файлі на 130 рядків міститься: загальне overview, технічний стек, layout (як поєднані API та web), команди для кожного стеку (огорнуті в make), опис модульної архітектури (гексагональна архітектура на бекенді, слайди на фронтенді), певні URL та секрети для тестування, посилання на документацію, ключові документи та інструкції з композицією. Важливо: якщо один і той самий запис є на двох рівнях (наприклад, user і project), то claude прочитає обидва і може заплутатись, якщо конвенції суперечать одна одній. Тому автор радить тримати все на project-рівні, щоб уникнути дублювання. Документація рекомендує не більше 200 рядків на файл, інакше модель починає ігнорувати частину інструкцій.

Приклад з реального проекту: три ключові блоки

Автор показує свій реальний проект на Go (TeamHub API) і три блоки, де різниця з автогенерованим файлом найочевидніша:

1. Database. У проекті архітектура з database як dumb storage: ніяких дефолтів для бізнес-полів, ролі та статуси — все в коді, ніяких check constraints. Це свідомий підхід, про який claude не знає, тому автор прописує це в claude.md. Бізнес-логіка живе в коді, і якщо частину розмазати по базі даних, то в наступній міграції виникають проблеми. Claude може прочитати цю конвенцію тільки з claude.md.
2. Error handling. У домені використовуються константи через errors.New, формат коду — snack_case, а відповідь завжди вкладена. Це певна конвенція, яку моделі немає звідки взяти, тому вона прописана вручну.
3. Підключення модулів. Кожен модуль реалізує інтерфейс RouteRegister. Сервер приймає список модулів, знає про кожен. Без цього правила claude хардкодить роути прямо в сервер Go — коли модулів 10, сервер знає про кожен замість одного, ламає інший.

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

Що варто класти в claude.md, а що ні

Автор пропонує два стовпчики для прийняття рішень:
Кладемо:

• Команди запуску і тестів.
• Архітектурні рішення, яких немає в коді явно.
• Конвенції команди, яких не видно зі структури файлів.
• Граблі, на які ви вже наступали двічі.

Не класти:

• Форматування — ESLint вже в репозиторії.
• Базовий Go, React, Python тощо — claude знає все це без вас і краще за вас.
• Зміст та дублювання — це просто шум.
• Опис того, що claude знайде сам за хвилину.

Обсяг має бути менше 200 рядків. Якщо шаблон більший після створення нового проекту, видаляйте те, що не стосується двох стовпчиків. Робочий файл має бути приблизно 180 рядків. Правило додавання: claude.md має зростати від вашого болю — додавайте новий пункт, коли claude зробив ту саму помилку вдруге або втретє. Коли нічого не болить, просто не чіпайте. Коли файл розростається, робіть код-рев'ю цього файлу і видаляйте зайве.

Підхід Андрія Карпатого: універсальні правила поведінки для агентів

Автор згадує Андрія Карпатого, колишнього директора AI в Tesla, який у січні 2026 року написав, що за місяць перейшов з 80% ручного коду на 80% агентського. Його головний біль: LLM мовчки роблять припущення, ускладнюють код, не показують трейдофи. Спільнота зібрала його спостереження в claude.md на 60 рядків, який містить чотири правила: «Думай перед кодом», «Простота», «Тільки хірургічні і точні зміни», «Чіткі критерії успіху». Жодного слова про конкретний проект — тільки як себе поводити. Це ідеально підходить для user-рівня, бо це загальні правила для всіх проектів. А проектний файл — це конвенція конкретного репозиторію. Два рівні переслідують одну ціль.

Інтерактивна генерація claude.md замість автоматичного дампа

Автор порушує питання: звідки взяти claude.md, якщо немає шаблону? Дефолтний init — це той самий автоматично згенерований файл, який досліджували ETH Zürich, і він давав -3%. Однак є момент, який часто пропускають: використовуючи команду claude code new --init з параметром 1, а потім запускаючи init, процес стає інтерактивним. Він аналізує директорії і задає питання про тести, архітектуру, формат помилок, які файли налаштовувати, чи потрібні скіли чи хуки. Таким чином, додавши змінну оточення, ви перетворюєте автоматичну генерацію на інтерактивну, де модель враховує ваші відповіді. Після цього файл уже не просто автогенерований дамп — він містить конкретні деталі проекту, які ви вказали.

Інструменти підтримки claude.md: Revise Clot MD, Improover та Memory

Автор наголошує, що claude.md та agent.md — це не «написав і забув». Борис Чорний видаляє і починає заново, коли файл роздувається. Щоб до цього не доходити, існують три інструменти в маркетплейсі:

1. Revise Clot MD. Це команда в плагінах, яку автор постійно використовує під час розробки. Вона аналізує сесію, читає контекст (помилки, виправлення) і вносить до claude.md помітки, щоб більше не наступати на ті самі граблі. Це формула: помилка -> фікс -> записали -> не повторюється.
2. Cloud MD Improover. Аналізує ваш поточний claude.md і видає репорт про якість за шістьма критеріями: команди, архітектура, неочевидні патерни, стислість, актуальність, практичність. Автор демонструє звіт з оцінкою 76/100 і рекомендацією запускати цю команду не рідше ніж раз на два тижні.
3. Memory. Автор закликає не вимикати авто memory. Clot MD — це свідомий контекст, який пишете ви, а AutoMemory — накопичений контекст, який збирає claude. Обидва завантажуються кожної сесії. Memory може містити корисні записи, що виникають під час розробки (наприклад, «інтеграційні тести завжди через реальну БД», «курсорна пагінація»). Їх також потрібно аналізувати, переносити в claude.md і періодично підчищати.

П'ять практичних дій, які можна зробити прямо зараз

Повертаючись до початку, автор підсумовує: ETH Zürich тестував автогенерований файл на 400 рядків, а Борис Чорний і Андрій Карпатий працюють з файлом на 100 рядків, написаним руками — це різні інструменти з однаковою назвою. Тому всі праві. П'ять конкретних дій:

1. Додайте змінну оточення (один рядок) — вона змінює ваш init на інтерактивний.
2. Після кожної помилки claude запускайте команду Revise Clot MD: помилка -> фікс -> записали.
3. Не рідше ніж раз на два тижні запускайте Improover — точкові рекомендації, без необхідності все переписувати з нуля.
4. Тримайте файл менше 200 рядків, видаляйте застаріле. Можна повністю видалити і почати спочатку.
5. Не вимикайте AutoMemory, але слідкуйте за ним: аналізуйте, переносьте в claude.md, підчищайте.

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