Модуль 5 · Оценка и управление · урок 23 из 24
Внедрение harness engineering: дорожная карта
За курс набралось два десятка практик: AGENTS.md как оглавление, docs/ как система записи, инварианты в линтерах, стенд на каждый worktree, evals, фоновая уборка, оркестрация. Внедрить всё сразу невозможно и не нужно. Этот урок собирает практики в последовательность для агентства, где одновременно живут десятки клиентских проектов на разном стеке: с чего начать завтра, что сделать за месяц и к чему прийти за квартал.
Исходные принципы
Один пилотный проект. Выберите репозиторий, где агент уже работает каждый день и где есть хотя бы базовые тесты. На сайте на OctoberCMS с e2e на Playwright начинать проще, чем на легаси без единого теста. Биргитта Бёкелер (Thoughtworks) называет это harnessability: строгие типы, явные границы модулей и фреймворк с жёсткими соглашениями облегчают построение обвязки, а в легаси обвязка нужнее всего там, где её труднее всего построить.
Провал — это задача для harness. С первого дня правило одно: если агент ошибся повторно, команда спрашивает не «кто недоглядел», а «какой направляющей или датчика не хватило». Это главное культурное изменение, остальное — инструменты.
Не копировать OpenAI один к одному. Авторы статьи о harness engineering сами оговариваются: поведение их агентов сильно зависит от структуры и инструментов конкретного репозитория и не переносится на другие проекты без сопоставимых вложений. Их 3,5 PR на инженера в день — результат greenfield-проекта, который строили под агентов с первого коммита, а не ориентир для команды. Минимум блокирующих merge-гейтов и необязательное ревью людьми авторы сами называют безответственными в среде с низкой пропускной способностью. Для клиентского продакшена такие решения нужно отдельно обосновывать.
Завтра: первая неделя
Цель — чтобы агент в пилотном проекте мог проверить себя сам, а команда начала копить сигналы.
- AGENTS.md как карта. Команды сборки, тестов и линта, структура репозитория, запреты, определение «готово» и ссылки на docs/. Коротко, без энциклопедии — подробности в уроке об AGENTS.md как оглавлении.
- Агент запускает проверки сам. Убедитесь, что
phpunit, линтер и хотя бы один e2e-сценарий запускаются из песочницы одной командой и выдают понятный вывод. Это первая петля обратной связи — см. урок о петлях обратной связи. - Журнал провалов. Файл в docs/ или метка в трекере: задача, что агент сделал не так, что исправил человек. Из этого журнала через месяц вырастет eval-набор.
- Права по умолчанию. Никаких полных прав «для скорости», пока процесс не понятен, — это один из антипаттернов в рекомендациях Codex.
Через месяц
Цель — направляющие и датчики, которые работают без участия конкретного человека.
- docs/ как система записи и планы исполнения. Архитектурные решения, договорённости из чатов и созвонов, планы крупных задач — в репозитории, версионируемо. См. уроки о системе записи и о планах исполнения.
- Первые инварианты в коде. Один-два кастомных линтера или структурных теста на правила, которые чаще всего всплывают в журнале провалов. Сообщение об ошибке — инструкция по исправлению. Подробно — в уроке об инвариантах.
- Изолированный стенд на задачу. Свой экземпляр приложения на каждый worktree, чтобы параллельные задачи не мешали друг другу, а агент мог сам открыть страницу в браузере. См. уроки об окружениях и о наблюдаемости.
- Первые 20 задач eval-набора из журнала провалов и прогон baseline — по схеме из урока о своих evals.
- Автоматическое ревью MR как дополнительный датчик, не замена человеку — см. урок о ревью-боте.
Признак, что этап пройден: новичок в команде, человек или агент, может поставить задачу в пилотном проекте и получить проверенный результат, не спрашивая устно «а как тут принято».
Через квартал
Цель — harness становится переиспользуемым продуктом агентства, а не набором файлов в одном репозитории.
- Шаблоны harness. Бёкелер предлагает harness templates для типовых топологий. Для агентства это шаблон под OctoberCMS-сайт, под мобильное приложение, под интеграционный сервис: AGENTS.md, каркас docs/, линтеры, CI, стартовый eval-набор. Новый проект стартует с обвязки, а не доходит до неё через полгода.
- Регресс при каждой смене модели и версии Codex. Прогон evals до и после — обязательный шаг, а не повод для споров в чате.
- Самоулучшающаяся петля. Еженедельный разбор правок ревьюеров с группировкой и исправлением harness агентом — см. урок о самоулучшающемся harness.
- Фоновая уборка. Задачи по расписанию, которые ищут отклонения от «золотых принципов» и открывают мелкие MR, — урок об энтропии.
- Оркестрация для чётких задач. Для потока однотипных, хорошо специфицированных задач — связка трекера и агентов по образцу Symphony, разобранная в уроке об оркестрации. Неоднозначная работа остаётся интерактивной.
Сводная таблица
| Этап | Главный артефакт | Признак готовности |
|---|---|---|
| Неделя | AGENTS.md-карта, журнал провалов | Агент сам запускает тесты и линтер в пилотном проекте |
| Месяц | docs/, 1–2 инварианта в линтерах, стенд на worktree, 20 eval-задач | Задача ставится и проверяется без устных пояснений |
| Квартал | Шаблоны harness, регресс-прогон, петля улучшения | Новый проект стартует с обвязки; смена модели проходит через evals |
Кто за что отвечает
- Владелец harness — один человек или маленькая платформенная группа: шаблоны, общие линтеры, eval-инфраструктура. Без владельца обвязка расползается так же, как код без архитектора. Как это выглядит в масштабе компании, разобрано в уроке о внутренней платформе агентов.
- Тимлид — журнал провалов, еженедельный разбор, решение, что переносить в правило. См. курс для тимлидов.
- QA — оракулы для evals и проверка поведения: тестировщики лучше всех знают, что значит «работает».
- Разработчики — пишут в журнал провалов и не чинят повторяющиеся ошибки агента молча.
Что смотреть по дороге
Цифр-ориентиров здесь нет намеренно: они зависят от проекта. Важнее не обмануться. Отчёт DORA 2025 фиксирует положительную связь внедрения AI с пропускной способностью и отрицательную — со стабильностью поставки. METR в обновлении исследования отмечает, что самооценки ускорения ненадёжны. Поэтому рядом со скоростью держите стабильность:
- доля агентских MR, принятых без существенной переделки;
- время от открытия MR до мержа и нагрузка на ревьюеров;
- дефекты, найденные после релиза в задачах с участием агента;
- pass rate регрессионного eval-набора по версиям harness;
- сколько правил добавлено и сколько удалено — обвязка, которая только растёт, стареет.
Подробнее о метриках для команды — в уроке о метриках.
Типичные ошибки внедрения
- Огромный AGENTS.md в первый же день вместо короткой карты.
- Задача по расписанию для процесса, который ещё ни разу не отработал вручную.
- Полные права агенту до того, как команда поняла, что он делает.
- Перенос «минимума гейтов» на клиентский продакшен без обоснования.
- Harness, который не пересматривают при смене модели: часть правил перестаёт быть нужной, а новых возможностей никто не использует.
Попробуйте сами
10–15 мин на рабочем месте- Пройдите по пунктам «Завтра» для своего проекта и отметьте, что уже есть. Выберите три недостающих дела и поставьте их задачами в трекер.
- Заведите журнал провалов — файл в docs/ с колонками «задача, что сделал агент, что исправил человек, чего не хватило». Попросите команду заполнять его две недели.
- Договоритесь, кто в команде владелец harness пилотного проекта, и запишите это в AGENTS.md.
Коротко
- Начинайте с одного пилотного проекта, где уже есть тесты и ежедневная работа с агентом.
- Неделя — агент проверяет себя сам и копятся сигналы; месяц — направляющие и датчики в коде; квартал — шаблоны, регресс и петля улучшения.
- Провал агента — задача для harness, а не для поиска виноватого.
- Практики OpenAI переносите с оглядкой: их среда строилась под агентов с первого коммита.
- Рядом со скоростью измеряйте стабильность и следите, чтобы обвязка не только росла, но и худела.
