[Перевод] Инженерия среды для агентов: использование Codex в мире с приоритетом агентов

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

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

Люди задают направление. Агенты исполняют.

Мы сознательно ввели это ограничение, чтобы вынудить себя построить всё необходимое для кратного увеличения скорости разработки. У нас были считанные недели на выпуск того, что в итоге превратилось примерно в миллион строк кода. Чтобы справиться с этим, нужно было понять, что меняется, когда основная задача команды разработки — уже не писать код, а проектировать среды, формулировать намерение и выстраивать циклы обратной связи, позволяющие агентам Codex надёжно выполнять работу.

Этот текст — о том, чему мы научились, создавая совершенно новый продукт вместе с командой агентов: что ломалось, что усиливалось со временем и как максимально эффективно использовать наш единственный по-настоящему дефицитный ресурс — человеческое время и внимание.

Мы начали с пустого репозитория Git

Первый коммит в пустой репозиторий была сделана в конце августа 2025 года.

Первичная структура — структура репозитория, конфигурация CI, правила форматирования, настройка менеджера пакетов и каркас приложения — была сгенерирована с помощью Codex CLI с использованием GPT-5 на основе небольшого набора существующих шаблонов. Даже исходный файл AGENTS.md, который задаёт правила работы агентов в репозитории, был написан самим Codex.

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

Пять месяцев спустя репозиторий насчитывает порядка миллиона строк кода: прикладная логика, инфраструктура, инструменты, документация и внутренние утилиты для разработчиков. За это время было создано и объединено около 1 500 пул-реквестов при участии небольшой команды всего из трёх инженеров, управлявших Codex. В среднем это соответствует 3,5 пул-реквестам на одного инженера в день, причём по мере роста команды до семи человек пропускная способность неожиданно увеличилась. Важно подчеркнуть, что это был не объём ради объёма: продукт использовали сотни внутренних пользователей, включая ежедневных активных пользователей.

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

Переосмысление роли инженера

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

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

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

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

Codex напрямую использует наши стандартные инструменты разработки — gh, локальные скрипты и встроенные в репозиторий скиллы — чтобы получать контекст без копирования и вставки со стороны человека в командную строку.

Люди могут просматривать пул-реквесты, но это не является обязательным. Со временем мы практически полностью перенесли процесс ревью на взаимодействие «агент — агент».

Повышение понятности приложения для агента

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

Например, мы сделали приложение запускаемым из каждого git worktree, чтобы Codex мог поднимать и управлять отдельным экземпляром под каждое изменение. Мы также интегрировали Chrome DevTools Protocol в среду выполнения агента и добавили инструменты для работы со снимками DOM, скриншотами и навигацией. Это позволило Codex самостоятельно воспроизводить ошибки, проверять исправления и напрямую анализировать поведение пользовательского интерфейса.

Аналогичным образом мы поступили со средствами наблюдаемости. Журналы, метрики и трассировки доступны Codex через локальный стек наблюдаемости, эфемерный для каждого worktree. Codex работает с полностью изолированной версией приложения — вместе с её журналами и метриками, которые удаляются после завершения задачи. Агенты могут выполнять запросы к журналам с помощью LogQL, а к метрикам — с помощью PromQL. При наличии такого контекста становятся выполнимыми промпты вроде «обеспечить запуск сервиса менее чем за 800 мс» или «ни один спан в этих четырёх критически важных пользовательских сценариях не должен превышать двух секунд».

Мы регулярно наблюдаем, как один запуск Codex работает над одной задачей более шести часов подряд — часто в то время, когда люди спят.

Мы сделали знания репозитория единым источником правды

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

Мы попробовали подход «один большой AGENTS.md». Он провалился по вполне предсказуемым причинам:

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

• Чрезмерные указания превращаются в отсутствие указаний. Когда «важно» всё, не важно ничего. Агенты начинают локально сопоставлять шаблоны вместо осмысленной навигации по системе.

• Такой документ быстро устаревает. Монолитное руководство превращается в кладбище устаревших правил. Агент не понимает, что из этого по-прежнему актуально, люди перестают поддерживать файл, и он незаметно становится источником проблем.

• Его трудно проверять. Единый массив текста плохо поддаётся механической проверке — по полноте, актуальности, закреплению ответственности, перекрёстным ссылкам — поэтому расхождение с реальностью неизбежно.

Поэтому вместо того чтобы воспринимать AGENTS.md как энциклопедию, мы используем его как оглавление.

База знаний репозитория находится в структурированном каталоге docs/, который рассматривается как единый источник истины. Короткий AGENTS.md (примерно на 100 строк) подаётся в контекст и выполняет роль карты, указывая на более глубокие и авторитетные источники информации в других частях репозитория.

AGENTS.md ARCHITECTURE.md docs/ ├── design-docs/ │ ├── index.md │ ├── core-beliefs.md │ └── ... ├── exec-plans/ │ ├── active/ │ ├── completed/ │ └── tech-debt-tracker.md ├── generated/ │ └── db-schema.md ├── product-specs/ │ ├── index.md │ ├── new-user-onboarding.md │ └── ... ├── references/ │ ├── design-system-reference-llms.txt │ ├── nixpacks-llms.txt │ ├── uv-llms.txt │ └── ... ├── DESIGN.md ├── FRONTEND.md ├── PLANS.md ├── PRODUCT_SENSE.md ├── QUALITY_SCORE.md ├── RELIABILITY.md └── SECURITY.md

Структура базы знаний в репозитории.

Проектная документация каталогизиро3вана и проиндексирована, включая статус проверки и набор базовых принципов, определяющих правила работы в режиме «с приоритетом агентов». Архитектурная документация даёт верхнеуровневую карту доменов и слоёв пакетов. Документ по качеству оценивает каждый продуктовый домен и архитектурный слой, отслеживая накопление разрывов и проблем со временем.

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

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

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

Главная цель — понятность для агента

По мере развития кодовой базы должна была эволюционировать и рамка (подход) Codex к проектным решениям.

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

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

Со временем мы поняли, что должны переносить всё больше контекста непосредственно в репозиторий. То обсуждение в Slack, где команда согласовала архитектурный подход? Если агент не может его обнаружить, для него оно столь же недоступно, как и для нового сотрудника, пришедшего через три месяца.

Дать Codex больше контекста — значит структурировать и предоставить правильную информацию так, чтобы агент мог на её основе рассуждать, а не заваливать его разрозненными указаниями. Точно так же, как вы вводите нового коллегу в курс продуктовых принципов, инженерных норм и командной культуры (вплоть до предпочтений по эмодзи), предоставление этой информации агенту приводит к более согласованному результату.

Такой подход прояснил многие неоднозначные моменты. Мы отдавали предпочтение зависимостям и абстракциям, которые можно полностью интерпретировать и анализировать внутри репозитория. Технологии, которые часто называют «скучными», обычно легче моделируются агентами благодаря композиционности, стабильности API и хорошему представлению в обучающем наборе. В ряде случаев оказалось дешевле поручить агенту заново реализовать часть функциональности, чем обходить непрозрачное поведение сторонних библиотек. Например, вместо подключения универсального пакета наподобие p-limit мы реализовали собственный вспомогательный механизм параллельного отображения с ограничением конкуренции (map-with-concurrency): он тесно интегрирован с нашим инструментированием OpenTelemetry, имеет 100% покрытие тестами и ведёт себя строго так, как ожидает наша среда выполнения.

Переводя всё больше компонентов системы в форму, которую агент может напрямую инспектировать, проверять и модифицировать, мы увеличиваем общий эффект — не только для Codex, но и для других агентов (например, Aardvark), работающих с этой кодовой базой.

Обеспечение архитектуры и инженерного вкуса

Одной документации недостаточно, чтобы поддерживать целостность кодовой базы, полностью сгенерированной агентами. Мы обеспечиваем соблюдение инвариантов, а не микроменеджмент конкретных реализаций, что позволяет агентам быстро выпускать изменения, не разрушая фундамент системы. Например, мы требуем от Codex валидировать формы (shapes) данных на границе системы, но не предписываем конкретный способ реализации (модель, похоже, предпочитает Zod, однако мы не задавали использование именно этой библиотеки).

Агенты наиболее эффективны в средах с жёсткими границами и предсказуемой структурой, поэтому мы построили приложение на основе строгой архитектурной модели. Каждый бизнес-домен разделён на фиксированный набор слоёв, с жёстко проверяемыми направлениями зависимостей и ограниченным набором допустимых связей между модулями. Эти ограничения механически обеспечиваются с помощью кастомных линтеров (разумеется, тоже сгенерированных Codex) и структурных тестов.

На диаграмме ниже отображено правило: внутри каждого бизнес-домена (например, «Настройки приложения») код может зависеть только «вперёд» по фиксированной цепочке слоёв (Types → Config → Repo → Service → Runtime → UI). Сквозные аспекты (аутентификация, коннекторы, телеметрия, фиче-флаги) подключаются через единственный явно определённый интерфейс — Providers. Любые другие зависимости запрещены и блокируются механически.

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

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

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

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

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

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

Рост пропускной способности меняет философию слияния

По мере увеличения пропускной способности Codex многие традиционные инженерные практики начали работать против нас.

В репозитории используются минимальные блокирующие проверки перед слиянием. Пул-реквесты живут недолго. Нестабильные тесты часто разруливаются повторными прогонами, а не блокируют процесс надолго. В системе, где производительность агентов значительно превышает объём человеческого внимания, исправления обходятся дёшево, а ожидание дорого.

В среде с низкой пропускной способностью такой подход был бы безответственным. Здесь же это зачастую оптимальный компромисс.

Что на самом деле означает «сгенерировано агентами»

Когда мы говорим, что кодовая база создана агентами Codex, мы имеем в виду всё без исключения.

Агенты создают:

• Код продукта и тесты

• Конфигурацию CI и инструменты релизов

• Внутренние инструменты разработки

• Документацию и историю проектных решений

• Оценочные харнессы (стенды)

• Комментарии к ревью и ответы на них

• Скрипты для управления самим репозиторием

• Файлы определения продакшн-дашбордов

Люди всегда остаются в контуре, но работают на другом уровне абстракции. Мы расставляем приоритеты, переводим пользовательскую обратную связь в критерии приёмки и проверяем результаты. Когда агент сталкивается с трудностями, мы воспринимаем это как сигнал: определить, чего не хватает — инструментов, ограничений, документации — и возвращаем это в репозиторий так, чтобы исправление писал сам Codex.

Агенты напрямую используют наши стандартные инструменты разработки. Они получают комментарии из ревью, отвечают на них прямо в интерфейсе, отправляют обновления и нередко сами выполняют squash и слияние своих пул-реквестов.

Рост уровня автономности

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

Получив один промпт, агент теперь способен:

• Проверить текущее состояние кодовой базы

• Воспроизвести заявленную ошибку

• Записать видео с демонстрацией сбоя

• Реализовать исправление

• Проверить исправление, управляя приложением

• Записать второе видео с демонстрацией устранения проблемы

• Создать пул-реквест

• Ответить на комментарии агентов и людей

• Обнаружить и устранить сбои сборки

• Обратиться к человеку только тогда, когда требуется суждение

• Произвести слияние изменений

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

Энтропия и «сборщик мусора»

Полная автономия агентов порождает и новые проблемы. Codex воспроизводит паттерны, уже присутствующие в репозитории — в том числе неровные или неудачные. Со временем это неизбежно приводит к дрейфу.

Сначала люди боролись с этим вручную. Наша команда раньше тратила каждую пятницу (около 20% рабочего времени) на уборку «AI-мусора». Очевидно, что такой подход не масштабируется.

Вместо этого мы начали кодировать так называемые «золотые принципы» непосредственно в репозитории и выстроили регулярный процесс очистки. Эти принципы представляют собой осознанные, формализованные правила, поддерживающие читаемость и согласованность кодовой базы для будущих запусков агента. Например: (1) мы предпочитаем общие пакеты утилит вместо самописных вспомогательных функций, чтобы централизовать инварианты, и (2) мы не исследуем данные «методом YOLO» — мы валидируем границы или используем типизированные SDK, чтобы агент не строил логику на предположительно угаданных структурах.

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

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

Чему мы всё ещё учимся

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

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

Одно стало ясно: разработка программного обеспечения по-прежнему требует дисциплины, но теперь она проявляется прежде всего в каркасе среды, а не в самом коде. Инструменты, абстракции и циклы обратной связи, поддерживающие целостность кодовой базы, становятся всё более значимыми.

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

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

Чтобы узнать больше о формате обучения и познакомиться с преподавателями, приходите на бесплатные уроки:

• 17 марта, 20:00. «Концепция ИИ-агентов и мультиагентных систем». Записаться

• 24 марта, 20:00. «Как остаться умнее ИИ в 2026 году?». Записаться

• 26 марта, 20:00. «Проектирование RAG систем». Записаться

Полный список бесплатных уроков марта смотрите в дайджесте.