中文版本 →

Примеры кода: code/ Практический проект: Project 01. Prompt-only vs. rules-first

Лекция 01. Сильные модели не означают надёжного исполнения

Считаете себя бывалым в мире AI — есть подписка Claude Pro, ключ к API GPT-4o, цифры с лидерборда SWE-bench выучены наизусть. И вот вы наконец отдаёте AI-агенту реальный проект, переполненные уверенностью. Результат? Он добавляет фичу, но ломает тесты, чинит баг, но создаёт два новых, работает 20 минут и гордо заявляет «готово» — а вы смотрите на код и видите, что это совсем не то, о чём вы просили.

Первая мысль? «Модель слабовата. Пора апгрейдиться». Стоп. Прежде чем доставать кошелёк, подумайте: возможно, проблема вовсе не в модели.

Посмотрим на цифры. К концу 2025 года самые сильные кодинг-агенты на SWE-bench Verified выдают примерно 50–60%. И это на тщательно отобранных задачах с понятными описаниями issue и существующими тестами. Перейдите в свою повседневную среду разработки — расплывчатые требования, отсутствие тестов, неявные бизнес-правила, разбросанные повсюду — и эта цифра только падает.

Но за этими числами скрывается контринтуитивная истина.

Один и тот же конь, разные судьбы

Anthropic провели контролируемый эксперимент. Один и тот же промпт («собери 2D ретро-конструктор игр»), одна и та же модель (Opus 4.5). Первый прогон: голая среда без поддержки — 20 минут, $9, ключевые механики игры просто не работают. Второй прогон: полный harness (архитектура из трёх агентов: planner + generator + evaluator) — 6 часов, $200, в игру можно играть.

Модель не меняли. Opus 4.5 оставался Opus 4.5. Изменилось седло.

Статья OpenAI 2025 года про harness engineering говорит прямо: Codex в репозитории с хорошим harness переходит из «ненадёжного» в «надёжный». Обратите внимание на формулировку — не «чуть лучше», а качественный сдвиг. Как с породистой лошадью: ездить можно и без седла, но далеко не уедете, быстро не разгонитесь, и упасть — не сюрприз. Harness и есть это седло — всё в инженерной инфраструктуре, что находится за пределами весов модели.

Где на самом деле застревают агенты

Так что же конкретно идёт не так?

Самое частое: вы так и не определили задачу чётко. Говорите «добавь поиск», а агент понимает это совсем не так, как вы — поиск чего? Полнотекстовый или структурированный? Пагинация? Подсветка? Вы не уточнили — агент гадает. Угадал — повезло; не угадал — фиксить дороже, чем было бы изначально внятно поставить задачу. Это как зайти в ресторан и сказать повару «я буду рыбу» — будет ли она тушёная, на пару или в горячем горшочке, остаётся на волю случая.

Даже если вы всё указали, в проекте есть неявные архитектурные конвенции, о которых агент не знает. Ваша команда стандартизировала синтаксис SQLAlchemy 2.0, а агент по умолчанию пишет код 1.x. Все API-эндпоинты должны использовать OAuth 2.0, но это правило существует только в вашей голове и в сообщении в Slack трёхмесячной давности. Агент этого не видит — не то чтобы он не хотел соблюдать, он буквально не знает, что эти правила существуют.

Среда — тоже ловушка. Неполная dev-среда, отсутствующие зависимости, неправильные версии инструментов. Агент жжёт драгоценное окно контекста на ошибки pip install и несовпадения версий Node вместо того, чтобы решать вашу реальную задачу. Как нанять умелого плотника, но забыть дать ему молоток, гвозди и ровный верстак — каким бы талантливым он ни был, работу он не сделает.

Ещё чаще: попросту нет способа верифицировать. Нет тестов, нет линта, или команды проверки никогда не были донесены до агента. Агент пишет код, смотрит на него, решает что норм, говорит «готово». Это как просить студента сдать домашку, не дав ему ответника — он думает, что всё правильно, а при проверке — куча ошибок. Anthropic заметили любопытное явление: когда агент чувствует, что контекст заканчивается, он торопится закончить, пропускает верификацию и выбирает простое решение вместо оптимального. Они называют это «контекстной тревогой» — тем же, что случается, когда вы понимаете, что время на экзамене на исходе, и начинаете наугад тыкать в оставшихся тестовых вопросах.

Длинные задачи на несколько сессий — ещё хуже: все находки прошлой сессии теряются, и каждая новая сессия заново исследует структуру проекта и заново разбирается в организации кода. У агентов без персистентного состояния процент провалов резко растёт на задачах длиннее 30 минут.

Ключевая терминология

Когда вы видите эти сценарии вживую, термины перестают быть просто жаргоном:

• Capability Gap: огромная пропасть между производительностью модели на бенчмарках и на реальных задачах. 50–60% pass rate на SWE-bench Verified означает, что почти половина реальных issue не решается.
• Harness: всё за пределами модели — инструкции, инструменты, среда, управление состоянием, верификационная обратная связь. Если это не веса модели — это harness. То самое «седло».
• Harness-Induced Failure: у модели достаточно способностей, но в среде исполнения есть структурные дефекты. Контролируемый эксперимент Anthropic это уже доказал.
• Verification Gap: разрыв между уверенностью агента в своей работе и реальной корректностью. Агент говорит «я закончил», когда не закончил — самый частый паттерн провала.
• Diagnostic Loop: выполнить, увидеть провал, отнести его к конкретному слою harness, починить этот слой, выполнить снова. Это ядро методологии harness engineering.
• Definition of Done: набор машинно-проверяемых условий — тесты проходят, линт чистый, проверки типов проходят. Без явного definition of done агент придумает свой.

Когда что-то ломается — чините harness первым

Главный принцип: когда что-то ломается, не меняйте сразу модель — проверьте harness. Если та же модель справляется со схожими, хорошо структурированными задачами, считайте, что проблема в harness. Это как с поломкой машины — вы же не сразу подозреваете двигатель. Сначала проверяете, не закончился ли бензин.

Конкретные шаги:

Привязывайте каждый провал к конкретному слою. Не ограничивайтесь «модель тупит». Спросите: задача была размыта? Контекста не хватало? Не было способов верификации? Сопоставьте каждый провал с одним из пяти защитных слоёв (спецификация задачи, предоставление контекста, среда исполнения, верификационная обратная связь, управление состоянием). Выработайте эту привычку — и в ваших логах «модель недостаточно хороша» будет всплывать всё реже.

Пишите явный Definition of Done для каждой задачи. Не «добавь поиск». А:

Критерии готовности:
- Новый эндпоинт GET /api/search?q=xxx
- Поддержка пагинации, по умолчанию 20 элементов
- В результатах подсвеченные сниппеты
- Весь новый код проходит pytest
- Проверка типов проходит (mypy --strict)

Заведите файл AGENTS.md. Положите его в корень репо, чтобы рассказать агенту про стек проекта, архитектурные конвенции и команды верификации. Это первый шаг harness engineering и шаг с самым высоким ROI. Один файл AGENTS.md может быть эффективнее апгрейда на более дорогую модель — я не шучу.

Постройте диагностическую петлю. Не относитесь к провалам как к «модель опять тупит». Считайте их сигналами, что в вашем harness есть дефект. На каждом провале определите слой, почините его, никогда больше так не падайте. Через несколько итераций harness крепнет, а производительность агента стабилизируется. Как ремонт дороги — каждая засыпанная яма делает следующий участок ровнее.

Измеряйте улучшения. Ведите простой лог: каждая задача — успех или провал, и какой слой стал причиной провала. Через несколько кругов вы увидите, какой слой — бутылочное горлышко. Туда и направляйте усилия.

Эксперимент в миллион строк

В 2025 году OpenAI провели агрессивный эксперимент: с помощью Codex построить целый внутренний продукт из пустого git-репозитория. Через пять месяцев в репо было примерно миллион строк кода — прикладная логика, инфраструктура, инструментарий, документация, внутренние dev-инструменты — всё сгенерировано агентом. Три инженера управляли Codex, открыли и смержили около 1500 PR. В среднем 3,5 PR на человека в день.

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

В начале прогресс был медленнее ожидаемого. Не потому что у Codex не хватало способностей, а потому что среда была недостаточно полной — агенту не хватало нужных инструментов, абстракций и внутренних структур, чтобы продвигаться к высокоуровневым целям. Работа инженеров превратилась в: разбиение больших целей на маленькие строительные блоки (дизайн, код, ревью, тест), сборку их агентом, а затем использование этих блоков для разблокирования более сложных задач. Когда что-то ломалось, фиксом почти никогда не было «попробуем сильнее» — было «какой способности агенту не хватает и как сделать её одновременно понятной и исполняемой?».

Этот эксперимент напрямую подтверждает главный тезис лекции: одна и та же модель в голой среде и в среде с полным harness даёт принципиально разные результаты. Модель не менялась. Менялась среда.

Источник: OpenAI: Harness engineering: leveraging Codex in an agent-first world

Более приземлённый пример

Команда использовала Claude Sonnet, чтобы добавить новый API-эндпоинт в среднеразмерное Python-веб-приложение (FastAPI + PostgreSQL + Redis, ~15 000 строк кода).

Сначала они дали только одну фразу: «добавь эндпоинты пользовательских настроек под /api/v2/users». Результат? Агент потратил 40% окна контекста на исследование структуры репо, выдал код, который выглядел разумно, но не следовал паттернам обработки ошибок проекта, использовал старый синтаксис SQLAlchemy и заявил о завершении, в то время как у эндпоинта были рантайм-ошибки. Следующая сессия должна была заново проделать всю разведку.

Потом они добавили AGENTS.md (с описанием архитектуры проекта и версий стека), явные команды верификации (pytest tests/api/v2/ && python -m mypy src/) и architecture decision records. Та же модель успешно справилась во всех трёх независимых прогонах, и эффективность контекста выросла примерно на 60%.

Модель они не меняли. Они меняли harness.

Главное

• Способности модели и надёжность исполнения — разные вещи. Породистой лошади всё равно нужно хорошее седло.
• Когда что-то ломается, сначала проверьте harness, потом модель. Менять модель — самый дорогой вариант, и часто это вообще не проблема модели.
• Каждый провал — сигнал: в вашем harness структурный дефект. Найдите, почините.
• Пять защитных слоёв: спецификация задачи, предоставление контекста, среда исполнения, верификационная обратная связь, управление состоянием. Проверяйте систематически, как врач сначала отметает самые частые причины.
• Один файл AGENTS.md может оказаться эффективнее апгрейда на более дорогую модель. Серьёзно.

Дальнейшее чтение

• OpenAI: Harness Engineering — Leveraging Codex in an Agent-First World
• Anthropic: Effective Harnesses for Long-Running Agents
• HumanLayer: Skill Issue — Harness Engineering for Coding Agents
• SWE-bench Leaderboard
• Thoughtworks Technology Radar: Harness Engineering

Упражнения

1. Сравнительный эксперимент: возьмите хорошо знакомую вам кодовую базу и нетривиальную задачу на изменение. Сначала прогоните агента без harness-поддержки и зафиксируйте провалы. Затем добавьте AGENTS.md с явными командами верификации и прогоните снова с тем же агентом. Сравните результаты, относя каждый провал к одному из пяти защитных слоёв.

2. Замер verification gap: возьмите 5 кодинг-задач. После каждой зафиксируйте, заявил ли агент о завершении, а затем независимыми тестами проверьте реальную корректность. Посчитайте долю случаев, когда агент говорит «готово», а на самом деле нет — это и есть ваш verification gap. Затем подумайте: какие команды верификации сократили бы эту долю?

3. Практика диагностической петли: найдите в проекте задачу, на которой агент стабильно падает. Прогоните один раз, зафиксируйте провал. Отнесите его к одному из пяти слоёв. Почините слой. Прогоните снова. Повторите три–пять раз, фиксируя улучшения каждый раз.