Как подготовить проект к работе с AI-агентами: AGENTS.md, правила, спеки

AI-агенты уже пишут заметную часть кода в командах любого размера. Но между «поставили Claude Code» и «агент реально ускоряет разработку» лежит настройка, которую большинство проектов пропускает. Агент без контекста ведёт себя как новый разработчик в первый день: не знает конвенций, изобретает свои паттерны, кладёт файлы не туда и уверенно ломает то, что нельзя трогать.

Подготовка проекта к агентам — не разовая настройка, а живая система: базовый каркас можно поставить за раз, а дальше он растёт и развивается вместе с кодом. Правила уточняются после каждой ошибки, за которую пришлось заплатить временем; карта проекта обновляется, когда меняется архитектура; накапливаются выученные уроки и типовые сценарии. Окупается это каждый день — но именно как процесс, а не как галочка. Вот из чего состоит каркас.

1. AGENTS.md — карта проекта для агента

AGENTS.md — открытый формат инструкций для кодинг-агентов, появившийся в августе 2025 года как совместная инициатива команд OpenAI Codex, Cursor, Factory, Google Jules и других; сегодня его читают десятки инструментов, а Claude Code использует тот же принцип с файлом CLAUDE.md. Идея проста: если README объясняет проект людям, AGENTS.md объясняет его агентам — файл в корне репозитория, который модель читает в начале каждой сессии. Что туда входит:

• Что это за проект — одним абзацем: продукт, стек, архитектура.
• Команды — как запустить тесты, линтер, сборку. Агент, который знает pnpm test, проверяет себя сам; агент без этого знания говорит «должно работать».
• Жёсткие инварианты — то, что нельзя нарушать никогда: «навигация только через <Link>», «каждый обработчик валидирует ввод», «коммиты — Conventional Commits».
• Карта правил — ссылки на детальные документы по темам (архитектура, тесты, безопасность), чтобы агент читал нужное правило в нужный момент, а не всё сразу.

Главный принцип: коротко. Файл на 400 строк агент «читает», но не соблюдает — контекст растворяется. Работает связка «короткая карта + тематические правила по ссылкам».

2. Правила по темам, а не монолит

Один файл на тему: docs/rules/testing.md, docs/rules/architecture.md, docs/rules/security.md. Каждый — до сотни строк, с примерами из вашего же кода («новый server action копирует форму update-name-action.ts»). Ссылка на живой файл-образец работает лучше любого абстрактного описания: агенты отлично копируют паттерны и плохо следуют прозе.

3. Спеки до кода

Агент, которому сказали «сделай оплату», сделает какую-то оплату. Агент, которому дали спеку — что строим, какие сценарии, какие крайние случаи, что считается готовым, — сделает ту, которую вы имели в виду. Шаблон спеки на полстраницы (проблема → скоуп → сценарии → тесты → что не входит) плюс правило «без спеки фича не начинается» меняют качество результата сильнее, чем любой промпт-инжиниринг.

4. Механические ограничители

Всё, что можно проверить автоматически, должно проверяться автоматически — у агентов, как и у людей, дисциплина держится на инструментах:

• Линтер с правилами архитектуры — например, запрет импорта внутренностей чужого модуля мимо его публичного API.
• Хуки — pre-commit с форматированием и линтом; в Claude Code — PreToolUse-хуки, которые физически блокируют запрещённые правки.
• CI-гейты — тесты, типы, линт на каждый push. Агент воспринимает красный CI как задачу, а устное правило — как пожелание.

5. Тесты как язык общения

Требование «фича не готова без теста, и тест обязан уметь падать» — самый дешёвый способ получать от агента работающий код. Агент с тестовой обвязкой итерирует сам: написал → прогнал → починил. Без неё цикл замыкается на вас.

Чек-лист каркаса

1. AGENTS.md / CLAUDE.md в корне: продукт, стек, команды, инварианты.
2. Правила по темам в docs/rules/, каждое со ссылкой на файл-образец.
3. Шаблон спеки + правило «сначала спека, потом код».
4. Линт и хуки, которые блокируют, а не советуют.
5. Тестовый гейт: нет теста — нет фичи.

И один пункт про жизнь после каркаса: заведите привычку после каждой сессии, где агент ошибся, спрашивать «какое правило или строка в AGENTS.md предотвратили бы это» — и дописывать её. Так система инструкций эволюционирует вместе с проектом, вместо того чтобы устареть за квартал.

Базовый каркас можно поставить за один присест — самостоятельно по этому чек-листу или с нашей помощью: мы готовим проекты к работе с AI-агентами под ключ, включая аудит текущего репозитория, и помогаем выстроить процесс их дальнейшего развития. Расскажите о своём проекте — предложим план.