Настройка ИИ-агента под свой проект: чек-лист из 10 шагов

Один и тот же агент в двух репозиториях ведёт себя как два разных инструмента. В первом он с ходу правит нужные файлы, гоняет тесты и заканчивает задачу тремя коммитами. Во втором перечитывает один и тот же модуль по кругу, забывает договорённость «не трогаем миграции» и приносит правки не в тот сервис. Разница не в модели — она одинаковая. Разница в том, насколько агент настроен под конкретный проект.

Эта статья не про то, как создать агента с нуля (об этом на сайте есть отдельный разбор), а про тонкую настройку: как довести уже работающего агента до предсказуемого поведения в вашем репозитории. За основу взят разбор настройки проекта под агента из конспекта двух вебинаров команды Veai с разработчиком агента Михаилом Костицыным (Habr, май 2026) и практика из разбора внутренней архитектуры Claude Code (Habr, март 2026). Ниже — тезисы, которые на практике проверяемы, и десять шагов.

Что значит «настроить агента под проект»

Главный вывод, вокруг которого сходятся оба источника: качество результата агента равно качеству контекста, всё остальное — производные. Каким бы хорошим ни был агент, на плохом контексте он выдаст неправильное решение.

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

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

Чек-лист из 10 шагов

1. Контракт репозитория: AGENTS.md или CLAUDE.md

Файл-конвенций в корне репозитория — входная точка для агента. По спецификации AGENTS.md это «README для агентов»: предсказуемое место, где лежат команды сборки, стек, соглашения и запреты. Формат читают больше двадцати инструментов — Codex, Cursor, Gemini CLI, OpenCode, Zed и другие. Claude Code читает не AGENTS.md, а собственный CLAUDE.md, поэтому канонический файл связывают с ним импортом @AGENTS.md или симлинком (документация Claude Code).

Зачем: у агента появляется один источник правды вместо набора догадок. Пример минимального контракта:

# AGENTS.md
## Команды
- Установка зависимостей: `pnpm install`
- Тесты: `pnpm test`
- Линт и типы: `pnpm lint`
## Стиль кода
- TypeScript strict mode
- Отступы 2 пробела, одинарные кавычки
## Запреты
- Не трогать `migrations/` без явной задачи
- Не коммитить файлы из `dist/`

2. Правила и стиль кода

Правила — это текст, который добавляется к промпту в каждой сессии. В Cursor они живут в .cursor/rules как .mdc-файлы с фронтматтером alwaysApply/globs/description (документация Cursor); в Claude Code — в .claude/rules/ с областями по путям. Писать стоит прежде всего то, что модель угадывает неверно.

Классический кейс из разбора Veai — PowerShell на Windows: большинство моделей училось на bash и zsh, и на PowerShell путается. Один отдельный rule про специфику команд снимает проблему навсегда. Другое частое применение — обход известных багов модели и приоритизация MCP.

3. Skills под повторяемые операции

Скилл — это описание решения одной конкретной задачи: SKILL.md с фронтматтером плюс папки scripts/ и references/. Запускается вручную через /имя-скилла или подхватывается агентом по описанию. Ключевой эффект для контекста: пока скилл не вызван, в окне лежит только его описание — ресурсы и скрипты грузятся по требованию (документация Claude Code).

Практичное правило из разбора Veai — боттом-ап: не писать скиллы заранее на всё, а выносить их из запросов, которые вы повторяете чаще всего. Формат SKILL.md стал кросс-вендорным стандартом Agent Skills и работает в Claude Code, Cursor, Codex и Copilot.

4. MCP-серверы: которых реально нужны

MCP — открытый стандарт подключения агента к внешним данным и инструментам, «USB-C для AI-приложений» (документация MCP). Полезны GitHub MCP, Atlassian (Jira и Confluence), Playwright, Figma. Но подключать их стоит по одному и осознанно.

Причина — цена в токенах. По подсчётам из разбора Claude Code один типичный MCP-сервер содержит 20–30 определений инструментов примерно по 200 токенов, итого 4–6 тысяч токенов. Пять серверов — это уже около 25 тысяч токенов только на описания, то есть почти 12,5% окна до начала работы. Чем меньше серверов, тем больше места для самого кода.

5. Права и песочница

Права решают, что агент делает без спроса. В Claude Code это allow/ask/deny-правила в .claude/settings.json и режимы разрешений (документация по настройкам). Ориентир — давать минимум: команды чтения и запуск тестов без подтверждения, а удаление и сетевые операции — только с явным разрешением. Режим bypassPermissions оставляйте для одноразовых экспериментов в контейнере.

6. Границы контекста

Заранее решите, что агент читает всегда, а что — никогда: большие генерируемые файлы, логи, node_modules, секреты. В разборе Veai для этого используют AgentIgnore — исключения области чтения и редактирования, отдельно для legacy-кода, секретов и TDD-циклов. Документация Claude Code добавляет ориентир по размеру: держите CLAUDE.md короче примерно 200 строк и выносите крупные процедуры в скиллы, иначе файл съедает контекст и правила соблюдаются хуже.

7. Тесты: как агент их гоняет

Агент должен уметь проверить свою работу сам. Пропишите в контракте точные команды сборки и тестов и ожидаемый результат. Из разбора Veai: подход TDD/SDD, когда тесты пишутся (или существуют) до реализации, даёт заметно лучшее качество — и критичен для локальных моделей.

Перед коммитом прогони pnpm test и pnpm lint.
Если падают тесты — исправь причину, а не тест.
Не меняй конфиг тестов без явной просьбы.

8. Критерии готовности задачи

Формулируйте «definition of done» так, чтобы его можно было проверить, а не оценить на глаз. Не «сделай авторизацию аккуратной», а «эндпоинт /login возвращает 401 при неверном пароле, покрыт интеграционным тестом, тип ответа — LoginResult».

9. Ревью диффов и хуки

Правило в markdown — это рекомендация, а не принуждение. То, что должно исполняться железно, выносится в хуки: команды, которые запускаются в определённые моменты жизненного цикла агента. Хук на событие после правки файла запускает форматтер, хук перед коммитом — линтер. Важная деталь из документации по хукам: PreToolUse-хук с решением deny блокирует действие даже в режиме bypassPermissions, то есть политику нельзя обойти сменой режима.

10. Логи и стоимость

Настройка без контроля расхода — это настройка вслепую. Держите под рукой команды вроде /context (что реально занимает окно), /usage (токены по сессиям и моделям) и смотрите, куда утекают деньги. Полное окно — это ещё и медленные ответы, поэтому контроль контекста экономит не только токены.

Таблица: шаг, файл или команда, что даёт

Шаг	Файл или команда	Что даёт
1. Контракт	AGENTS.md / CLAUDE.md	Команды, стек, запреты — в одном месте
2. Правила	.claude/rules/*.md, .cursor/rules/*.mdc	Стиль и обход багов модели по областям
3. Скиллы	skills/<name>/SKILL.md	Повторяемые операции одной командой
4. MCP	.mcp.json	Доступ к Jira, GitHub, браузеру
5. Права	.claude/settings.json	Что агент делает без подтверждения
6. Границы	AgentIgnore, CLAUDE.local.md	Что не читается и не редактируется
7. Тесты	pnpm test в контракте	Агент проверяет работу сам
8. Готовность	текст правил	Проверяемый «definition of done»
9. Ревью	hooks в settings	Формат и линт до коммита
10. Контроль	/context, /usage	Видно расход токенов и места

Пример готового AGENTS.md

# AGENTS.md
## Проект
REST-сервис на Node.js + TypeScript, PostgreSQL, Prisma.
## Команды
- `pnpm install` — зависимости
- `pnpm dev` — локальный сервер
- `pnpm test` — юнит и интеграционные тесты
- `pnpm lint` — ESLint + tsc --noEmit
## Архитектура
- Роуты — в `src/api/`, бизнес-логика — в `src/services/`
- Схема БД — в `prisma/schema.prisma`, миграции не переписывать
## Правила работы
- После правки кода запускай `pnpm lint` и `pnpm test`
- Новый эндпоинт = роут + сервис + тест
- Публичные функции без `any`, ошибки — структурированным объектом
## Запреты
- Не трогать `migrations/` и `.env*`
- Не менять конфиг CI без отдельной задачи

Спецификация советует покрывать такие секции, а для монорепозитория — класть вложенные AGENTS.md в подпакеты: ближайший к редактируемому файлу выигрывает. Именно так устроен основной репозиторий OpenAI — по данным agents.md там 88 вложенных файлов.

Типичные ошибки настройки

• Правила описывают роль, а не задачи. «Ты — тимлид» модель не понимает. «Проверяет циклы в графе зависимостей» — понимает.
• Перегруз контекста. Длинный CLAUDE.md и десяток MCP-серверов оставляют агенту всё меньше окна под сам код. Лечение — путь в обратную сторону от шага 6.
• Копии правил расходятся. Как только одна и та же инструкция описана в двух файлах, копии разъедутся; вопрос только когда. Один источник правды, остальное — симлинк или импорт.
• Ожидание жёсткого исполнения. Markdown-правило читается как контекст, а не как политика. Если правило обязано соблюдаться, это хук, а не файл конвенций.
• Настройка без контроля. Без /usage и /context вы не видите, что половину окна съели инструменты.

Российские реалии

Сам файл-конвенций — это Markdown в git-репозитории. Он работает офлайн и без аккаунта, вопрос только в инструменте, который его читает.

• Claude Code — Россия не входит в список поддерживаемых стран ни для API, ни для claude.ai (список Anthropic), без VPN не запускается; российские карты не принимаются. Про установку и оплату — в гайде по установке Claude Code.
• Cursor и OpenAI (Codex) — сервисы доступны, но оплата картой РФ не проходит: нужен зарубежный банк, UnionPay, крипта или посредник.
• OpenCode — open source, работает без аккаунта и без VPN; практический опыт из РФ описан в посте «Как стать вайбкодером». Установка — в нашем гайде.

Русскоязычных материалов именно про настройку кодинг-агента под репозиторий немного, но они есть: конспект двух вебинаров про контекст, rules, skills и MCP (Habr), «Устав и летопись кодинг-агентов» — про управляющий слой из файлов (Habr) и разбор архитектуры и контекстной инженерии Claude Code (Habr). Про управление сессиями и контекстом — гайд на vc.ru.

Честные ограничения

• Файл конвенций не даёт жёстких гарантий. Содержимое CLAUDE.md попадает в контекст как инструкция, а не как политика; агент может её проигнорировать. Жёстко исполняется только хук.
• Claude Code не читает AGENTS.md. Ему нужен CLAUDE.md — импорт или симлинк. Это неоднородность экосистемы, а не временная ошибка конкретной версии.
• Markdown устаревает молча. Файл-конвенций снижает хаос, но не защищает от того, что инструкция устарела относительно кода. Его нужно проверять как любой другой артефакт.
• MCP-инструменты дорожают контекстом. Каждый подключённый сервер занимает окно фиксированными определениями инструментов, даже если вы им не пользуетесь.
• Правила не заменяют человека в решении. Агент реализует и рутинно проверяет, но «что строить» и архитектурные границы по-прежнему на вас.
• Из РФ часть инструментов — через VPN и обходные схемы оплаты. Технические ограничения контекста никуда не деваются, к ним добавляется доступность сервиса.

Вывод

Настройка агента под проект — это не один файл, а короткий набор решений: контракт репозитория, правила, скиллы, минимум MCP-серверов, права, границы контекста, тесты, критерии готовности, хуки и контроль расхода. Каждый шаг убирает часть работы, которую иначе вы повторяете в каждой сессии.

Начать стоит с малого: один AGENTS.md с командами и запретами, один симлинк CLAUDE.md для Claude Code, одна команда тестов, которую агент гоняет сам. Этого уже достаточно, чтобы поведение стало предсказуемым. Дальше — скиллы на повторяемые операции и хуки там, где правила должны исполняться железно.

Дальше по теме: AGENTS.md — файл-конвенций, что такое MCP, лучшие MCP-серверы, контекст Claude Code, сабэдженты и mentions и как создать своего ИИ-агента.

---

Читайте также: Плагины и skills ИИ-агента: как расширить агента под свою команду · Кейс: анатомия harness engineering: как измерить и ограничить ИИ-агента