Недавно Anthropic опубликовали статью о design harness для долгоживущих агентов. В этой статье я собрал свой опыт, как настроить проект так, чтобы AI-агент эффективно в нём работал, мог делиться скиллами между проектами и следовал правилам без необходимости менять десятки файлов вручную.

Примеры приведены на основе Claude Code, но описанные принципы применимы к любым кодовым агентам — потребуется лишь адаптировать названия файлов и директорий.

С чего начать настройку?

Настройка проекта — это эволюционный процесс. Правила постепенно дополняются и уточняются по мере развития проекта и выявления ошибок агента.

Начните с простого: создайте один файл в корне проекта с базовыми инструкциями для агента. В него включите:

• структуру проекта,
• команды для запуска и тестирования,
• основные правила разработки — например, что после изменений нужно обновлять тесты.

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

Если у вас есть стандарты кода, проверяемые линтерами или скриптами, полагайтесь на них, а не на инструкции для агента. Это снизит нагрузку на модель и уменьшит ошибки.

Уже на этом этапе вы избавляетесь от рутины: не нужно каждый раз объяснять архитектуру, команды запуска или процесс проверки изменений.

Как устранять ошибки агента?

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

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

Признаки того, что настройка ещё не завершена:

• агент не знает, где искать нужный модуль;
• допускает «глупые» ошибки — подключает зависимости не оттуда, регистрирует классы в неподходящих местах.

Работа с окружением

Современные приложения — это не только код. Есть логи, мониторинг, аналитика и другие внешние системы. Как научить агента с ними взаимодействовать?

Два основных подхода — skills и MCP. Рассмотрим skills, как более удобный.

Создайте отдельные скиллы для внешних сервисов. В каждом укажите:

• назначение сервиса,
• доступные функции,
• готовые скрипты для стандартных действий — чтобы агент не изобретал велосипед каждый раз.

Например, skills/logs/SKILL.md может описывать, как искать ошибки в логах, какие поля доступны, как фильтровать записи.

Теперь агент может не только писать код, но и анализировать логи, собирать аналитику, находить проблемы.

Обмен скиллами между проектами и командами

Часто несколько репозиториев используют одинаковое окружение. Хочется делиться скиллами между ними и коллегами, особенно если они используют те же инструменты.

Это упрощает настройку для новых участников и помогает скептикам — они могут сразу попробовать агента, не тратя время на ручную настройку.

Для этого существуют:

• публичные решения, например claudemarketplaces.com;
• внутренние решения, которые можно развернуть в своём контуре, например в neuraldeep.

Работа с разными агентами в команде

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

Решение — rulesync, CLI-инструмент, который конвертирует единые правила в форматы для 25+ агентов: Claude Code, Cursor, Windsurf, Copilot, Gemini, Cline и другие.

Правила хранятся в .rulesync/rules/. Каждый файл — markdown с frontmatter, описывающим, для каких агентов и в каких контекстах он применяется.

После генерации rulesync автоматически создаёт и раскладывает инструкции по нужным директориям с правильными именами файлов.

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

Фоновые агенты для анализа кода

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

• запуск агента на новых коммитах или MR,
• анализ изменений на соответствие правилам,
• создание комментариев или предупреждений.

Настройка проекта под AI-агентов — долгий процесс, но даже базовые правила дают значительный прирост в скорости и качестве работы. Это классический случай, когда 20% усилий дают 80% результата.

Недавно Anthropic опубликовали статью проharness design для долгоживущих агентов. Решил собрать свой опыт и рассказать, как настроить проект так, чтобы агент понимал как работать в нём, как делиться скилами между проектами, как сделать настройку для любого популярного кодового агента, не меняя десятки файлов.

Всё показываю на примере Claude Code, но принципы работают с любыми агентами — поменяются только названия файлов и директорий.

С чего начать настройку?

Первое, что стоит осознать, это эволюционный процесс, в который мы постепенно вносим новые правила, убираем устаревшие вместе с развитием проекта.

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

Также, если у вас есть какие-то стандарты написания кода, которые можно проверить скриптами, лучше делать это через них, а не отдавать на откуп нейронке.

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

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

Как с этим бороться? Начать систематично при любой ошибке агента дописывать правила. Очень желательно, особенно если проект большой, понимать к какому модулю относится ошибка, а не писать всё в корневую инструкцию, заводя для каждого отдельного куска программы свою инструкцию.

Яркими признаками, что вы ещё не до конца настроили проект, являются:

1. Агент делает поиск нужного модуля, не зная куда пойти.
2. Агент допускает казалось бы глупые ошибки — тянет зависимости не оттуда, регистрирует класс не там и т.д.

Работа с окружением

Итак, агент делает множество задач без нареканий, сам понимает где и как писать логику, знает что после правки кода надо поправить тесты, доки и что угодно ещё. Но наши программы сейчас это далеко не только код, это также логи, мониторинг, аналитика и много чего ещё, что живёт вне нашего кода. Как заставить агента работать с окружением?

Для решения таких задач есть два подхода — это skills и MCP, я буду рассматривать на примере skills, так как они мне нравятся больше.

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

Примерskills/logs/SKILL.md:

Отлично, теперь наш агент может не только следить за кодом, но и собирать для нас аналитику, помогать найти проблему по логам и много чего ещё!

Вспоминаем, что мы работаем не в одиночку

Работая со skills/mcp довольно быстро приходишь к мысли: у меня несколько репозиториев с одним и тем же окружением, хочется как-то делиться ими между репозиториями и коллегами, которые используют те же самые инструменты (а ещё помогает скептикам поверить, что агенты работают, так как понижает порог, убирая необходимость разбираться в скилах и описывать правила, позволяя сразу попробовать что-то сделать через агента)!

И для этой задачи есть как публичные решения по типу claudemarketplaces.com, так и решения, которые вы можете развернуть в контуреneuraldeep

Проблема с разными кодовыми агентами в команде

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

Неприятная ситуация, но к счастью есть решениеrulesync— CLI которая берёт правила и генерирует из них файлы для 25+ агентов: Claude Code, Cursor, Windsurf, Copilot, Gemini, Cline и т.д.

Правила живут в .rulesync/rules/

Каждый файл — markdown с frontmatter:

Теперь можно сгенерировать файлы для конкретного нашего агента, и rulesync сам разложит инструкции в нужные директории с правильными названиями.

Пример для нескольких популярных кодовых агентов

После генерации в репе появляется:

Таким образом получаем единое место для редактирования правил, которое подойдёт для большинства агентов.

Фоновые агенты

Есть довольно много задач, связанных с оценкой кода. Если у нас уже есть хорошо описанный проект, почему бы нам не приложить ещё капельку усилий и не добавить фоновых агентов, которые будут подсвечивать проблемы? В зависимости от выбранного агента, создание может несколько отличаться, но в самом простом варианте это будет выглядеть примерно так

Делать хорошую настройку проекта для агента — это весьма долгая задача, но при этом даже простенькие правила дают ощутимый прирост в скорости и качестве работы агента, наверное это тот случай где 20% усилий дают 80% результата =)

Мой тг канал “Вектор, вектор, человечек”