К содержанию
Все статьи

Harness для ИИ-агента: CLAUDE.md, правила и хуки

Что такое harness ИИ-агента и почему от него зависит больше, чем от модели. Как устроены CLAUDE.md, разрешения, хуки, skills и MCP в Claude Code, пример CLAUDE.md для компании и тот же подход в AGENTS.md для OpenCode и Codex.

🧑‍💻Сергей Шульман 9 мин чтения

Claude Code harness — то, о чём редко пишут в обзорах, хотя именно от него зависит, будет ли ИИ-агент полезен в компании. Типичная история: поставили Claude Code, дали сотрудникам, первые дни восторг, через месяц разочарование. Агент каждый раз заново изучает проект, нарушает договорённости, лезет туда, куда не надо, а каждый сотрудник объясняет ему одно и то же своими словами. Модель тут ни при чём. Не хватает окружения: правил, памяти, разрешений и автоматических проверок. Ниже — из чего состоит harness, как собрать его для бизнес-команды, пример CLAUDE.md для компании и как тот же подход работает в OpenCode, Codex и Kimi Code.

Коротко:

  • Harness — всё, что окружает модель: контекст и правила (CLAUDE.md), память, разрешения, хуки, skills, подключения к сервисам (MCP) и субагенты.
  • CLAUDE.md — инструкции, которые агент читает в начале каждой сессии. Но это контекст, а не замок: жёсткие запреты делаются разрешениями и хуками.
  • Хуки — команды, которые срабатывают всегда в заданный момент: после правки файла, перед запуском команды, при остановке агента.
  • Для команды harness хранится в репозитории: все сотрудники получают одинаковые правила и проверки.
  • Тот же подход работает в других агентах: OpenCode и Codex читают AGENTS.md, Kimi Code поддерживает хуки, skills и MCP.

Что такое harness простыми словами

Модель — это двигатель. Harness — всё остальное: руль, тормоза, приборная панель, навигатор с маршрутом. Сильный двигатель без руля и тормозов опасен, а не полезен.

Слово пришло из английского и буквально значит «упряжь». В мире ИИ-агентов так называют программную обвязку вокруг модели. Anthropic сама использует этот термин, когда пишет о том, как команда Claude Code организует работу многих агентов. Сам Claude Code — тоже harness: он даёт модели доступ к файлам, терминалу и инструментам. А вы поверх него настраиваете свой слой под задачи компании.

Из чего он состоит в Claude Code:

СлойЧто делаетГде живёт в Claude CodeАналогия в компании
ИнструкцииКак устроен проект, что принято, что запрещеноCLAUDE.md, .claude/rules/Регламенты и должностная инструкция
ПамятьЧто агент узнал о вас и проектеAuto memoryЗаметки опытного сотрудника
РазрешенияЧто агенту можно делать без спроса, что только с подтверждением, что нельзяpermissions в .claude/settings.jsonДоступы и подписи
ХукиПроверки и действия, которые срабатывают всегдаhooks в .claude/settings.jsonОбязательные процедуры: контроль качества, уведомления
SkillsГотовые сценарии для повторяющихся задач.claude/skills/Чек-листы и инструкции по процессам
MCPДоступ к CRM, базам, таблицам, трекеру.mcp.jsonДоступы к рабочим системам
СубагентыСпециалисты под отдельные задачи.claude/agents/Сотрудники разных ролей

Дальше пройдусь по главным слоям. Skills, MCP и субагентам будут посвящены отдельные статьи.

CLAUDE.md: правила, которые агент читает каждый раз

CLAUDE.md — обычный текстовый файл в формате Markdown. Claude Code загружает его в начале каждой сессии. По официальной документации, файлы бывают нескольких уровней:

УровеньГде лежитДля чего
ОрганизацияСистемная папка, например /etc/claude-code/CLAUDE.md на LinuxОбщие стандарты и требования безопасности для всех сотрудников. Разворачивает IT
Пользователь~/.claude/CLAUDE.mdЛичные предпочтения во всех проектах
Проект./CLAUDE.md или ./.claude/CLAUDE.mdПравила проекта для всей команды, хранятся в git
Локально./CLAUDE.local.mdЛичные настройки в проекте, не попадают в git

Все найденные файлы складываются вместе, а не заменяют друг друга. Первую версию проектного файла создаёт команда /init: Claude изучит проект и запишет команды сборки, тестов и найденные соглашения.

Три правила из документации, которые я соблюдаю у клиентов:

  1. До 200 строк на файл. Длинный CLAUDE.md съедает контекст и хуже соблюдается. Правила для отдельных частей проекта выносятся в .claude/rules/ — их можно привязать к путям, и они подгружаются, только когда агент работает с этими файлами.
  2. Конкретно и без противоречий. Если две инструкции спорят, Claude может выбрать любую.
  3. CLAUDE.md — это контекст, а не принуждение. Агент старается следовать инструкциям, но гарантии нет. Если действие нужно заблокировать в любом случае, для этого есть разрешения и хуки.

Длинный документ можно подключить через импорт @path/to/file — но он всё равно загрузится целиком, контекст это не экономит.

Пример CLAUDE.md для компании

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

# Проект: сайт и внутренние инструменты ООО «Пример»

## Что это
Сайт компании (Astro), админка заявок, скрипты отчётов для отдела продаж.
Владелец решений — коммерческий директор. Изменения в прод — только после его ок.

## Команды
- Запуск локально: `bun run dev`
- Сборка: `bun run build`
- Тесты: `bun test`

## Правила
- Тексты на сайте не переписывать без задачи: это согласованные формулировки.
- Цены не публиковать нигде, кроме страницы /prices.
- Персональные данные клиентов не выводить в логи и отчёты, только ID заявки.
- Новые зависимости — только с объяснением, зачем они нужны.

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

## Где что лежит
- Страницы: src/pages
- Отчёты: scripts/reports (выгрузка из CRM раз в сутки)
- Подробные правила оформления отчётов: @docs/reports-style.md

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

Память: что агент запоминает сам

Кроме CLAUDE.md, у Claude Code есть auto memory — заметки, которые агент ведёт сам: ваши предпочтения, исправления, которые вы ему давали, текущие решения по проекту, ссылки на внешние системы. Они лежат в ~/.claude/projects/<project>/memory/, индекс подгружается в каждую сессию. Включить или выключить можно командой /memory.

Разница простая: CLAUDE.md пишете вы, и это общие правила команды. Auto memory пишет агент, и это его личный опыт работы с вами.

Разрешения: что можно, что нельзя

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

Правила бывают трёх видов: allow (можно без спроса), ask (спросить), deny (нельзя). Пример из документации: агент запускает npm-скрипты и коммиты без вопросов, но не может делать git push:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

Запрет всегда сильнее разрешения. Чтобы агент не читал файл с секретами, добавляют правило вроде Read(./.env) в deny.

Ещё есть режимы работы: ручной (спрашивать при первом использовании каждого инструмента), acceptEdits (принимать правки файлов сами), plan (только изучать и предлагать план) и auto, где перед действиями срабатывает фоновая проверка. Режим bypassPermissions пропускает все вопросы — документация рекомендует его только в изолированных средах вроде контейнеров. Для организаций есть managed settings: правила, которые сотрудник не может переопределить.

Хуки: то, что происходит всегда

Хуки — команды, которые Claude Code запускает в определённые моменты: при старте сессии, перед вызовом инструмента (PreToolUse, может его заблокировать), после успешного вызова (PostToolUse), когда агент ждёт ввода (Notification), когда закончил ответ (Stop) и в других точках.

Пример из документации: после каждой правки файла автоматически запускать форматирование. Это кладётся в .claude/settings.json проекта:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\""
          }
        ]
      }
    ]
  }
}

Ещё полезные сценарии из той же документации: запрет правок защищённых файлов (.env, .git/) — скрипт завершается с кодом 2, и правка блокируется; уведомление на рабочий стол, когда агент ждёт ответа; повторная подгрузка важного контекста после сжатия разговора. Проверить, какие хуки подключены, можно командой /hooks.

Для бизнеса хуки — способ сделать обязательные процедуры обязательными. Не «агент, пожалуйста, запускай тесты», а «тесты запускаются всегда».

Как я собираю harness для команды

Порядок, в котором я настраиваю окружение у клиентов:

  1. Разбор процессов. Какие задачи команда будет отдавать агенту: сайт, отчёты, интеграции, документы. Где деньги, где персональные данные, где риски.
  2. CLAUDE.md проекта и организации. Короткие правила, команды, договорённости, ответственные.
  3. Разрешения. Что агенту можно делать сразу, что с подтверждением, что запрещено. Секреты и прод закрываются в первую очередь.
  4. Хуки. Автоматические проверки, форматирование, защита файлов, уведомления.
  5. Skills под повторяющиеся процессы. Еженедельный отчёт, подготовка КП, публикация статьи — каждый как отдельный сценарий.
  6. Подключение сервисов через MCP. CRM, таблицы, трекер — с минимально нужными правами.
  7. Обучение команды. На её собственных задачах, а не на абстрактных примерах. Цель — чтобы через несколько недель команда сама дописывала правила и skills.

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

Тот же подход в AGENTS.md: OpenCode, Codex, Kimi Code

Harness — не особенность Claude Code. Это подход, и он переносится:

  • AGENTS.md — аналог CLAUDE.md, который читают многие агенты. В OpenCode правила проекта лежат в AGENTS.md в корне, глобальные — в ~/.config/opencode/AGENTS.md, а /init создаёт файл. Если AGENTS.md нет, OpenCode читает CLAUDE.md. Codex CLI тоже поддерживает AGENTS.md и создаёт его через /init.
  • Claude Code читает AGENTS.md, если в проекте нет CLAUDE.md. Можно держать один файл с правилами для всех инструментов.
  • Kimi Code поддерживает MCP, skills, субагентов и хуки.
  • DeepSeek Harness построен по принципу «всё — плагин»: модели, инструменты, skills, сессии.

Поэтому я пишу правила так, чтобы при смене инструмента или модели они переезжали почти без правок. Это страховка от зависимости от одного поставщика.

Доступ из России

Anthropic официально не обслуживает Россию: ни приложения, ни API, ни компании, которые базируются в России. Всё, что описано выше про Claude Code, — для команд с легальным доступом. Для остальных тот же harness собирается на OpenCode, Kimi Code или DeepSeek Harness с моделями, доступными легально, например через российские облака. Подробно — в статье Когда режут VPN: на чём работать с ИИ-агентами в России, а про подключение GLM к агентам — в статье GLM 5.3 для кода.

Частые вопросы

Чем harness отличается от промпта? Промпт — одна задача здесь и сейчас. Harness — постоянное окружение: правила, разрешения, проверки и сценарии, которые действуют в каждой сессии и для каждого сотрудника.

Достаточно ли одного CLAUDE.md? Для старта да. Но CLAUDE.md — это контекст, а не принуждение: то, что нельзя нарушать, закрывается разрешениями и хуками.

Сколько времени занимает настройка harness для команды? Зависит от числа процессов и систем. Базовый слой (правила, разрешения, пара хуков) собирается быстро, дальше он растёт вместе с задачами команды.

Можно ли один набор правил использовать в Claude Code и OpenCode? Да. Claude Code читает AGENTS.md, если нет CLAUDE.md, а OpenCode читает CLAUDE.md, если нет AGENTS.md. Хуки и разрешения настраиваются в каждом инструменте отдельно.

Сколько стоит настройка? Называю после 30-минутного созвона, когда понятны процессы и системы, и фиксирую до старта.


Хотите, чтобы ИИ-агент в вашей компании работал по вашим правилам, а не по настроению? Посмотрите, как я настраиваю Claude Code и альтернативы с harness под команду, или напишите в Telegram, какие процессы хотите отдать агенту.

Похожие статьи: Как установить Claude Code на Windows, Mac и Linux · Что такое Claude Code и чем он отличается от Claude

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

Есть похожая задача?

Разберу её бесплатно за 30 минут и предложу решение. Пишите в Telegram или звоните.