Чему вы научитесь

Это руководство охватывает инженерию обвязки (harness engineering) от фундаментальных принципов до практической реализации. Вы поймете, что это такое, почему OpenAI сделала на это ставку в своем крупнейшем внутреннем проекте, какие специфические архитектурные паттерны обеспечивают ее работу и как применить эти принципы в ваших собственных рабочих процессах с ИИ-агентами — используете ли вы Codex, Claude Code, OpenCode или любую другую агентную систему.

Harness Engineering: Полное руководство по разработке ИИ-агентов в 2026 году

Если 2025 год стал годом, когда ИИ-агенты доказали, что могут писать код, то 2026 год — это год, когда мы поняли, что сложность не в агенте, а в обвязке (harness).

Команда OpenAI Codex опубликовала знаковую статью в блоге в феврале 2026 года, описывающую, как они создали продакшн-приложение, содержащее примерно один миллион строк кода, где ни одна строка не была написана человеческими руками. Секрет заключался не в более совершенной модели или умном промпте. Это была система, которую они выстроили вокруг агента — обвязка (harness). Источник

В этом руководстве разбираются все принципы, паттерны и практические методы, извлеченные из этого эксперимента и более широкого движения harness engineering, возникшего вокруг него.

Часть 1: Что такое Harness Engineering?

Определение

Harness engineering — это дисциплина проектирования всей среды — каркасов (scaffolding), циклов обратной связи, документации, архитектурных ограничений и машиночитаемых артефактов — которая позволяет ИИ-агентам по кодингу выполнять надежную и высококачественную работу в масштабе с минимальным вмешательством человека.

Термин "harness" (сбруя, упряжь) пришел из конной экипировки: поводья, седло, удила — полный набор снаряжения для направления мощного, но непредсказуемого животного в нужное русло. Неуправляемая лошадь опасна. Лошадь в упряжи строила цивилизации. То же самое применимо к ИИ-агентам. Источник

Почему это появилось именно сейчас

Переход от prompt engineering к harness engineering отражает взросление ландшафта разработки ИИ:

Источник

Ключевое озарение, которое привело к этому переходу: агенты стали достаточно функциональными, и узкое место сместилось с качества модели на качество среды. Современная модель (state-of-the-art), работающая в плохо структурированном репозитории, выдает худшие результаты, чем посредственная модель в хорошо подготовленной обвязке.

Часть 2: Эксперимент OpenAI Codex

Масштаб

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

Команда

Проект начался всего с трех инженеров, управлявших Codex. За пятимесячный период было открыто и объединено около 1,500 Pull Request. Когда команда выросла до семи инженеров, пропускная способность увеличилась — контринтуитивный результат, который показал, что именно обвязка (harness) была основным множителем производительности, а не индивидуальные навыки.

OpenAI оценивает, что они построили систему примерно в десять раз быстрее, чем потребовалось бы для написания кода вручную. Источник

Начальный каркас (Scaffold)

Проект начался с того, что Codex CLI сгенерировал начальный каркас (scaffold) с помощью GPT-5, руководствуясь небольшим набором существующих шаблонов:

• Структура репозитория и соглашения по директориям
• Конфигурация CI/CD
• Правила форматирования кода и линтинга
• Настройка менеджера пакетов
• Бойлерплейт фреймворка приложения

Из этого семени все остальное выросло благодаря разработке, управляемой агентами.

Проблема пятницы

В начале эксперимента команда обнаружила критическую проблему: каждую пятницу они тратили 20% своего инженерного времени на очистку того, что они назвали "ИИ-шлаком" (AI slop). Это включало несогласованные паттерны, дублирующуюся логику, неправильно названные переменные и архитектурные отклонения.

Это было не масштабируемо. Решением стало кодирование их стандартов непосредственно в обвязку (harness), чтобы агенты с самого начала выдавали более чистый результат, и создание автоматизированных систем очистки для остаточных отклонений.

Часть 3: Пять основных принципов

Принцип 1: Знания прежде всего в репозитории (Repository-First Knowledge)

С точки зрения агента, всего, к чему он не может получить доступ в контексте во время работы, фактически не существует. Знания, которые живут в Google Docs, ветках чатов, сообщениях Slack или в головах людей, невидимы для системы.

Это означает, что все знания должны существовать в виде локальных версионных артефактов репозитория:

• Код — основной артефакт
• Markdown документация — архитектурные решения, соглашения, руководства по онбордингу
• Схемы — контракты API, схемы баз данных, определения типов
• Исполняемые планы — пошаговые разбивки задач, которым агент может следовать
• Конфигурация — правила линтеров, CI пайплайны, стандарты форматирования

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

Практическая реализация:

# ARCHITECTURE.md (находится в корне репо)

## Правила зависимостей
- Компоненты UI могут импортировать из уровня Service, но никогда из уровня Repo
- Уровень Service не может импортировать из уровня Runtime
- Все междоменное взаимодействие идет через типизированную шину событий

## Соглашения об именовании
- React компоненты: PascalCase, с суффиксом по назначению (UserListPage, UserCard)
- Services: camelCase, с суффиксом Service (userService, authService)
- Types: PascalCase, с префиксом домена (UserProfile, OrderItem)

## Требования к тестированию
- Все функции Service требуют модульных тестов
- Все эндпоинты API требуют интеграционных тестов
- Порог покрытия: 80% на пакет

Принцип 2: Золотые принципы (Golden Principles)

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

Примеры из эксперимента OpenAI:

1. Предпочитать общие утилиты самописным помощникам — централизует инварианты, так что при необходимости изменить поведение, оно меняется в одном месте.
2. Не исследовать данные в стиле YOLO — валидируйте границы или полагайтесь на типизированные SDK, чтобы агенты случайно не строили логику на угаданных формах данных.
3. Одна концепция — один файл — каждый файл должен представлять одну концепцию, что облегчает агентам поиск и изменение нужного места.
4. Явное лучше неявного — избегайте магического поведения, для понимания которого агенту потребовались бы сакральные знания команды.

Источник

Эти принципы — не просто документация. Они обеспечиваются:

• Правилами линтера — кастомные линтеры (сами созданные Codex), которые помечают нарушения.
• Структурными тестами — тесты, проверяющие соблюдение архитектуры.
• CI гейтами — Pull Request, нарушающие золотые принципы, отклоняются автоматически.

Принцип 3: Многослойная архитектура с механическим контролем

Каждый бизнес-домен в проекте OpenAI разделен на фиксированный набор слоев со строго валидируемыми направлениями зависимостей:

Types → Config → Repo → Service → Runtime → UI

Зависимости текут только в одном направлении. Компонент UI может зависеть от Runtime и Service, но Service никогда не может импортировать из UI. Repo может зависеть от Config и Types, но никогда от Service. Источник

Эти ограничения обеспечиваются механически:

// structural-test.ts — контролирует границы зависимостей
import { analyzeImports } from './tools/import-analyzer';

describe('Dependency Layer Enforcement', () => {
  it('Service layer must not import from Runtime', () => {
    const violations = analyzeImports({
      sourceLayer: 'service',
      forbiddenLayers: ['runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });

  it('Repo layer must not import from Service', () => {
    const violations = analyzeImports({
      sourceLayer: 'repo',
      forbiddenLayers: ['service', 'runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });
});

Структурные тесты подтверждают соответствие и предотвращают нарушения модульной многослойности. Это не предложение — это требование CI. Каждый Pull Request, созданный человеком или агентом, должен пройти эти тесты.

Принцип 4: Автоматизированная сборка мусора (Automated Garbage Collection)

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

1. Сканируют на наличие отклонений от золотых принципов по всей кодовой базе.
2. Обновляют оценки качества для каждого модуля на основе баллов соответствия.
3. Открывают целевые Pull Request на рефакторинг, которые исправляют конкретные категории отклонений.

Это заменило ручную "пятничную очистку" системой, которая работает непрерывно. Сам сборщик мусора работает на агентах Codex, создавая самоподдерживающийся цикл. Источник

# .github/workflows/garbage-collection.yml
name: Codebase Garbage Collection
on:
  schedule:
    - cron: '0 2 * * *'  # Запуск каждую ночь в 2 часа ночи

jobs:
  gc-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run golden principle scanner
        run: npx codex-gc scan --principles ./GOLDEN_PRINCIPLES.md
      - name: Generate refactoring PRs
        run: npx codex-gc fix --auto-pr --max-prs 5

Принцип 5: Исполняемые планы

Прежде чем агенты напишут код, они пишут планы. Эти планы — не неформальные заметки, а структурированные, исполняемые документы, которые определяют:

• Цель: Что задача выполняет.
• Файлы для изменения: Явный список файлов, которые затронет агент.
• Зависимости: Другие задачи или модули, от которых зависит эта работа.
• Критерии приемки: Как проверить, что работа завершена.
• Ограничения: Архитектурные правила, которые нельзя нарушать.

# План: Добавить настройки уведомлений пользователя

## Цель
Позволить пользователям настраивать каналы уведомлений (email, SMS, push),
которые они получают, с детализацией по категориям.

## Файлы для изменения
- src/types/user.ts — Добавить тип NotificationPreferences
- src/repo/userRepo.ts — Добавить методы getPreferences/setPreferences
- src/service/notificationService.ts — Фильтровать уведомления по настройкам
- src/ui/pages/SettingsPage.tsx — Добавить раздел настроек в UI

## Ограничения
- Должен соблюдаться поток зависимостей Types → Repo → Service → UI
- Тип NotificationPreferences должен быть общим, а не дублироваться
- Все новые методы требуют модульных тестов

## Критерии приемки
- [ ] Пользователь может переключать email/SMS/push для каждой категории уведомлений
- [ ] Настройки сохраняются между сессиями
- [ ] Отключение канала прекращает уведомления в этом канале в течение 30 секунд

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

Часть 4: Цикл агента Codex

Понимание того, как цикл агента Codex работает внутри обвязки (harness), важно для эффективной инженерии обвязки.

Архитектура цикла

OpenAI опубликовала подробный разбор цикла агента Codex в сопутствующей статье "Unrolling the Codex agent loop". Источник Цикл следует по этой схеме:

Чтение контекста → Планирование → Выполнение → Валидация → Commit (или Повтор)

Каждая итерация:

1. Чтение контекста: Агент читает соответствующие файлы, документацию, схемы и план задачи из репозитория.
2. Планирование: Основываясь на контексте, агент определяет, какие изменения внести.
3. Выполнение: Агент пишет или изменяет код.
4. Валидация: Обвязка запускает тесты, линтеры и структурные проверки внесенных изменений.
5. Commit или Повтор: Если валидация пройдена, агент фиксирует изменения (commit). Если нет, агент читает лог ошибок и пробует снова.

Роль обвязки (harness) заключается в том, чтобы сделать шаги 1 и 4 максимально информативными. Чем больше контекста читает агент, тем лучше его план. Чем точнее обратная связь при валидации, тем быстрее он придет к рабочему решению.

Обвязка App Server

В статье "Unlocking the Codex harness: how we built the App Server" OpenAI описывает конкретную инфраструктуру, которая обеспечивает работу цикла агента. Источник App Server предоставляет:

• Песочницы для выполнения (sandboxed environments) для каждой задачи агента.
• Предварительно настроенный доступ к инструментам (файловая система, терминал, браузер).
• Автоматическую вставку контекста из артефактов репозитория.
• Потоковую обратную связь по валидации, чтобы агенты могли видеть ошибки тестов в реальном времени.

Часть 5: Применение инженерии обвязки в вашей команде

С чего начать: Минимально жизнеспособная обвязка (MVH)

Вам не нужно копировать всю инфраструктуру OpenAI, чтобы получить выгоду от инженерии обвязки. Начните с этих базовых элементов:

Шаг 1: Создайте ARCHITECTURE.md

Задокументируйте архитектурные правила вашего проекта в машиночитаемом формате в корне репозитория. Включите:

• Границы модулей и разрешенные зависимости.
• Соглашения об именовании.
• Правила организации файлов.
• Требования к тестированию.

Этот единственный файл значительно улучшает качество работы агента, так как агенты читают его перед внесением изменений.

Шаг 2: Добавьте структурные тесты

Напишите тесты, которые проверяют ваши архитектурные правила. Эти тесты не проверяют бизнес-логику — они проверяют правильность организации кода:

// Ни один файл сервиса не должен импортировать из модуля UI
test('service layer isolation', () => {
  const serviceFiles = glob('src/services/**/*.ts');
  for (const file of serviceFiles) {
    const imports = extractImports(file);
    const uiImports = imports.filter(i => i.startsWith('../ui/'));
    expect(uiImports).toHaveLength(0);
  }
});

Шаг 3: Настройте CI-валидацию

Убедитесь, что ваш CI-пайплайн запускает структурные тесты, линтеры и проверки типов для каждого Pull Request — включая те, что созданы агентами. Агент должен видеть тот же результат валидации, что и человек-разработчик.

Шаг 4: Пишите планы задач перед запуском агента

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

Шаг 5: Настройте автоматическую очистку

Запускайте еженедельную или ночную CI-задачу, которая сканирует кодовую базу на предмет отклонений от ваших стандартов и создает сфокусированные Pull Request на рефакторинг.

Выбор агентной системы

Принципы harness engineering применимы независимо от того, какого агента вы используете:

Обвязка (harness) живет в вашем репозитории, а не в агенте. Это означает, что вы можете менять агентов, не теряя вложений в обвязку.

Масштабирование от одного агента к многим

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

Ключевые требования для параллельной работы агентов:

1. Четкое владение модулями — каждый агент работает в определенных границах.
2. Типизированные интерфейсы между модулями — агенты могут писать код для интерфейсов, не зная деталей реализации.
3. Предотвращение конфликтов слияния — задачи ограничены так, чтобы минимизировать пересечение файлов.
4. Централизованная валидация — все агенты отправляют код в один и тот же CI-пайплайн.

Часть 6: Распространенные ловушки и антипаттерны

Антипаттерн 1: Отношение к агенту как к обвязке

Агент — это не обвязка. Обвязка — это среда, в которой работает агент. Попытка заставить более умную модель компенсировать плохо структурированный репозиторий — это неправильный подход. Исправляйте среду, а не промпт.

Антипаттерн 2: Документация в неположенном месте

Если ваши архитектурные решения живут в Confluence, Notion или Google Docs, агенты их не видят. Решение простое, но требует дисциплины: перенесите всю документацию, имеющую отношение к разработке, в репозиторий.

Антипаттерн 3: Ручная очистка вместо автоматического контроля

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

Антипаттерн 4: Избыточные ограничения

Слишком жесткая обвязка мешает агентам находить творческие решения. Цель состоит в том, чтобы ограничить архитектуру, а не реализацию. Укажите агентам, какие модули они могут изменять и какие зависимости разрешены, но позвольте им самим решать, как реализовать логику внутри этих границ.

Антипаттерн 5: Игнорирование обратной связи от агента

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

Часть 7: Будущее Harness Engineering

Взгляд Мартина Фаулера

Мартин Фаулер опубликовал анализ harness engineering в своем блоге, отметив, что это представляет собой фундаментальный сдвиг в работе команд разработчиков ПО. Эта дисциплина заимствует лучшие практики программной инженерии десятилетий — непрерывную интеграцию, записи архитектурных решений (ADR), внедрение зависимостей — но перепрофилирует их для мира, управляемого агентами. Источник

Фреймворк HumanLayer

Команда HumanLayer опубликовала анализ, назвав harness engineering "проблемой навыков" (skill issue) — утверждая, что способность проектировать эффективные обвязки станет основным отличием между высокопроизводительными и испытывающими трудности инженерными командами. Источник

Что это значит для разработчиков

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

Для команд, создающих приложения, такие платформы, как ZBuild, уже внедряют принципы harness engineering в свои рабочие процессы. Вместо того чтобы требовать от разработчиков проектировать собственные обвязки с нуля, ZBuild предоставляет предварительно настроенные архитектурные паттерны, управление зависимостями и системы валидации, которые направляют ИИ-агентов к высококачественному результату — позволяя разработчикам сосредоточиться на продуктовых решениях, а не на инфраструктуре.

Три горизонта

Заглядывая вперед, можно ожидать, что harness engineering пройдет три фазы эволюции:

1. Краткосрок (2026): Команды внедряют документацию в стиле "сначала репозиторий", структурные тесты и золотые принципы. Разработка с помощью агентов становится стандартной практикой для проектов с хорошей обвязкой.

2. Среднесрок (2027): Генерация самой обвязки становится управляемой агентами. Агенты анализируют существующие кодовые базы и предлагают конфигурации обвязки — правила линтеров, структурные тесты, границы зависимостей — на основе наблюдаемых паттернов.

3. Долгосрок (2028+): Обвязки становятся адаптивными. Вместо статических правил они эволюционируют на основе результатов работы кода, созданного агентами, автоматически ужесточая ограничения там, где агенты часто ошибаются, и ослабляя их там, где они стабильно добиваются успеха.

Часть 8: Практический чек-лист

Используйте этот чек-лист для оценки зрелости инженерии обвязки в вашей команде:

Фундамент (Начните отсюда)

• ARCHITECTURE.md существует в корне репозитория
• Форматирование кода автоматизировано (Prettier, Black, gofmt)
• Линтинг запускается для каждого Pull Request
• Проверка типов обязательна (TypeScript strict, mypy и т. д.)

Средний уровень

• Структурные тесты валидируют границы зависимостей
• Золотые принципы задокументированы и механически проверяемы
• Планы задач пишутся перед выполнением агентом
• Pull Request, созданные агентами, проходят тот же CI, что и человеческие

Продвинутый уровень

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

Экспертный уровень

• Агенты генерируют части обвязки (правила линтера, структурные тесты)
• Оценки качества автоматически присваиваются каждому модулю
• Улучшения обвязки основаны на данных об успехе агентов
• Команда выпускает больше кода на одного инженера в неделю, чем до внедрения агентов

Заключение

Harness engineering — это не мимолетное увлечение. Это естественная эволюция программной инженерии в эпоху, когда ИИ-агенты способны писать продакшн-код, но нуждаются в структурированной среде для качественной работы. Эксперимент OpenAI с миллионом строк кода доказал жизнеспособность концепции в масштабе, а сформулированные ими принципы — знания прежде всего в репозитории, золотые принципы, многослойная архитектура, автоматизированная сборка мусора и исполняемые планы — применимы к командам любого размера.

Команды, которые освоят harness engineering в 2026 году, будут выпускать продукты быстрее, поддерживать более высокое качество кода и масштабироваться эффективнее, чем те, кто относится к ИИ-агентам как к продвинутому автодополнению. Агент — это лошадь. Обвязка (harness) — это то, что делает ее полезной.

Источники

• Harness Engineering: Leveraging Codex in an Agent-First World — OpenAI
• Unlocking the Codex Harness: How We Built the App Server — OpenAI
• Unrolling the Codex Agent Loop — OpenAI
• OpenAI Introduces Harness Engineering — InfoQ
• Harness Engineering — Martin Fowler
• Skill Issue: Harness Engineering for Coding Agents — HumanLayer
• From Prompt Engineering to Harness Engineering — SoftmaxData
• How to Build an Agent Harness — Study Notes
• Harness Engineering — GTCode
• OpenAI Harness Engineering: Ship 1M Lines of Code — The Neuron
• How OpenAI Built 1M Lines of Code Using Only Agents — TonyLee
• Harness Engineering — The New Discipline — CodeNote