Боль: почему AI косячит в коде в одних и тех же местах

Те, кто пишет проекты в Cursor, Windsurf или Claude Code, ловят один и тот же ужас: AI выдаёт простыню кода, ты копируешь, запускаешь — сборка падает, тесты красные, зависимости встали не туда. Дело не в «интеллекте» AI — он просто не знает негласных правил твоего проекта.

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

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

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

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

Открытый проект AGENTS.md на GitHub (репозиторий github.com/agentsmd/agents.md, на 2026-08-25 около 24 000 звёзд) решает ровно эту проблему. Идея до безобразия простая: кладёшь в корень проекта Markdown-файл, в котором написано, как AI собирать, тестировать и в каком стиле писать код.

Это не замена README, а дополнение. README — для людей-контрибьюторов, AGENTS.md — для AI-агентов. Обязанности разделены, никто никому не мешает.

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

Путь первый: написать минимальный AGENTS.md руками

Стоит копейки. Создаёшь файл, пишешь три блока — и хватит.

Для ясности: в примерах ниже pnpm (экономит место на диске и умеет monorepo workspace), turbo — это оркестратор задач для monorepo, флаг --filter указывает, что команда работает только с конкретным подпакетом, не трогая весь репозиторий.

Блок первый «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 сам не угадает, но стоит прописать — и он их выполняет.

Блок второй «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 стабильно забивает на тесты

Блок третий «PR instructions»: формат заголовка коммита, обязательный lint и test перед отправкой. Из шаблона: Title format: [<project_name>] <Title> и «Always run pnpm lint and pnpm test before committing».

Все три блока — меньше 50 строк, но процент кода, который AI сдаёт с первого раза, заметно подскакивает (по отзывам комьюнити, точная цифра под вопросом).

Путь второй: вложенный 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 — он имеет приоритет над корневым. Получается, что AI-ассистент фронта и AI-ассистент бэка получают разные инструкции и не путают карты.

Путь третий: превратить AGENTS.md в козырь на фрилансе

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

Тактика: получив заказ, потрать 30 минут на разбор структуры проекта клиента и напиши кастомный AGENTS.md. Этот документ — часть сдачи: клиент потом сам сможет поддерживать код через AI без боли.

Упакуй настройку AGENTS.md как отдельную услугу (ценник подгоняй под местный рынок): базовый пакет — 4 500 ₽ (один файл + README с пояснениями), корпоративный — 25 000 ₽ (вложенный 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 работает только в Cursor, перешёл на Windsurf — всё заново; CLAUDE.md в Claude Code обслуживает только Claude; у GitHub Copilot своя система инструкций. «Написал один раз — работает везде» — вот почему AGENTS.md так быстро подхватили.

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

Призыв к действию: сегодня вечером добавь проекту «инструкцию для машины»

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

Если у тебя monorepo — добавь ещё 20 минут и положи вложенный AGENTS.md в каждый подпакет. Завтра с утра заметишь: AI больше не выдаёт код, который приходится по десять раз править.

AGENTS.md сейчас — самый окупаемый конфиг для AI-кодинга: 30 минут настройки экономят несколько часов дебага каждый месяц.