Харнесс для кодящего агента: как устроена обёртка вокруг Claude на реальном проекте

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

Опыт, описанный ниже, накапливался три месяца на реальной многосервисной аналитической платформе: Next.js 16 на фронте, аналитический MCP-сервер на Python с DuckDB, sandbox для изолированного исполнения кода, расчётный солвер с 500+ тестами, фоновой sync-сервис — всё это деплоится через Helm на MicroK8s с отдельными кластерами для прода и стейджинга. Агенту нельзя «примерно» — система настоящая.

Первый слой харнесса — конституция проекта, набор файлов, которые агент читает раньше всего остального. CLAUDE.md содержит не README для людей, а инструкции для модели: как собирать каждый сервис, что нельзя трогать (например, папку components/ui/, которой управляет CLI shadcn), куда класть документы и на каком языке отвечать. Файл устроен слоями: личный кросс-проектный слой в ~/.claude/, под ним проектный, ещё ниже — правила с привязкой к путям. Правила для MCP-кода подхватываются только при работе с MCP-кодом, правила фронта — только на фронте. Рядом лежат PRODUCT.md (продуктовый бриф с явными anti-references), DESIGN.md (палитра в токенах, типографика) и CONTEXT.md — словарь домена с зафиксированными неоднозначностями. Без словаря каждая сессия заново выводит термины из контекста и каждый раз чуть по-своему.

Второй слой — память. Она двухконтурная. Первый контур — трекер задач beads (bd), реализованный не как плоский TODO.md, а как граф зависимостей. На момент описания в графе 106 задач: 55 закрыто, 50 открыто, 48 готовы к работе. Граф знает, что задача B заблокирована задачей A, и умеет восстановить контекст после сжатия диалога командой bd prime. Markdown-списки задач автор запретил сознательно — они дрейфуют между сессиями и конфликтуют с графом. Второй контур — память суб-агентов: у каждой специализированной роли (архитектор, бэкенд, инфра, фуллстек) своя папка с MEMORY.md и отдельными файлами под решения и полученный фидбэк. Агент-бэкенд, однажды получив правку, больше не повторяет ту же ошибку.

Третий слой — документация со строгой структурой. За три месяца накоплено: 162 плана реализации в docs/plans/, 157 дизайн-спек в docs/specs/, 48 отчётов и аудитов в docs/reports/, 15 архитектурных решений (ADR) в docs/adr/. ADR пишутся в immutable-формате MADR через специальный скил: сканирование кода, сократический опрос, черновик, ревью. Решение, принятое в апреле, не теряется в чате — это отдельный файл, на который ссылается архитектурный обзор. Вся папка одновременно открыта как Obsidian-vault: разработчик ходит по проекту через граф ссылок, агент — по тем же файлам через свои инструменты.

Отдельного внимания заслуживает история с инструментами, которые не прижились. claude-mem — инструмент с более чем 80 тысячами звёзд на GitHub — был подключён как слой памяти, но за две недели база разрослась до 700 МБ почти бесполезной выжимки, а застарелый баг съел пять ядер CPU. Инструмент пришлось снести. Это иллюстрирует общий принцип: звёзды репозитория и его пригодность в конкретном проекте — разные вещи. Из подключённых MCP-серверов половина за 98 зафиксированных сессий не вызвалась ни разу — при том что реальных сессий было больше из-за ротации логов в Claude Code.

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