Перестаньте тюнить промпты. Постройте harness для coding-агента

Anthropic выпустил статью How Claude Code Works in Large Codebases. Главный тезис: в реальной кодовой базе модель — меньшая переменная. Слой контекста и инструментов, который вы выстраиваете вокруг агента, значит больше, чем версия Sonnet или Opus. Engin Diri из Pulumi разбирает эту идею на практическом уровне — не теория, а готовая схема внедрения.

Как Claude Code ориентируется без индекса

Claude Code работает с живой кодовой базой — не требует индекса, который нужно строить и поддерживать. Агент навигирует так же, как инженер: grep, find, ls, чтение файлов, переход по ссылкам. Плюс очевиден: нет отдельного индекса для синхронизации.

Минус тоже очевиден: инженер, впервые попавший в репозиторий с одними лишь shell-инструментами, утонет. Ваш агент в первый день — это он и есть. Всё, о чём дальше, — про то, как дать ему карту.

AI-слой из семи компонентов

Раньше в кодовой базе было два слоя: код и тесты. Теперь есть третий — AI-слой, или harness. Anthropic выделяет семь компонентов:

1. CLAUDE.md — фундамент, читается в начале каждой сессии и остаётся в контексте.
2. Хуки (hooks) — самоулучшение harness, срабатывают на события сессии.
3. Навыки (skills) — progressive disclosure: workflow подгружается только когда агент работает в нужной директории.
4. Плагины — дистрибуция навыков и хуков внутри организации.
5. LSP — навигация на уровне символов вместо строкового поиска.
6. MCP-серверы — расширение инструментов агента.
7. Субагенты — разделение исследования и редактирования.

Компактный и слоёный CLAUDE.md

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

Правильный подход: в корне — только то, что применимо везде. Что это за проект, стек, команды (make test, make lint, как запустить dev-сервер), общие конвенции. Локальные конвенции — в CLAUDE.md внутри поддиректорий (services/api/CLAUDE.md). Claude Code идёт вверх от рабочей директории и загружает все CLAUDE.md по пути, так что корневой контекст не теряется, а промежуточные слои накладываются в правильном порядке.

Два быстрых улучшения: make test и make lint в поддиректориях должны запускать только текущий срез, а не весь репозиторий. И exclusion rules в .claude/settings.json должны исключать dist/, сгенерированные SDK и vendor-код — каждый пропущенный файл экономит токены на осмысленной работе.

Хуки для самоулучшения harness

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

SessionStart-хук срабатывает до того, как агент начал работу. Скрипт печатает в stdout текущую ветку, незакоммиченный diff, последние коммиты — агент получает ориентацию бесплатно, без лишнего хода.

Stop-хук срабатывает в конце хода. В этот момент diff ещё маленький, контекст свежий. Запустите headless-сессию Claude, передайте ей diff и CLAUDE.md, попросите предложить обновления и запишите результат в review-файл. Ключевой трюк — вызов LLM в фоновом режиме, чтобы конец каждого хода не блокировался на рефлексию:

if os.environ.get("REFLECT_LOCK"):
    sys.exit(0)
subprocess.Popen(
    ["uv", "run", "python", ".claude/hooks/reflect_claude_md.py"],
    cwd=root, env={**os.environ, "REFLECT_LOCK": "1"},
    stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
)

Навыки с привязкой к пути

CLAUDE.md — это конвенции («каждый роут регистрируется здесь»). Skills — это workflow («вот как добавить новый роут от начала до конца»). Разделение держит в тонусе: правила в CLAUDE.md, рецепты в навыках.

Главная недооценённая возможность — привязка навыка к директории. Навык create-api-endpoint загружается только когда агент редактирует файлы в services/api/. С десятками навыков в реальном проекте scoping — это разница между полезной библиотекой и стеной нерелевантных промптов. Ментальная модель: progressive disclosure для экспертизы.

Символьный поиск через LSP и MCP

grep — нормально, пока строк в проекте не стало шестизначное число. Строковой поиск возвращает слишком много, жжёт токены на чтение ненужных файлов и теряет то, что IDE делала десятилетиями: jump-to-definition, find-references, hover-for-types.

Решение: локальный language server, обёрнутый в MCP-сервер, с двумя-тремя инструментами: where_is, find_references, goto_definition. Агент ищет по символам, а не по строкам. Запрос «найди все использования monthly_total_cents» возвращает одно определение и реальные референсы, а не пятьдесят grep-совпадений в комментариях.

Субагенты для исследования

Правило: разделяйте исследование и редактирование. Субагент работает в своём контекстном окне. Вы спрашиваете, какие файлы реализуют billing webhook, или как выглядит user model в разных сервисах. Он копает, а в основную сессию возвращается только резюме.

Выигрыш — бюджет контекста, а не параллелизм. Исследование по природе расточительно: агент читает 40 файлов, чтобы найти 3 нужных, и 37 из них выбрасываются. Если это происходит в основной сессии, редактирование начинается с наполовину заполненным контекстом. В субагенте шум остаётся там. Ограничение tools до read-only — ключевая строка конфигурации:

---
name: explorer
tools: Read, Grep, Glob
model: sonnet
---

Не дайте harness протухнуть

Harness — не разовая настройка. Модели улучшаются, и правила, написанные под прошлогоднюю модель, часто ограничивают текущую. Правило «всегда разбивай рефакторинг на однофайловые изменения» могло спасать в 2024 и блокировать полезный кросс-файловый рефакторинг в 2026. Anthropic советует пересматривать CLAUDE.md каждые 3-6 месяцев или при стагнации производительности после крупного релиза модели.

Назначьте владельца

Команды, получающие отдачу от Claude Code в масштабе, имеют ответственного за harness. Небольшая platform-engineering команда, или один DRI, или гибрид PM/инженер на полставки. Задача та же, что и владение CI-пайплайном: писать конвенции, строить навыки, запускать LSP-обёртку, версионировать хуки, продвигать работающее, выводить из обращения устаревшее.

Паттерн, который проваливается: завезти Claude Code в организацию в пятницу, надеяться на вирусное принятие, наблюдать как каждая команда полгода растит свою версию CLAUDE.md. Паттерн, который работает: тихий период обкатки, небольшой набор одобренных навыков, пара работающих плагинов, задокументированная governance-модель, затем широкий доступ. Относитесь к harness как к инфраструктуре.

С чего начать

Порядок, проверенный автором на практике:

1. Урезать корневой CLAUDE.md до одного экрана. Остальное — в поддиректории.
2. Добавить Stop-хук, предлагающий обновления CLAUDE.md в headless-режиме.
3. Превратить три самых частых повторяющихся задачи в path-scoped навыки.
4. Запустить language server за MCP-сервером. Перестать искать строки.
5. Освоить отправку исследования в субагенты.

Большинство команд застрянет на первом шаге на неделю и заметит, что агент уже ощутимо умнее. Остальное накапливается.