Как перестать писать код руками и начать проектировать поводья для нейросетей

Недавно я поймал себя на странном ощущении. Сидишь в редакторе, запускаешь агента вроде Claude Code или Cursor, даешь ему задачу, а через десять минут разгребаешь кашу из выдуманных функций и поломанных типов. Попытка надиктовать длинный системный промпт на пять страниц обычно делает только хуже: модель забывает начало инструкции уже на третьем шаге.

Оказывается, в сообществе инженеров вокруг OpenAI, Anthropic и Cursor эту проблему уже оформили в отдельную дисциплину. Называется она Harness Engineering, что можно перевести как проектирование обвязки или упряжи для агентов.

Репозиторий deusyu/harness-engineering собрал в одном месте огромную базу знаний по этой теме: разборы концепций, переводы десятков англоязычных статей от инженеров Мартина Фаулера, LangChain и создателей Bun, а также готовые шаблоны для внедрения такого подхода в свои проекты.

Откуда взялась идея

Если в классической разработке человек пишет код, а машина его исполняет, то с приходом автономных агентов цепочка меняется. Человек формулирует ограничения и правила игры, нейросеть пишет код, а среда гоняет проверки и возвращает обратную связь агенту.

Смысл в том, что инженер перестает быть автором каждой строчки. Главным продуктом инженера становится система ограничений: конфигурационные файлы AGENTS.md, кастомные линтеры, структурные тесты и жесткие гейты в CI.

В репозитории приводятся данные реального эксперимента одной из команд: за 5 месяцев команда из 3-7 человек влила около 1500 пулл-реквестов объемом под миллион строк кода, закрывая в среднем по 3.5 PR на человека в день. Основная часть генерации крутилась по ночам сессиями по шесть часов подряд.

Главные принципы Harness Engineering

Автор репозитория деконструирует подход на несколько прикладных концепций.

Репозиторий как единственный источник правды

Все, чего нет внутри git-репозитория, для агента не существует. Ваши созвоны в Zoom, обсуждения архитектуры в Slack или черновики в Google Docs не попадают в контекст модели.

Если вы приняли решение изменить сигнатуру API или договорились о структуре папок, это должно лежать в репозитории в виде версионируемых файлов. Любые спецификации и планы задач сразу коммитятся в ветку.

Карта вместо энциклопедии

Частая ошибка при настройке агентной разработки заключается в создании гигантского системного файла с описанием всех инструкций проекта. Модели захлебываются в длинных промптах.

Вместо этого используется файл AGENTS.md размером около 100 строк. Он работает как оглавление или карта местности, подсказывая агенту, в какие подкаталоги смотреть за деталями в зависимости от задачи. В каждом подкаталоге лежит свой локальный AGENTS.md. Этот принцип называют прогрессивным раскрытием контекста.

Механический контроль вместо словесных уговоров

Текстовые правила в документации быстро устаревают, а агенты склонны их игнорировать или трактовать превратно. Линтеры и юнит-тесты не устаревают.

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

+----------------+      генерирует код      +------------------+
| AI Agent       | -----------------------> | Исходный код     |
+----------------+                          +------------------+
        ^                                             |
        | читает ошибку и инструкцию                  v
+----------------+    провалил проверку     +------------------+
| Feedback Loop  | <----------------------- | Linter / Tests   |
+----------------+                          +------------------+

Читаемость кода для агентов и управление энтропией

При выборе библиотек приоритет отдается стабильным, хорошо задокументированным технологиям с предсказуемым поведением. Если библиотека слишком сложная или использует темную магию метапрограммирования, агент будет постоянно спотыкаться. Иногда проще реализовать простой внутренний модуль с нуля, чем заставлять нейросеть угадывать поведение непрозрачного внешнего пакета.

Кроме того, агенты обожают копировать плохие паттерны, если находят их в существующей кодовой базе. Чтобы репозиторий не загнивал, в фоновом режиме запускают специальных рефакторинг-агентов, задача которых сводится к поиску отклонений от стандартов и созданию корректирующих PR.

Самореферентный репозиторий

Что подкупает в проекте deusyu/harness-engineering — он сам построен по тем принципам, о которых рассказывает.

Внутри репозитория работает строгий скрипт scripts/check-consistency.sh, запускаемый через pre-commit хуки и GitHub Actions. Скрипт проверяет тринадцать уровней целостности:

Сверяет точное количество упоминаемых статей в бейджах и документации
Следит за соответствием структуры каталогов заявленному дереву файлов
Проверяет валидность всех ссылок и таблиц
Контролирует аудит картинок в переводах статей, чтобы ни одна схема из оригиналов не потерялась

Процесс добавления новых материалов автоматизирован через специализированный навык Claude, где агенты проводят первичный разбор и форматирование статей, а человек выступает лишь финальным цензором.

# Включение локального контроля целостности перед коммитом
git config core.hooksPath .githooks

# Ручной запуск всех тринадцати проверок
bash scripts/check-consistency.sh

Для кого этот проект

Если вы пишете пет-проекты в одиночку или хотите выстроить в команде эффективную работу с Cursor, Claude Code, Aider или локальными моделями, этот репозиторий стоит положить в закладки.

Здесь нет волшебных кнопок или готовых бинарников. Это методичка и сборник инженерного опыта, объясняющий, почему ваши промпты перестают работать на дистанции и как настроить репозиторий так, чтобы нейросети приносили пользу, а не превращали кодовую базу в свалку.

Начать изучение проще всего с файлов в директории concepts/, а затем посмотреть реализацию AGENTS.md в корне проекта и примерить похожую структуру на свои рабочие репозитории.