CLAUDE.md і AGENTS.md:який агент читає який файл.

Що це за файли

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

• CLAUDE.md стосується лише Claude Code. Він може лежати в корені проєкту (./CLAUDE.md або ./.claude/CLAUDE.md), у ~/.claude/CLAUDE.md для всіх ваших проєктів і в підпапках. Файл CLAUDE.local.md зберігає особисті нотатки для одного проєкту.
• AGENTS.md — відкритий формат, описаний на agents.md, README для агентів. Його читають Codex, Cursor, агент-програміст GitHub Copilot, Gemini CLI, Zed та багато інших. У монорепозиторії AGENTS.md у підпапці діє для цієї частини, і перемагає найближчий файл.

Вміст по суті той самий. Різниться те, який інструмент підхоплює файл.

Що Claude Code робить з AGENTS.md

Документація Claude Code описує три випадки, для версії 2.1.277 і новіше:

• Лише AGENTS.md у проєкті, CLAUDE.md немає: Claude Code читає AGENTS.md.
• Обидва файли в проєкті: Claude Code читає лише файли CLAUDE.md.
• CLAUDE.md, що імпортує AGENTS.md через @AGENTS.md: Claude читає CLAUDE.md разом з AGENTS.md.

Саме другий випадок дивує людей. Якщо додати CLAUDE.md, навіть крихітний, у репозиторій, де вже є AGENTS.md, Claude перестає читати AGENTS.md, доки CLAUDE.md його не імпортує. Те саме стосується CLAUDE.local.md. Старі версії Claude Code читали лише CLAUDE.md, тому імпорт і досі надійний вибір. У документації також описано налаштування Project instructions у /config, щоб Claude читав обидва файли разом.

Один набір інструкцій

Оберіть один файл як джерело істини. Задокументовано два способи:

1. Імпортувати AGENTS.md з CLAUDE.md

   Створіть CLAUDE.md поруч з AGENTS.md, першим рядком якого буде @AGENTS.md, а нижче додайте інструкції лише для Claude. Імпорти використовують синтаксис @path, відносні шляхи відраховуються від файлу, де вони записані, а імпортовані файли можуть імпортувати інші до чотирьох рівнів вкладеності.

2. Зробити CLAUDE.md символічним посиланням на AGENTS.md

   Виконайте ln -s AGENTS.md CLAUDE.md, якщо вам нічого додати спеціально для Claude. Документація попереджає, що інструменти правки Claude не пишуть через символічне посилання, а у Windows закомічене посилання може вивантажитися як однорядковий текстовий файл, тому для спільного репозиторію імпорт надійніший.

Не використовуйте третій підхід: CLAUDE.md, у якому словами написано «прочитай AGENTS.md». Claude побачить файл, лише якщо вирішить його відкрити, а імпорт завантажує його щоразу.

Спільний AGENTS.md

Покладіть в AGENTS.md те, що потрібно будь-якому агентові:

# AGENTS.md

## Commands
- Install: `npm ci`
- Test: `npm test`
- Lint: `npm run lint`

## Conventions
- TypeScript, strict mode. No default exports.
- Update the tests with every change.

## Do not
- Edit files under `generated/`.
- Commit without running the tests.

Пишіть коротко й конкретно. У документації Claude Code радять вкладатися приблизно у 200 рядків на один CLAUDE.md, бо довгі файли коштують контексту й виконуються менш надійно.

Часті помилки

• Два файли розходяться. Одну копію оновили, іншу ні. Використовуйте імпорт.
• Додали CLAUDE.md і втратили AGENTS.md. Див. вище: імпортуйте його.
• Секрети в будь-якому з файлів. Їх комітять, і вони завантажуються в кожну сесію.
• Розпливчасті правила. «Пиши чистий код» нічого не дає. «Запусти npm test, перш ніж казати, що закінчив» дає.
• Суперечливі правила у файлі батьківської папки й файлі підпапки.

Читання й рев'ю цих файлів

Обидва — звичайний Markdown, тому DotMD відкриває CLAUDE.md і AGENTS.md як будь-який .md-файл, зі змістом та історією кожної зміни, і показує, що в них змінив агент. Читання безкоштовне. Див. також Claude Code і Codex з DotMD.

Питання про CLAUDE.md і AGENTS.md

Інші запитання