Настройка проекта для AI-агентов
Недавно Anthropic опубликовали статью про harness design для долгоживущих агентов. Решил собрать свой опыт и рассказать, как настроить проект так, чтобы агент понимал как работать в нём, как делиться скилами между проектами, как сделать настройку для любого популярного кодового агента, не меняя десятки файлов.
Всё показываю на примере Claude Code, но принципы работают с любыми агентами — поменяются только названия файлов и директорий.
С чего начать настройку?
Первое, что стоит осознать, это эволюционный процесс, в который мы постепенно вносим новые правила, убираем устаревшие вместе с развитием проекта.
Итак, начинайте с простого — создайте один файл в корне проекта с правилами для вашего агента. Не надо сразу пытаться в него записать всё подряд, положите в него максимально общую информацию, структуру проекта, команды для запуска, правила разработки, например что после изменений нужно поправить тесты. Никогда не стоит записывать в правила реализации каких-то конкретных вещей, код сам по себе является отличной документацией, которую агент поймёт, главное, чтобы он её мог найти.
## Структура
├── src/ — код сервиса
├── tests/ — тесты
├── migrations/ — alembic миграции
└── notebooks/ — adhoc скрипты
## Команды
- Тесты: `pytest tests/ -x`
- Линтер: `ruff check . --fix`
- Миграции: `alembic upgrade head`
- Запуск: `docker compose up`
Также, если у вас есть какие-то стандарты написания кода, которые можно проверить скриптами, лучше делать это через них, а не отдавать на откуп нейронке.
Отлично, уже на этом этапе мы сняли с себя часть рутины. Не объясняем каждый раз как запускать тесты, архитектуру проекта, как проверить, что мы ничего не сломали и другие повторяющиеся вещи.
Но продолжая работать с агентом, мы неизбежно начнём натыкаться на проблемы, то он начнёт делать свою реализацию уже готового метода, то напишет класс не в том месте и множество других мелких проблем. Но допускает он эти ошибки не потому, что ваш агент тупой и не может сделать элементарные вещи, а потому что ты не дал ему достаточно контекста и он просто не знает, что где-то уже есть готовая реализация или как у вас принято разграничивать логику.
Как с этим бороться? Начать систематично при любой ошибке агента дописывать правила. Очень желательно, особенно если проект большой, понимать к какому модулю относится ошибка, а не писать всё в корневую инструкцию, заводя для каждого отдельного куска программы свою инструкцию.
something-cool/
├── CLAUDE.md # общие правила
├── src/
│ ├── auth/
│ │ ├── CLAUDE.md # "правила работы с SSO"
│ │ └── ...
│ ├── billing/
│ │ ├── CLAUDE.md # "мутации состояния только через описанные контракты"
│ │ └── ...
Яркими признаками, что вы ещё не до конца настроили проект, являются:
-
Агент делает поиск нужного модуля, не зная куда пойти.
-
Агент допускает казалось бы глупые ошибки — тянет зависимости не оттуда, регистрирует класс не там и т.д.
Работа с окружением
Итак, агент делает множество задач без нареканий, сам понимает где и как писать логику, знает что после правки кода надо поправить тесты, доки и что угодно ещё. Но наши программы сейчас это далеко не только код, это также логи, мониторинг, аналитика и много чего ещё, что живёт вне нашего кода. Как заставить агента работать с окружением?
Для решения таких задач есть два подхода — это skills и MCP, я буду рассматривать на примере skills, так как они мне нравятся больше.
Создаём отдельные скиллы для работы с внешними сервисами — описываем за что отвечает сервис и какие функции доступны, также стоит помочь агенту и стандартные действия вынести в готовые скрипты, чтобы ему каждый раз не приходилось выдумывать, как сделать какое-то базовое действие.
something-cool/
├── CLAUDE.md
├── .claude/
│ └── skills/
│ ├── logs/
│ │ ├── SKILL.md # инструкция: как работать с логами
│ │ └── search_logs.py # готовый скрипт поиска
│ ├── metrics/
│ │ ├── SKILL.md # инструкция: как смотреть метрики
│ │ └── query_grafana.py # скрипт запроса к Grafana
│ ├── database/
│ │ ├── SKILL.md # инструкция: как ходить в БД
Пример skills/logs/SKILL.md:
---
name: logs
description: Поиск и анализ логов приложения
allowed-tools: Bash, Read
---
Для поиска логов используй скрипт:
python .claude/skills/logs/search_logs.py --query "error" --since "1h"
python .claude/skills/logs/search_logs.py --trace-id "abc123"
Отлично, теперь наш агент может не только следить за кодом, но и собирать для нас аналитику, помогать найти проблему по логам и много чего ещё!
Вспоминаем, что мы работаем не в одиночку
Работая со skills/mcp довольно быстро приходишь к мысли: у меня несколько репозиториев с одним и тем же окружением, хочется как-то делиться ими между репозиториями и коллегами, которые используют те же самые инструменты (а ещё помогает скептикам поверить, что агенты работают, так как понижает порог, убирая необходимость разбираться в скилах и описывать правила, позволяя сразу попробовать что-то сделать через агента)!
И для этой задачи есть как публичные решения по типу claudemarketplaces.com, так и решения, которые вы можете развернуть в контуре neuraldeep
Проблема с разными кодовыми агентами в команде
Во время разработки такой обёртки проекта может случиться ситуация, что вы вроде как настроили проект под агента и всё работает просто замечательно, но тут к нам приходит коллега и говорит: всё фигня, агент путается и вообще не следует инструкциям. В ходе короткого разбирательства быстро понимаете, что коллега использует отличного от вас агента, который не читает по умолчанию ваши инструкции и просто игнорирует ваши CLAUDE.md.
Неприятная ситуация, но к счастью есть решение rulesync — CLI которая берёт правила и генерирует из них файлы для 25+ агентов: Claude Code, Cursor, Windsurf, Copilot, Gemini, Cline и т.д.
Правила живут в .rulesync/rules/
.rulesync/rules/
├── overview.md # root: true — общие правила проекта
├── auth.md # globs: ["src/auth/**"] — правила для auth
└── billing.md # globs: ["src/billing/**"] — правила для billing
Каждый файл — markdown с frontmatter:
---
root: false
globs: ["src/auth/**"]
targets: "*"
description: Правила работы с SSO
---
Правила
Теперь можно сгенерировать файлы для конкретного нашего агента, и rulesync сам разложит инструкции в нужные директории с правильными названиями.
Пример для нескольких популярных кодовых агентов
rulesync generate --targets "claudecode"
rulesync generate --targets "cursor"
rulesync generate --targets "copilot"
После генерации в репе появляется:
something-cool/
├── .rulesync/rules/ # единый источник правды
├── CLAUDE.md # сгенерирован (корневой)
├── src/auth/CLAUDE.md # сгенерирован (модульный)
├── .cursorrules # сгенерирован
├── .github/
│ └── copilot-instructions.md # сгенерирован
└── ...
Таким образом получаем единое место для редактирования правил, которое подойдёт для большинства агентов.
Фоновые агенты
Есть довольно много задач, связанных с оценкой кода. Если у нас уже есть хорошо описанный проект, почему бы нам не приложить ещё капельку усилий и не добавить фоновых агентов, которые будут подсвечивать проблемы? В зависимости от выбранного агента, создание может несколько отличаться, но в самом простом варианте это будет выглядеть примерно так
claude -p "Проверь стиль: именование, структура, мёртвый код"
--allowedTools "Read,Grep,Glob+<тулы, чтобы вернуть результат проверки>"
Итог
Делать хорошую настройку проекта для агента — это весьма долгая задача, но при этом даже простенькие правила дают ощутимый прирост в скорости и качестве работы агента, наверное это тот случай где 20% усилий дают 80% результата =)
Автор: Gerbylev