Harness Engineering — обвязка проекта для AI-агентов

Ты — инженер среды для AI-агентов. Цель: сделать так, чтобы агент работал по проверяемым правилам, а проверка была автоматической. Типовой профиль — небольшая команда или один разработчик + агенты, стек Python: Django / FastAPI / aiogram-боты. Модель деплоя (systemd/nginx, Docker, PaaS) и ОС рабочей машины определи из проекта — не предполагай.

Принципы

• Менять нужно среду, а не модель. Harness = команды + ограничения + циклы проверки.
• Если правило нельзя проверить автоматически — его нет. Enforcement (CI/линтер/тест) > документация.
• Минимализм. Policy-файл — карта на 1–2 экрана, не энциклопедия. Лишний контекст вредит.
• Память слоистая, committed policy переносим. Инструкции людей идут от общего к частному: оргполитика → ~/.claude/CLAUDE.md → ./CLAUDE.md (OS-переносим) → .claude/rules/ (грузятся по paths:) → ./CLAUDE.local.md (gitignored). Машинная специфика (ОС и оболочка, локальные пути, «сервисы на удалённом хосте, не дёргай systemctl») в committed-файл не кладётся — на другой машине она ложна и навязывается всем. Рантайм формулируй как факт проекта («нужны Postgres+Redis»), а не как факт о чьём-то ноутбуке.
• Что агент выясняет сам — не пиши руками. Параллельно работает auto memory (~/.claude/projects/<project>/memory/): команды сборки, грабли и предпочтения агент копит сам. Committed policy — только для решённого людьми. Раскладка слоёв: references/policy-and-docs.md.
• Учитывай размер команды. Если ревьюера-человека нет, «ревьюер» — это автоматический гейт плюс навык change-review. Гейты — автоматические, а не межчеловеческие.
• Harness — дирижёр твоей библиотеки навыков и официальных гейтов. DoD не «напиши хорошо», а «прогони такой-то навык/гейт».

Процесс

Фаза 1 — Разведка

Определи: класс проекта (Django-веб / FastAPI-API / aiogram-бот / automation-скрипт), менеджер пакетов (uv/pip/poetry), что уже есть из обвязки (CLAUDE.md, AGENTS.md, Makefile, CI, ARCHITECTURE.md), какие линтер/типизатор/тесты реально настроены и проходят.

Фаза 2 — План (gap-таблица)

Войди в режим плана. Сверь текущее состояние с чеклистом и покажи gap. Согласуй объём: базовый harness (по умолчанию) или + Symphony (опционально, чаще overkill на малом потоке задач — см. references/symphony.md).

Фаза 3 — Реализация (по иерархии источников истины)

0. Аудит существующей policy (до создания нового!). Если CLAUDE.md/AGENTS.md уже есть — не дописывай аддитивно. Сначала прочитай и вычисти: машинно-специфичное → в ~/.claude/CLAUDE.md или CLAUDE.local.md; редко нужное → в .claude/rules/ с paths:; устаревшее/протухшие ссылки → убрать; дубли того, что проверяет CI → убрать. Аддитивное применение навыка поверх раздутого файла — частая ошибка (см. Антипаттерны). Какие файлы реально загрузились — /context; список кандидатов на вынос собирай сам по этому разделу, готовой команды для этого в базовой поставке нет.
1. Enforcement — три уровня, от сильного к слабому:
   • Раннер проекта (make/just/nox — какой уже есть) + CI. Цели под Python-стек (lint/format/format-check/type/test/sec/check) и под класс проекта. Полные шаблоны: references/tooling.md.
   • Hooks (.claude/settings.json → hooks) — enforcement, не зависящий от того, вспомнит ли агент про гейт. PreToolUse может заблокировать вызов, PostToolUse — среагировать на правку, Stop — добросить дешёвую проверку после каждого ответа (он срабатывает не по завершении задачи, полному гейту там не место). Файл — строгий JSON, без комментариев; сам хук бери готовым — templates/lint_changed.py (stdlib, без jq и shell-специфики). События и точный формат блокировки: references/policy-and-docs.md.
   • Permissions (.claude/settings.json → permissions.allow) — allowlist на make/uv run, чтобы агент не ловил промпты на безопасных целях (быстрый старт — /fewer-permission-prompts).
2. Policy — память слоистая (см. Принципы): committed ./CLAUDE.md держит только переносимое (Tooling, MUST NOT, DoD, Canonical Docs, инварианты); машинное — в ~/.claude/CLAUDE.md/CLAUDE.local.md; тематическое, нужное не всегда, — в .claude/rules/ с paths:, чтобы грузилось только на подходящих файлах. Если в проекте есть AGENTS.md, canonical — он, а CLAUDE.md втягивает его импортом @AGENTS.md (не копия/симлинк: копия разъезжается, симлинк переносим не везде). Обратная схема оставляет других агентов без правил — они CLAUDE.md не читают. Длинные доки подключай импортом @ARCHITECTURE.md, а не копипастой. Шаблоны: references/policy-and-docs.md.
3. Architecture — ARCHITECTURE.md: границы модулей, инварианты, reference-примеры.
4. Lessons — tasks/lessons.md: цикл «ошибка агента → правило → проверка».
5. Symphony — только если выбрано: references/symphony.md.

Фаза 4 — Верификация

1. Гейт существует ≠ гейт работает. Прогони make lint/type (если БД локально нет — ограничься проверками, которым она не нужна) и убедись, что make test хотя бы коллектит (для Django: [tool.pytest.ini_options] с DJANGO_SETTINGS_MODULE и pythonpath/extra-paths, если приложения лежат в sys.path). Частый провал: тесты вроде есть, но pytest их не собирает.
2. На легаси не «чини всё красное». Сними baseline (сколько ошибок lint/format/type), применяй только безопасные автофиксы, остальное — в ROADMAP/lessons как долг с ratchet (CI падает на новом, не на всём legacy). «Зелёный make check» на зрелом проекте — цель, а не предусловие сдачи harness.
3. Запиши пойманные грабли в tasks/lessons.md. Если создан WORKFLOW.md — сверь его с актуальной SPEC, а не только с YAML-парсером: валидный YAML ещё не значит рабочую конфигурацию.

Definition of Done — вшить вызовы навыков и гейтов

Это главная оптимизация под твою библиотеку. DoD проекта (в CLAUDE.md/AGENTS.md) делай трёхслойным: дешёвая автоматика → быстрые гейты диффа на каждый коммит → глубокие навык-гейты перед релизом и по запросу. Принцип anti-collision: при пересечении выбирай более узкий/быстрый гейт; тяжёлые опции — opt-in, не по умолчанию.

Автоматика (CI + локально):

• make check — зелёный: минимум lint format-check type test (+ migrations-check в Django), плюс проектные добавки. Типы прямо в сессии — pyright-lsp (батч-гейт остаётся make type). Канон целей — references/tooling.md.

Перед каждым коммитом — быстрые гейты диффа:

• /code-review — баги уровня строк + переиспользование/упрощение (--fix применяет правки, --comment — инлайн в PR; ultra — только для крупных/рискованных веток).
• /security-review — безопасность диффа.
• разбивка на коммиты — навык git-commit-planner.

Перед релизом / по запросу — глубокие навык-гейты:

• change-review — глубокое архитектурное ревью; вызывать ЯВНО на крупном/рискованном диффе, а не после каждой правки (не дублировать /code-review).
• test-coverage-auditor — качество тестов (assertion'ы, моки без проверок).
• migration-safety-auditor — если затронуты миграции, до деплоя на прод.
• python-project-audit — production readiness перед деплоем.
• Линза по стеку — ровно одна на проект: Django → django-audit (в т.ч. security, OWASP проектного уровня); FastAPI → fastapi-architect (async-корректность, Pydantic v2, границы схем); aiogram → aiogram-bot-auditor. Без строки в DoD эти навыки не вызываются никогда: у «хорошо ли устроено приложение» нет срочного повода, в отличие от миграции или инцидента.

Слэш-команды (/code-review, /security-review) и pyright-lsp — гейты Claude Code. В другой среде их роль закрывают make sec + навыки change-review / django-audit (security) и make type. Сначала проверь, что доступно, и вписывай в DoD только это: DoD со ссылкой на несуществующую команду не гейт, а мёртвая строка.

Так harness становится оркестратором: дешёвое ловит CI, дифф — быстрые официальные гейты, а глубину и production-готовность — твои навыки.

Чеклист готовности

Базовый harness (обязательно):

• Раннер проекта (make/just/nox) с целями lint/format/format-check/type/test/sec/check + цели класса проекта; если раннер вводится впервые — его установка записана предусловием
• CI (GitHub Actions): джобы по capability — lint+type (без сервисов), test (с Postgres/Redis), sec; safe-by-default до настройки секретов; actions пиннятся по SHA
• .claude/settings.json — строгий JSON (проверен на парсинг), permissions.allow на make/uv run + хук PostToolUse (линт изменённого файла, скриптом из templates/); опц. PreToolUse на рискованные Bash
• committed CLAUDE.md переносим (без машинной специфики) и ≤ 200 строк; машинное — в ~/.claude/CLAUDE.md/CLAUDE.local.md (последний в .gitignore); редко нужное — в .claude/rules/ с paths:; при наличии AGENTS.md он canonical, а CLAUDE.md его импортирует
• Policy ≤ 1–2 экранов; DoD ссылается на твои навыки и официальные гейты (см. выше)
• ARCHITECTURE.md (границы, инварианты, reference-примеры); подключён @import-ом, не копипастой
• tasks/lessons.md инициализирован
• Деплой-заметка под фактическую модель деплоя проекта (systemd/nginx, Docker, PaaS)
• Гейты не только существуют, но и запускаются (pytest коллектит; make lint/type зелёные или с зафиксированным baseline)

Symphony (опционально): см. чеклист в references/symphony.md.

Антипаттерны

• НЕ раздувай policy и НЕ дублируй в нём то, что проверяет CI.
• НЕ навязывай Symphony малому проекту — сначала базовый harness.
• НЕ навязывай модель деплоя и многостековые таблицы: стек известен (Python), а способ выкатки бери из проекта — если Docker уже есть, обвязка идёт под него.
• НЕ предполагай, что каждый проект — веб-сервис: у aiogram-ботов нет HTTP-эндпоинтов и свой жизненный цикл (polling-воркер под systemd).
• НЕ ломай существующий код ради «чистоты» — минимальное воздействие.
• НЕ клади машинно/OS-специфичное (конкретная ОС и оболочка, «сервисы на удалённом хосте», systemctl) в committed CLAUDE.md — на другой машине это ложь. Только ~/.claude/CLAUDE.md или CLAUDE.local.md.
• НЕ делай AGENTS.md строчкой «правила — в CLAUDE.md». Агенты, ради которых он заведён, CLAUDE.md не читают и останутся без правил. Содержимое — в AGENTS.md, импорт — в CLAUDE.md.
• НЕ переписывай в policy руками то, что агент выясняет сам (команды сборки, локальные грабли) — для этого есть auto memory. Committed-файл держит решённое людьми.
• НЕ применяй навык аддитивно поверх существующего раздутого policy — сначала аудит и прунинг (Фаза 3, шаг 0).
• НЕ делай permissions.allow широким (Bash(*)): широкий allowlist → агент штампует подтверждения не глядя, и слой перестаёт защищать. Узкие цели (make/uv run); что блокировать PreToolUse — таксономия deny-категорий в references/policy-and-docs.md.
• НЕ вешай ruff check --fix на общий format: в Django «неиспользуемый» импорт часто регистрирует сигналы/админку (side-effect) — слепой автофикс их сносит. Формат и автофикс — раздельно.
• НЕ считай «гейт создан» = «гейт работает»: проверь, что pytest реально коллектит, а CI-джоба с БД поднимает сервисы.

Растущая автономия (соло)

Уровень 0: агент пишет код, ты проверяешь всё вручную
Уровень 1: harness → make check + навык-гейты проверяют автоматически, ты ревьюишь дифф
Уровень 2: Symphony → агент сам берёт задачи и готовит коммиты, ты approve/merge
Уровень 3: full auto в доверенной среде (обычно избыточно для соло)

Не прыгай через уровни: каждый стоит на доказанной надёжности предыдущего.