Как настроить проект для AI-агентов: CLAUDE.md, skills и rulesync

Кодовые AI-агенты вроде Claude Code, Cursor или Copilot умеют читать файлы, запускать тесты и писать код. Без контекста проекта они тянут не те зависимости, дублируют существующие методы, пишут код не в том стиле. Лечится это инструкциями: от одного файла в корне до полной настройки с навыками и синхронизацией между инструментами.

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

Один файл в корне — уже половина дела

Не пытайтесь описать всё сразу. Создайте файл CLAUDE.md (или .cursorrules, .github/copilot-instructions.md — зависит от инструмента) в корне проекта. Положите туда самое общее:

• Структура проекта: какие директории за что отвечают
• Команды для запуска: тесты, линтер, сборка
• Ключевые правила разработки, например «после изменений прогони тесты»

Пример минимального CLAUDE.md:

## Структура
├── src/           — код сервиса
├── tests/         — тесты
├── migrations/    — alembic миграции
└── scripts/       — утилиты

## Команды
- Тесты: pytest tests/ -x
- Линтер: ruff check . --fix
- Миграции: alembic upgrade head
- Запуск: docker compose up

## Правила
- После изменений кода — запусти тесты
- Стили проверяются ruff, не вноси стилевые правки руками

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

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

Иерархические правила для больших проектов

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

Заведите отдельные файлы инструкций для каждого модуля. В Claude Code это работает через вложенные CLAUDE.md:

my-project/
├── CLAUDE.md                          # общие правила
├── src/
│   ├── auth/
│   │   ├── CLAUDE.md                  # «SSO через OIDC, токены в Redis»
│   │   └── ...
│   ├── billing/
│   │   ├── CLAUDE.md                  # «мутации через описанные контракты»
│   │   └── ...
│   └── notifications/
│       ├── CLAUDE.md                  # «все уведомления через шину событий»
│       └── ...

Когда агент работает с файлами в src/auth/, он автоматически подгружает и корневой CLAUDE.md, и модульный. Правила биллинга при правке авторизации ему не нужны.

Признаки, что проект ещё не до конца настроен:

• Агент долго ищет нужный модуль, не зная куда идти
• Допускает «глупые» ошибки: тянет зависимости не оттуда, регистрирует класс не там
• Дублирует существующую функциональность вместо переиспользования

Каждая такая ошибка — повод дописать правило в нужный модульный файл. Настройка проекта развивается вместе с кодовой базой.

Skills: агент работает с внешним окружением

Помимо кода, в проектах есть логи, метрики, базы данных, CI/CD. Claude Code позволяет научить агента работать с этим через механизм skills (навыков).

Навык — директория с файлом SKILL.md и, по желанию, вспомогательными скриптами. По состоянию на март 2026 года Claude Code поддерживает три уровня навыков:

Пример: навык для поиска по логам:

.claude/skills/
├── logs/
│   ├── SKILL.md              # инструкция: как работать с логами
│   └── search_logs.py        # готовый скрипт поиска
├── metrics/
│   ├── SKILL.md              # инструкция: как запрашивать метрики
│   └── query_grafana.py      # скрипт запроса к Grafana

Содержимое 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"

После этого достаточно написать в чате «найди ошибки в логах за последний час», и агент сам вызовет нужный скрипт. Навыки можно вызывать вручную через /logs.

Параметр allowed-tools определяет, какие инструменты агент может использовать без запроса разрешения, пока навык активен. Можно разрешить Bash только для конкретного навыка, не давая агенту свободный доступ к терминалу в остальное время.

Claude Code также поставляется со встроенными навыками: /batch для массовых изменений с параллельными агентами, /simplify для автоматического код-ревью, /debug для отладки. Полный список — в документации Anthropic.

Rulesync: одни правила для всей команды

Вы настроили проект, всё работает, и тут коллега говорит: «Твой агент бесполезный, ничего не понимает». Оказывается, он работает в Cursor, который не читает CLAUDE.md.

Каждый инструмент хранит инструкции в своём формате:

• Claude Code — CLAUDE.md
• Cursor — .cursor/rules/
• GitHub Copilot — .github/copilot-instructions.md
• Gemini CLI — .gemini/settings.json

Поддерживать всё это вручную нереально. Для этого есть rulesync — open-source CLI, которая генерирует конфигурации для 23+ AI-инструментов из единого источника.

По состоянию на март 2026 года: версия 7.23.0, 935 звёзд на GitHub, MIT-лицензия.

Установка:

npm install -g rulesync
# или
brew install rulesync

Правила хранятся в .rulesync/rules/:

.rulesync/rules/
├── overview.md          # root: true — общие правила
├── auth.md              # globs: ["src/auth/**"] — правила для auth
└── billing.md           # globs: ["src/billing/**"] — правила для billing

Каждый файл — Markdown с YAML-frontmatter:

---
root: false
globs: ["src/auth/**"]
targets: "*"
description: Правила работы с SSO
---

Авторизация через OIDC. Токены хранятся в Redis.
Никогда не создавай собственную реализацию проверки токенов.

Генерация для нужных инструментов:

rulesync generate --targets "claudecode"
rulesync generate --targets "cursor"
rulesync generate --targets "*"   # для всех сразу

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

Помимо правил, rulesync умеет синхронизировать MCP-серверы, commands, subagents и skills между инструментами. Команда с разными редакторами — не проблема.

Фоновые агенты для контроля качества

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

claude -p "Проверь стиль: именование, структура, мёртвый код" \
  --allowedTools "Read,Grep,Glob"

Такой агент работает в режиме только для чтения. Он видит все ваши инструкции, понимает контекст проекта, но ничего не меняет. Можно подключить его к CI/CD и получать отчёт о проблемах на каждый коммит.

Встроенный навык /simplify работает похоже: запускает три параллельных агента для ревью изменённых файлов, собирает результаты и применяет исправления.

С чего начать

Настройка проекта для AI-агентов — процесс постепенный. Минимальный план:

1. Создайте CLAUDE.md в корне с базовой информацией: структура, команды, ключевые правила
2. При каждой ошибке агента дописывайте правило в соответствующий модульный файл
3. Для внешних сервисов (логи, метрики, БД) создайте навыки со скриптами
4. Если в команде разные инструменты — поставьте rulesync и синхронизируйте правила
5. Подключите фоновых агентов для автоматического ревью

Даже первый шаг даёт заметный результат. Как замечает автор оригинальной статьи на Хабре — это тот случай, когда 20% усилий дают 80% результата.

Читайте также:

• AI-агенты: что это, как работают и зачем нужны
• Claude Opus 4.6 и Sonnet 4.6: полный обзор моделей Anthropic
• ChatGPT: полное руководство для русскоязычных пользователей