Біль: чому AI постійно ламає код в одному й тому самому місці

Хто працював у Cursor, Windsurf чи Claude Code над реальним проєктом, знає це відчуття: AI видає цілу простирадлу коду, ти вставляєш — і отримуєш червоний білд, провалені тести, залежності не туди. Проблема не в «інтелекті» моделі, а в тому, що вона не знає ваших негласних правил.

AGENTS.md — це звичайний Markdown-файл у корені проєкту, написаний спеціально для AI: як збирати, як тестувати, який стиль дотримуватись. README.md — для людей: опис проєкту, гайд для контриб’юторів, історія бренду. Коли AI читає README, це схоже на те, як нового співробітника в перший день кидають на стіл корпоративний буклет і одразу просять писати код. Він знає, чим займається компанія, але не знає команду білду, не знає, як запускати тести, не знає правил ESLint. І тоді в чаті починається одне й те саме: «використовуй pnpm, а не npm», «тести в packages/web», «не забудь прогнати lint». Повтори це сто разів — проєкт усе одно крихкий.

На фрилансі збиток ще відчутніший: взяв замовлення на Next.js + Prisma, підключив Cursor для прискорення — а AI ставить залежності через npm install, ламає workspace від pnpm, не знає, де лежить схема бази, і кладе migration у неправильне місце. Клієнт підганяє дедлайн, а ти три години дебажиш код, який сам AI й наробив. Гроші зароблені — нерви знищені.

Три типові сценарії, де AI провалюється через брак правил: ① пакетний менеджер не той (проєкт на pnpm, AI ставить через npm — залежності летять не туди, workspace падає); ② точка входу тестів не знайдена (тести в packages/web, AI запускає pnpm test у коні — отримує «тестів не знайдено»); ③ стиль коду ігнорується (ESLint + Prettier налаштовані, AI плює на відступи й лапки — CI падає).

Можливість: AGENTS.md розділяє «документацію для людей» і «документацію для машин»

Відкритий проєкт AGENTS.md на GitHub (репозиторій github.com/agentsmd/agents.md, станом на 2026-08-25 близько 24 тис. зірок) вирішує саме це. Ідея проста до геніальності: покласти в корінь проєкту Markdown-файл, який каже AI, як збирати, як тестувати, який стиль дотримуватись.

Це не заміна README, а доповнення. README — для людей-контриб’юторів, AGENTS.md — для AI-агентів. Обов’язки чітко розділені, конфліктів немає.

За даними джерела, AGENTS.md уже підхопили десятки тисяч відкритих проєктів (точна цифра потребує перевірки), і його читають VS Code, Cursor, Windsurf, Aider, GitHub Copilot — усі ключові AI-тули для коду (підтверджено перевіркою). За відгуками спільноти, підтримку також додали OpenAI Codex і Google Jules (⚠️ не перевірено). Хто не підключить зараз — той дозволяє AI розмовляти з проєктом на своєму діалекті.

Шлях 1: написати мінімально робочий AGENTS.md вручну

Вкладення мінімальні. Створюєте файл, пишете три блоки — і поїхали.

Перед стартом: приклади нижче на pnpm (економить диск, підтримує monorepo workspace), turbo — це оркестратор задач для monorepo, прапорець --filter обмежує дію одним підпакетом, щоб не смикати весь репозиторій.

Блок 1 «Dev environment tips»: кажете AI, який пакетний менеджер, як стрибати між підпакетами, як створювати нові модулі. З офіційного прикладу:

• pnpm dlx turbo run where <project_name> — одразу переходить у потрібний підпакет, без ls по дереву
• pnpm install --filter <project_name> — ставить залежності тільки для конкретного підпакета, не чіпає весь monorepo
• pnpm create vite@latest <project_name> -- --template react-ts — створює новий підпакет із React + Vite + TypeScript

Цих команд AI сам не вгадає. А варто прописати — і він робить як треба.

Блок 2 «Testing instructions»: як запускати тести, де лежить CI-план, що обов’язково прогнати перед комітом. З офіційного прикладу:

• pnpm turbo run test --filter <project_name> — запускає всі перевірки для конкретного підпакета
• pnpm vitest run -t "<test name>" — ганяє один тест за іменем
• «Fix any test or type errors until the whole suite is green» — не зупиняйся, поки все зелене
• «Add or update tests for the code you change, even if nobody asked» — оце ключова фраза: без неї AI стабільно забиває на тести

Блок 3 «PR instructions»: формат заголовка коміту, обов’язковий lint і test. З офіційного прикладу: Title format: [<project_name>] <Title> плюс «Always run pnpm lint and pnpm test before committing».

Усі три блоки — менше 50 рядків. Але перший-прохідний результат AI-коду зростає помітно (за відгуками спільноти, точна цифра потребує перевірки).

Шлях 2: вкладені AGENTS.md у великому monorepo

Якщо берете корпоративне замовлення з monorepo (кілька пов’язаних проєктів в одному Git-репозиторії: фронтенд, бекенд, спільний код — кожен у своїй підтеці), один AGENTS.md у корені не витягне. Файл підтримує вкладеність: у кожній підтеці лежить свій AGENTS.md, і AI автоматично підхоплює «найближчий».

Як це зробити: кореневий AGENTS.md описує глобальні правила (пакетний менеджер, CI-процес, безпека), а в packages/web/, packages/api/, packages/shared/ лежать свої файли — з командами збірки, точками входу тестів, специфічними залежностями. Наприклад, для фронтенд-пакета: «компоненти на shadcn, стилі на Tailwind, іконки з lucide-react». Для бекенд-пакета: «міграції через Prisma, API-роути в src/routes, авторизація через JWT».

Коли AI працює в підпакеті, він бере найближчий AGENTS.md — він має пріоритет над кореневим. Той самий проєкт дає фронтенд-агенту й бекенд-агенту різні інструкції, і вони не заважають одне одному.

Шлях 3: AGENTS.md як конкурентна перевага на фрилансі

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

Як це робиться: після підписання угоди витрачаєте 30 хвилин на розбір структури проєкту клієнта й пишете кастомний AGENTS.md. Цей файл — частина поставки. Клієнт потім сам використовує його, коли підключає AI для підтримки коду.

Послугу з налаштування AGENTS.md можна виносити окмим рядком у прайсі (орієнтовно, під локальний ринок): базовий пакет — ~€65 (один файл + короткий README-гайд), корпоративний — ~€400 (вкладені AGENTS.md у monorepo + безпекові правила + командний тренінг). Що входить: ① кастомний AGENTS.md ② 30 днів підтримки в месенджері ③ 10-хвилинний відео-розбір. Підходить: клієнт уже має підписку Cursor/Windsurf, але не вичавлює з неї результат. Не підходить: клієнт пише код руками й не збирається впроваджувати AI-тули.

Кейс: AGENTS.md і його захисний рівень сумісності

AGENTS.md поширюється під MIT-ліцензією (підтверджено джерелом), підтримується спільнотою (структура управління потребує уточнення), офіційний сайт — agents.md.

Сумісність — головний захисний рівень: підтверджено, що VS Code, Cursor, Windsurf, Aider і GitHub Copilot читають AGENTS.md; за відгуками спільноти, підтримку також мають OpenAI Codex, Claude Code, Gemini CLI і Google Jules (⚠️ не перевірено). Один файл — і працює з усіма ключовими AI-асистентами. Не треба писати окремі конфіги під кожну тул.

Для порівняння: .cursorrules працює тільки в Cursor, перейшли на Windsurf — конфіг здох; CLAUDE.md обслуговує лише Claude; у GitHub Copilot своя система інструкцій. Принцип «написав один раз — працює скрізь» — головна причина, чому AGENTS.md так швидко підхопили.

Міграція між тулами — нульова. Сьогодні Cursor, завтра Windsurf — AGENTS.md лишається той самий, правила не переписуєте.

Заклик до дії: сьогодні ввечері додайте проєкту «мануал для машини»

Чек-ліст на 5 хвилин: ① відкрийте корінь проєкту ② створіть AGENTS.md ③ скопіюйте офіційний шаблон (github.com/agentsmd/agents.md) ④ пропишіть три команди (білд, тести, lint) ⑤ наступного разу, коли AI писатиме код, — дивіться на результат.

Якщо у вас monorepo — додайте ще 20 хвилин на вкладені файли в кожному підпакеті. Завтра вранці AI видаватиме код, який не треба по десять разів правити в чаті.

AGENTS.md — це найвигідніша інвестиція в AI-розробку зараз: 30 хвилин роботи → кілька годин дебагу щомісяця зекономлені.