AGENTS.md та CLAUDE.md: як написати конфіг, який агент справді використовує

Написати хороший конфіг — це найвища віддача при мінімальних зусиллях в агентному кодуванні. Ви налаштовуєте контекст один раз, і кожна сесія виграє: агент перестає вгадувати вашу команду запуску тестів, перестає переформатовувати код під власні стандарти, перестає редагувати директорію, яку ви позначили як недоторкану. Ця сторінка — конкретна практика, що стоїть за AI-Native навичкою «контекст і конфігурація» — однією з 17 AI-native навичок, які ми оцінюємо на різних рівнях. Зберігання довготривалої пам'яті проєкту в CLAUDE.md / AGENTS.md — визначальна ознака розробника рівня 3 (Agentic Developer), тому це варто зробити правильно.

Базова ідея однакова для всіх інструментів, хоча механіка відрізняється: конфіг-файл несе те, що агент не може вивести з коду самостійно. Модель вже знає вашу мову. Вона не знає, що тести потребують конкретного прапорця, що три місяці тому ви перейшли з однієї бібліотеки, або що infra/ — згенерований код і його не можна редагувати вручну. Саме цю прогалину і заповнює файл.

Ландшафт: одна філософія, різні файли

Кожен великий агент читає файл контексту проєкту. Вони поділяють одну філософію, але різняться назвою файлу та механікою завантаження. Ось карта на 2026 рік:

File	Tool(s)	Status
AGENTS.md	OpenAI Codex, Cursor, GitHub Copilot agent, + ~20 інструментів	Відкритий міжінструментний стандарт
CLAUDE.md	Claude Code	Рідний формат Claude Code
GEMINI.md	Gemini CLI	Рідний формат Gemini
.github/copilot-instructions.md	GitHub Copilot	Інструкції для репозиторію Copilot
.cursor/rules (раніше .cursorrules)	Cursor	Формат правил Cursor

Висновок: AGENTS.md — це єдине джерело правди, що формується як стандарт; його вже читають ~20 інструментів. Але є нюанс: Claude Code не читає AGENTS.md нативно — тільки CLAUDE.md. Тому канонічний підхід «одне джерело правди» виглядає так: тримати AGENTS.md як основний файл і зв'язати його з Claude через мінімальний CLAUDE.md, що імпортує його:

@AGENTS.md

<!-- Claude-specific notes can go below -->

Символічне посилання теж працює (ln -s AGENTS.md CLAUDE.md), але на Windows краще використовувати @import — там для символічних посилань потрібні права адміністратора. Так ви підтримуєте один файл, і обидві екосистеми його читають.

Що реально туди писати

Аналіз GitHub понад 2 500 репозиторіїв («How to write a great AGENTS.md») показав, що конфіги, які реально допомагають агентам, мають шість розділів. У порядку пріоритету:

1. Commands — розміщуйте на початку, з точними виконуваними командами та прапорцями (npm test, npm run build, pytest -v), а не просто назвами інструментів. Це розділ з найвищою окупністю: агенти вже знають, що існує pytest; вони не знають потрібних прапорців вашого проєкту. Ставте його вгорі.
2. Testing practices — як ви тестуєте, що запускати перед комітом, вимоги до покриття.
3. Project structure — де що знаходиться, щоб агент не шукав.
4. Code style — покажіть один реальний фрагмент коду, а не три абзаци тексту.
5. Git workflow — назви гілок, угоди про коміти, правила PR.
6. Boundaries — що агент ніколи не повинен чіпати (згенеровані директорії, секрети, вендорний код, міграції).

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

Включати / виключати: тест по кожному рядку

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

Включати	Виключати
Bash-команди, які агент не може вгадати	Будь-що, що можна вивести з коду
Правила стилю коду, що відрізняються від стандартних	Стандартні мовні угоди, які модель вже знає
Інструкції з тестування / обраний тест-ранер	Детальна документація API (краще дайте посилання)
Порядок роботи в репозиторії (гілки, угоди для PR)	Інформація, що часто змінюється
Специфічні для проєкту архітектурні рішення	Довгі пояснення та туторіали
Особливості середовища розробки (необхідні env-змінні)	Пофайловий опис кодової бази
Неочевидні підводні камені	Самоочевидні практики на зразок «пишіть чистий код»

Є один тест, що замінює всю таблицю і перетворюється на звичку:

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

Запускайте цей тест для кожного рядка. «Використовуй TypeScript» — агент і так бачить .ts-файли; вирізати. «Запускай міграції бази даних через npm run db:migrate, ніколи не редагуй migrations/ вручну» — він не міг цього вгадати, а помилка тут руйнує стан; залишити.

Пишіть на правильній висоті

Настанова Anthropic з context engineering зводить якісне авторство до чотирьох принципів.

1. Конкретність / верифікованість. Пишіть правила достатньо конкретно, щоб їх можна було перевірити за виводом агента. Розмиті настанови не можна перевірити — отже, їм не можна слідувати надійно.

• «Відступ 2 пробіли» — не «Форматуй код правильно».
• «Запускай npm test перед комітом» — не «Тестуй свої зміни».
• «HTTP-обробники живуть у src/api/handlers/» — не «Тримай файли організовано».

2. Правильна висота (right altitude). Прагніть до того, що між жорсткою захардкодженою логікою і розмитою порожнечею: «достатньо конкретно, щоб направляти поведінку, але достатньо гнучко, щоб бути сильною евристикою». Занадто жорстко — зламається на першому виключенні; занадто розмито — нічого не направляє.

3. Мінімально, але достатньо. Мінімально не означає коротко. Це означає давати рівно стільки контексту наперед, щоб агент не мав потреби вгадувати або переоткривати — і нічого більше. Вирізайте наповнювач, залишайте несучі деталі.

4. Структура. Використовуйте мічені секції — заголовки Markdown або XML-теги. Файл, що легко сканується, — це файл, який агент (і ваші колеги) реально парсять.

Тримайте його компактним

Справжня причина залишатися компактним — бюджет токенів. Конфіг-файл завантажується повністю в кожній сесії. Він не підтягується на запит; він додається до контексту при запуску. Тому роздутість має прямі, виміряні наслідки: роздутий CLAUDE.md вимірювано знижує дотримання інструкцій. Сам Anthropic формулює прямолінійно — роздуті файли CLAUDE.md змушують Claude ігнорувати ваші реальні інструкції. Кожен зайвий рядок послаблює ваші корисні рядки.

Цільові орієнтири конкретні:

• Anthropic орієнтується на менше ~200 рядків як м'яку ціль для CLAUDE.md.
• Codex встановлює жорстке обмеження в 32 KiB для AGENTS.md (project_doc_max_bytes); файли, що перевищують ліміт, обрізаються, тобто все, що за межею, мовчки не завантажується.

І пастка, про яку варто знати: імпорти не економлять бюджет. Файл, що підключається через @import, все одно завантажується в контекст при запуску — ви розділили файл, але не зменшили його сліду. Щоб реально скоротити те, що завантажується в кожній сесії, виносьте умовно релевантний вміст:

• Path-scoped rules для наскрізних питань, що зачіпають багато файлів — завантажуються тільки коли агент працює в цьому шляху.
• Skills для процедур на вимогу — завантажуються тільки при виклику.
• Посилання для довгого чи детального довідкового матеріалу — вказуйте на нього, а не вставляйте в текст.

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

DESIGN.md: командна угода, а не стандарт

DESIGN.md — це підручниковий приклад «тримай конфіг компактним, виноси деталі за посиланням». Це окремий документ з дизайну/архітектури — ключові рішення, доменна модель, архітектурні патерни, чому це побудовано саме так — який ваш AGENTS.md підключає через @import або посилається на нього, замість того щоб вставляти інлайн. Це тримає завжди завантажуваний конфіг коротким, а глибокий контекст залишається за один крок.

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

Область дії та ієрархія

Обидві екосистеми накладають файли від широкого до специфічного, але по-різному вирішують пріоритет.

CLAUDE.md має чотири рівні, від широкого до специфічного:

1. Managed policy — встановлюється вашою організацією / IT, діє на рівні всієї організації.
2. User — ~/.claude/CLAUDE.md, діє для всіх ваших проєктів.
3. Project — ./CLAUDE.md, зафіксований у git і спільний для команди.
4. Local — ./CLAUDE.local.md, у gitignore, для ваших особистих перевизначень.

У монорепозиторіях файли батьківських директорій завантажуються автоматично, а файли дочірніх — на вимогу. Імпорти використовують синтаксис @path/to/file (відносний або абсолютний), вкладаються до 4 рівнів, а парсер пропускає блоки коду — шлях всередині огородженого блоку не трактується як імпорт.

AGENTS.md вирішується за принципом «ближчий перемагає». Codex обходить від кореня Git вниз до вашої поточної робочої директорії і конкатенує знайдені файли, починаючи з кореня. Оскільки ближчі файли з'являються пізніше, вони перекривають — ближчий файл перемагає. У монорепозиторії ви тримаєте один AGENTS.md на пакет, і той, що ближче до коду, який редагується, має пріоритет. Вище за все: явна інструкція в чаті перекриває будь-який файл.

Міст між двома системами з попереднього розділу пов'язує їх: тримайте AGENTS.md канонічним, додайте CLAUDE.md з командою @AGENTS.md, і ваша ієрархія буде спільною для всіх інструментів без дублювання.

Порадник, а не примусовий механізм

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

Акцентні слова на зразок IMPORTANT та YOU MUST вимірювано покращують дотримання — але не гарантують його. Для вимог, що мають виконуватися кожного разу (запускати форматер, блокувати коміт із невдалими тестами, ніколи не писати в main), детерміністичний запобіжник — це hooks (у Claude Code), а не сильніше формулювання в конфізі.

Практичне правило: використовуйте конфіг для керівних принципів і евристик; беріться за hooks у той момент, коли «агент зазвичай це робить» вже недостатньо і вам потрібно «агент завжди це робить».

Підтримуйте його як код

Конфіг-файл — живий артефакт, а не разове написання. Ставтеся до нього так само, як до решти репозиторію.

• Бутстрапте за допомогою /init. Дайте інструменту згенерувати перший чернетку з вашої кодової бази, а потім доопрацюйте вручну — згенерований варіант є відправною точкою, а не готовим файлом.
• Переглядайте, коли щось іде не так. Кожного разу, коли агент робить щось нерозумне, запитуйте себе: чи спричинив це відсутній або помилковий рядок у конфізі?
• Регулярно обрізайте. Знову запускайте тест по кожному рядку для всього файлу. Рядки, що були необхідними минулого кварталу, можуть тепер бути мертвим вантажем.
• Тестуйте зміни за поведінкою. Не довіряйте, що правка допомогла — спостерігайте, чи справді змінилася поведінка агента. Якщо різниці не видно, рядок, мабуть, не працює.
• Фіксуйте в git. Спільний, версіонований конфіг означає, що вся команда робить внесок і отримує вигоду, а зміни видно на рев'ю.

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

Стартовий AGENTS.md

Ось реальний скелет для копіювання з усіма шістьма розділами високої окупності, заповненими реалістичними плейсхолдерами. Замініть на свої специфічні дані та видаліть усе, що не проходить тест по кожному рядку.

# AGENTS.md

## Commands
- Install: `npm ci`
- Dev server: `npm run dev`
- Test (all): `npm test`
- Test (single file): `npm test -- path/to/file.test.ts`
- Lint + autofix: `npm run lint -- --fix`
- Typecheck: `npm run typecheck`
- Build: `npm run build`

## Testing
- Run `npm test` and `npm run typecheck` before every commit.
- New code needs a test in the matching `*.test.ts` file.
- Integration tests need a running DB: `npm run db:up` first.

## Project structure
- `src/api/handlers/` — HTTP route handlers
- `src/services/` — business logic (no HTTP/DB code here)
- `src/db/` — schema + queries; migrations in `src/db/migrations/`
- `web/` — React frontend (separate AGENTS.md inside)

## Code style
- 2-space indentation, single quotes, no default exports.
- Throw typed errors from `src/errors.ts`, never bare `Error`.
```ts
// Good: typed error, narrow return
export async function getUser(id: string): Promise<User> {
  const user = await db.users.find(id);
  if (!user) throw new NotFoundError('user', id);
  return user;
}

Git workflow

• Branch from main: feature/<short-desc> or fix/<short-desc>.
• Conventional Commits (feat:, fix:, chore:).
• Open a PR; never push directly to main.

Boundaries

• NEVER edit src/db/migrations/ by hand — generate with npm run db:migrate:new.
• NEVER touch dist/, node_modules/, or *.generated.ts (all generated).
• NEVER commit secrets; required env vars are documented in .env.example.

Для єдиного джерела правди між інструментами покладіть поруч однорядковий `CLAUDE.md` з вмістом `@AGENTS.md` і зв'яжіть ваші глибші нотатки з архітектури (`DESIGN.md`, ADR-и) посиланням, а не вставляйте їх.

## Куди рухатися далі

Компактний, конкретний конфіг-файл — одна з конкретних поведінок, що відрізняють AI-assisted розробників від справді AI-native. [Дізнайтеся свій AI-native рівень](/quiz) за три хвилини — він оцінює саме такий рівень майстерності — а коли будете готові налаштувати свій інструментарій, починайте з [рекомендованого стеку ProCoders](/stack).