Шпаргалка

Шпаргалка харнес агента: компоненты, файлы, проблемы и чек-лист запуска

Обновлено: 12.10.2026 · Skillaria.Top

Харнес агента состоит из пяти подсистем: инструкции, инструменты, среда, состояние и обратная связь. Минимальный набор файлов — AGENTS.md как короткий роутер, скрипт проверки (make check, verify.sh), файл прогресса и список фич со статусами; статус готовности ставит скрипт, а не агент.

Пять подсистем харнеса

Подсистема	Что это	Артефакты	Симптом поломки
Инструкции	Что агент должен знать о проекте	AGENTS.md / CLAUDE.md, skills, docs/, ADR	Нарушает известные конвенции
Инструменты	Что агент может сделать	shell, тесты, линтер, браузер, MCP-серверы	«Хочет, но не может»
Среда	Где агент работает	lock-файлы, Docker/devcontainer, git worktree, песочница, init.sh	Сессия начинается с починки окружения
Состояние	Что переживает перезапуск	PROGRESS.md, DECISIONS.md, feature_list.json, коммиты	Новая сессия не знает, где остановились
Обратная связь	Как агент узнаёт об ошибке	make check, E2E, хуки, arch-check, оценщик	«Готово», а не работает

Порядок внедрения с нуля: обратная связь → инструкции → состояние → среда → инструменты.

Файлы харнеса

Файл	Назначение	Правило
AGENTS.md / CLAUDE.md	Входная точка: что за проект, как запустить, как проверить	Короткий роутер (порядка 80 строк), ссылки на доки с условием «когда читать»
docs/*.md	Подробности по темам	Читаются по требованию, не целиком
.claude/skills/*/SKILL.md	Повторяемые процедуры (деплой, ревью)	Подгружаются, когда задача совпала с описанием
PROGRESS.md	Состояние, сделано, блокеры, следующие шаги	Обновлять в конце каждой сессии
DECISIONS.md	Решение, причина, отвергнутые варианты	Записывать путь, а не только вывод
feature_list.json	Фичи: behavior, verification, state	Ровно одна фича active (WIP=1)
scripts/verify.sh	Проверка фичи и перевод в passing	Единственный, кто ставит passing, с SHA коммита
scripts/arch-check.sh	Архитектурные границы	Код выхода 1 + WHY и FIX в выводе
scripts/init.sh	Проверка окружения перед работой	Окружение, чистый git, зелёный make check, активная фича
sprint contract	Контракт на фичу до кода	В скоупе / вне скоупа / открытые вопросы
.claude/settings.json	Разрешения и хуки Claude Code	Проверки на событиях, а не в памяти агента

Скелет AGENTS.md

# Проект: платёжный бэкенд (FastAPI, PostgreSQL)

## Запуск
docker compose up -d && ./scripts/init.sh

## Проверка
make check   # линт, типы, юнит, arch-check
make e2e     # сквозные сценарии

## Definition of Done
- make check и make e2e — код 0
- фича переведена в passing скриптом scripts/verify.sh
- PROGRESS.md обновлён

## MUST
- запросы к БД только через репозитории
- секреты только из переменных окружения

## Документы
- docs/payments.md — когда задача касается оплаты и возвратов
- docs/migrations.md — когда меняется схема БД

Состояния фичи

Состояние	Значение	Кто переводит
pending	В очереди	Планировщик
active	В работе (только одна)	Агент при старте
passing	Проверка пройдена	Только verify.sh
blocked	Нужно решение человека	Агент с описанием причины

Уровни верификации

Уровень	Что	Когда
1	Линт, типы	Всегда
2	Юнит- и интеграционные тесты	Всегда
3	E2E	Изменение больше одного слоя; перед «готово»
4	arch-check	Новые межслойные импорты

Право на «готово» — только после верхнего уровня. Зелёные юниты — не готовность.

Механизация правил

Уровень	Инструмент	Цена
grep-гвард	Скрипт с поиском паттерна и сообщением WHY/FIX	Минуты
Правило линтера	import-linter (Python), dependency-cruiser, eslint-plugin-boundaries (JS/TS)	Час
Архитектурный тест	Тест в CI, падающий при нарушении слоёв	Больше, но видно в make check

#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WHY: сервисы не обращаются к БД напрямую"
  echo "FIX: используйте репозиторий из app/repositories/"
  fail=1
fi
exit $fail

Типичные проблемы и решения

Проблема	Подсистема	Решение
Правило в CLAUDE.md не соблюдается	Инструкции	Сократить файл, правило превратить в проверку или хук
Агент не может запустить тесты	Инструменты	Разрешить команду, установить зависимости в образ
Разное поведение на разных машинах	Среда	lock-файлы, Docker/devcontainer, фиксированные версии рантайма
Амнезия между сессиями	Состояние	PROGRESS.md, session handoff, чтение в начале сессии
Три фичи начаты, ни одна не закончена	Состояние	WIP=1 в feature_list.json
«Готово», а не работает	Обратная связь	DoD, E2E, verify.sh, независимый оценщик
Тесты зелёные, фича сломана	Обратная связь	E2E с реальной базой и конфигурацией
Агент копирует плохие паттерны	Обратная связь	arch-check с первого дня
Непонятно, что агент сделал	Состояние	Мелкие коммиты, отчёт в PROGRESS.md, DECISIONS.md
Агент сломал окружение за ночь	Среда	Песочница, git worktree, чекпоинты, откат через init.sh
Один и тот же комментарий на ревью дважды	Харнес в целом	Превратить в проверку в make check, убрать текст из инструкций

Роли для долгих задач

Роль	Делает	Не делает
Планировщик	Фичи с критериями приёмки	Не пишет код
Генератор	Реализует одну фичу, гоняет тесты	Не решает, готово ли
Оценщик	Вердикт по рубрике со ссылками на файл, строку, лог	Не видит рассуждений генератора
Мердж	Коммит при review == pass	Это код, а не агент

Бюджет автономной работы

Цель — одно предложение (например, довести все фичи до passing).
WIP=1, лимит времени и попыток на фичу.
Метрика растёт монотонно, регрессия — немедленный откат.
Миграции, инфраструктура, деньги — эскалация человеку.
После нескольких неудачных ревью — начать фичу с чистого контекста.

Чек-лист запуска агента

Есть AGENTS.md: стек, запуск, команда проверки, DoD.
make check проходит на чистом клоне.
Окружение воспроизводимо: lock-файлы, Docker или devcontainer.
Агенту доступны нужные команды, опасные — запрещены или в песочнице.
Есть E2E хотя бы на главный сценарий.
Есть PROGRESS.md и правило читать его в начале сессии.
Фичи в списке со статусами, активна одна.
Статус passing ставит скрипт.
Сообщения проверок содержат WHY и FIX.
Задача сформулирована с критериями приёмки и границами скоупа.
Определено, что требует решения человека.
Посчитан verification gap до изменений, чтобы было с чем сравнить.

Метрики харнеса

Метрика	Как считать
Verification gap	Доля «готово» без подтверждения проверкой на 10 задачах
MTTR	Время от поломки до восстановления рабочего состояния
Холодный старт	Отвечает ли новая сессия на вопросы «где мы, что дальше» без догадок
Абляция	Просадка при отключении одной подсистемы на фиксированном наборе задач

Коротко

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

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

Чем AGENTS.md отличается от CLAUDE.md?

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

Сколько строк должно быть в AGENTS.md?

Жёсткого лимита нет, но входной файл стоит держать коротким — порядка сотни строк, как оглавление. Детали выносятся в отдельные документы.

Нужен ли feature_list.json для маленького проекта?

Для разовых правок нет. Он окупается, когда агент работает над несколькими фичами подряд или в нескольких сессиях.

Где хранить секреты, к которым нужен доступ агенту?

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

Разберите тему на видео

Эта тема подробно разобрана с практикой в курсе «Harness Engineering: инженерия надёжности AI-агентов».

Перейти к курсу