Представьте, что в вашу команду взяли уверенного миддла. Но ему не дали доступ к трекеру, не показали базу знаний, а про архитектурные решения рассказали один раз на онбординге. Его изредка просят что‑нибудь погуглить, иногда поручают небольшую фичу в отрыве от контекста большой картины, а потом ругают за плохое понимание задачи и принятых в компании процессов.
Одни и те же ошибки я вижу и в стартапах, и в венчурных студиях, и у нетехнических соло‑фаундеров и, уж понятное дело, — в кровавом энтерпрайзе. Некоторые при этом уже называют себя модным «AI‑native» — хотя каждый их сотрудник по‑своему работает с единственным агентом, а обмен знаниями если происходит, то по чьей‑то частной инициативе в личном разговоре.
Разработчикам покупают Claude Code или Codex и предлагают играться дальше самим. Руководство слышало, что агенты ускоряют разработку — инструмент выдан, галочка стоит. Но скорость доставки почему‑то не изменилась.
А не изменилась она потому, что «автоматизировали» только один узел — система, внутри которой он работает, осталась без изменений. Код теперь генерируется со скоростью инференса, а спринт спланирован как раньше.
Штайнбергер в статье Shipping at Inference‑Speed описывает процесс, в котором его производительность упирается во время инференса и в сложные инженерные решения. Он запускает несколько задач параллельно, ведет документацию по подсистемам, дает агентам выполнять команды и проверять за собой результат.
Он — отличный пример того, чего добивается опытный соло‑разработчик, перестроивший под агентов всю личную среду. Но в той же статье есть важная оговорка: часть его практик в большой команде не полетит.
У одного разработчика с поставленной задачей, скорость инференса действительно становится главным ограничением. А у команды целиком это ограничение — процессы, которые генерируют эти задачи.
Когда в доагентскую эпоху я рассказывал о подходах для ускорения своей работы с помощью нейронок, я часто слышал:
А как же хайлоад?
в контексте применения этих подходов в больших системах — и не понимал, как размер системы может мешать поручать нейронке определенные задачи. Потом дошло: люди представляли себе ровно один сценарий применения моделей. Засунуть в контекст всю кодовую базу, попросить модель вести себя как сеньор и ждать, что все правильно спроектируется и заработает само, волшебным чудом, а потом разочарованно вздыхать.
Но так не работает ни модель, ни человек.
Человек, хорошо знающий проект, держит в голове маршруты: он знает, где что находится, где лежит контракт, кого спросить, если контракт молчит. Агенту нужно ровно то же самое.
Этот маршрут выглядит примерно так:
намерение или задача ↓ критерии приемки и границы риска ↓ маршрутизация к нужному контексту ↓ план для нетривиального изменения ↓ изолированная реализация ↓ обязательные локальные проверки ↓ независимое ревью и CI ↓ staging и проверка поведения ↓ контролируемая доставка ↓ телеметрия, выводы и обновление документации
Убирать человека из каждого узла не требуется. У каждого участка должен быть явный вход, выход, владелец и условие перехода. Где риск низкий — переход автоматический. Где высока цена ошибки — нужно подтверждение человека. Агент исполняет разрешенную ему часть процесса и переносит проверяемый результат на следующий гейт.
Возьмем условный пример. Команда добавляет идемпотентность в создание платежа. В задаче записано проверяемое обещание: два запроса с одним ключом создают одну операцию. Корневая инструкция отправляет агента к контракту API, ADR по платежам и правилам миграций. Фича‑план перечисляет затронутые компоненты, состояние при частичном сбое и способ отката. Агент меняет код в изолированном окружении и прогоняет happy path вместе с повторным запросом, параллельными запросами, падением после записи в базу и повторным запуском миграции. Второй агент или человек получает исходное обещание, diff и результаты проверок. CI заново исполняет обязательный профиль. На staging сценарий гоняется на синтетических данных. После успешной проверки человек принимает результат и одобряет доставку собранного артефакта в production.
Модель здесь пишет код, а надежность обеспечивается процессом вокруг этого: заранее заданные критерии, нужный контекст, изолированная реализация, независимое ревью, повторные проверки и человеческое решение о доставке.
Дальше — из чего такой маршрут собирается.
Нужна единая точка входа вместо энциклопедии в одном промпте
В корне проекта нужен короткий файл, который агент читает перед работой. У Codex это AGENTS.md.
Документация Anthropic говорит о том, что Claude не читает Agents.md, и ей нужен выделенный Claude.md, но по моим наблюдениям — еще как читает, если нет альтернативного файла. К тому же, AGENTS.md можно указать как явную точку входа в начальной инструкции или в том корневом файле Claude, если нужно; дублировать и поддерживать отдельный Claude.md с идентичным содержанием нет смысла.
Задача корневого файла — маршрутизация. Внутри достаточно описать назначение проекта и его границы, команды запуска и базовой проверки, карту документации, правила выбора тестового профиля, действия с обязательным подтверждением и определение готового результата.
Выглядеть это может примерно так:
# Working agreements - Read `docs/contracts/` and `docs/testing/api.md` before changing the API. - Follow `docs/workflows/migrations.md` for migrations. - Start non-trivial tasks with a plan in `docs/plans/active/`. - Update user-facing docs after any behavior change. - A task is done when the check commands and their output are attached. - Prepare report and instructions for an operator.
Правило выбирается по типу изменения. Минорный CSS‑твик обходится линтером и компонентными тестами, платежный контракт тянет за собой полный профиль тестирования.
Это полезно и людям — новый сотрудник открывает тот же репозиторий, идет по тем же маршрутам и быстрее понимает, как здесь принято работать. Хорошая документация для агента почти всегда оказывается хорошей документацией для команды. А от неявных договоренностей одинаково страдают все.
Документация живет в репозитории
Документация для агентов — это общий, версионируемый и поддерживаемый репозиторий знаний о производстве продукта. Если агентская документация в вашей команде это забота отдельных разработчиков и каждого для себя — ни о какой стандартизации разработки и контроля качества просто не идет речи.
Самое занятное, видеть отсутствие таких стандартов в студиях разработки, которые называют себя AI‑first — производство продуктов поставлено на поток, а стандартизация процессов и стека сделана в лучшем случае по советам ChatGPT.
Сейчас принято ругать нетехнических людей, которые добрались, наконец, до возможности реализовывать свои идеи без знания компьютерной науки, за техническое качество их продуктов, но такие команды и студии вносят не меньший вклад в массовую слопогенерацию — если не больший. Потому что штамповать в несколько рук слабоподдерживаемые проекты можно куда быстрее.
Когда агентская документация стандартизирована для команд, начинают меняться и процессы внутри: знания перестают всплывать в случайных ссылках или внутренних воркшопах; изменения кода и документации идут через единый поток ревью, а новый разработчик получает актуальную доку вместе с доступом к проекту. Агент видит статус и область действия рядом с кодом и ведет себя одинаково на каждой отдельной рабочей машине.
Минимальная структура проектной документации может выглядеть так:
AGENTS.md docs/ architecture/ # subsystems and data flows contracts/ # APIs, schemas, external commitments decisions/ # ADRs and the reasoning behind them plans/ active/ # in-flight changes completed/ # finished plans with outcomes research/ # verified research notes testing/ # test profiles and selection criteria workflows/ # repeatable processes operations/ # runbooks, diagnostics, rollback
Конкретные названия каталогов могут отличаться — важны назначение документов и понятная структура связей между ними.
В своих и клиентских проектах, я, кроме общей документации, выделяю несколько основных типов документов, специфичных для работы с агентом.
Мастер‑план
Мастер‑план фиксирует направление проекта: цель, границы, архитектурные принципы, крупные этапы и фазы, внешние зависимости, основные риски и то, что сознательно не делается.
Этот документ обычно создается в новом проекте, который стартует с чистого листа и ресерча. Когда нужные данные собраны, стали понятны границы и рамки, сформировался конечный вид — хотя бы на текущем этапе понимания проекта — мастер‑план собирает все это в себе и дает основу для быстрого создания следующих документов.
Искать и изучать информацию для основного направления проекта лучше в рамках одной сессии и в рамках той же сессии — готовить мастер‑план. Если исследование, которое вы проводите, не влезает в контекст сессии или начинает его размывать — сохраняйте промежуточные результаты в отдельных документах — позже их можно использовать как бульонные кубики контекста, для заваривания общей картины в мастер‑плане.
Фича‑план
Фича‑план описывает конкретное изменение: текущее и желаемое поведение, затронутые компоненты, инварианты, миграцию, отказные сценарии и критерии готовности.
Такой план обычно — это описание процесса, который должен привести к определенному результату. Допустимо делать этот документ объемным и больше, чем на одну фичу. При большом объеме, он делится на фазы — каждая со своими условиями для старта и своими критериями выполнения и приемки; но все они работают в одну сторону: создать новую конечную функциональность, сделать крупный рефакторинг или стабилизировать работу части системы.
ADR
Или Architecture Decision Record — хранит причину решения, рассмотренные варианты и последствия. ADR нужен, чтобы объяснить и зафиксировать решение, принятое на ходу, например с появлением новых данных. Оно может отличаться от того, что написано в конкретном фича‑плане, или отклоняться от общей канвы мастер‑плана — ADR фиксирует, зачем, почему, при каких условиях это было решено и почему это важно. Это одновременно и жесткая фиксация знаний и один из инструментов гибкости процесса.
У документа должен быть жизненный цикл
Папка docs/ сама по себе ничего не стандартизирует и без процесса она быстро превращается в свалку MD‑файлов.
У каждого важного документа должны быть хотя бы область действия, статус, владелец, дата последней проверки и условие, при котором документ пора пересматривать. Статусов достаточно четырех: черновик, действует, заменен, архивирован.
Обновление документации входит в определение готовности. Если изменение поменяло публичный контракт, обязательную команду, архитектурный инвариант, операционный процесс — задача не закончена, пока соответствующий документ не обновлен.
При этом описывать все подряд не нужно и вредно. Структура каталогов, список зависимостей и сигнатуры функций агент прочитает из репозитория сам. Документировать нужно то, чего из кода не понять:
намерение;
ограничения;
причины решений;
опасные исключения;
критерии приемки;
известные режимы работы и условия их применения.
Конфликт источников тоже разрешается явно: тесты показывают зафиксированное ожидаемое поведение, код показывает фактическую реализацию, ADR объясняет архитектурное намерение, активный план описывает еще не завершенное изменение. Если они разошлись, агент останавливается, фиксирует конфликт и выносит его владельцу — машина не должна иметь возможность просто взять и выбрать самую удобную версию истины.
Механические проверки переносятся в CI: битые ссылки, отсутствующие обязательные поля, неизвестные владельцы, завершенный план без итогового статуса. Смысловую актуальность документа подтверждает тот же владелец, который отвечает за соответствующее поведение системы.
Куда складывать знания, чтобы переезд не стоил недель работы
Не в скиллы. Вокруг агентских скиллов сейчас много мистики, хотя по сути это просто упаковка повторяемого процесса: инструкции, вспомогательные материалы и иногда скрипты. OpenAI описывает skills как формат переиспользуемых рабочих процессов с прогрессивной загрузкой контекста.
Скиллы хорошо работают, когда задача действительно повторяется: починить определенный класс падений пайплайна, подготовить миграцию по принятому шаблону, собрать релизные заметки. Но складывать в них всю память компании бессмысленно.
Во‑первых, конкретная агентская система может изменить формат, правила загрузки или поведение после очередного обновления. Во‑вторых, поставщик может стать недоступен конкретной команде, региону или аккаунту.
Вот здесь автор описывает всю боль переезда со скиллов из Claude Code на Codex, после того как Anthropic начали блокировать аккаунты по региону более внимательно.
Главная проблема была в скиллах. За последние несколько месяцев очень глубоко оброс скиллами для внутренних систем, некоторые дублировали друг друга.
Переделка скиллов заняла два с половиной дня. Сложность была в том, что для некоторых внутренних систем идеальных скиллов пока не существует. Например, для нашей системы контроля версий есть три скилла с разными сильными и слабыми сторонами. И с тремя разными авторами.
со временем весь зоопарк скиллов превращается в помойку и нужно убираться.
Последняя цитата у меня особенно откликается, потому что именно такие ощущения вызывает документирование скиллов. Кажется, что правильней документировать подходы, а не конкретные навыки.
А скилл‑инструкция, которая хорошо исполнялась одной моделью, не обязана так же хорошо исполняться другой. Коммерческие модели обновляются, старые версии со временем уходят — то, что стабильно работало с GPT-5.5 в 5.6 начинает сбоить или вообще игнорируется.
Поэтому тут я выделяю слои документирования:
знания о проекте, инварианты и обязательные политики живут рядом с кодом;
повторяемый рабочий процесс может оформляться скиллом;
критические и детерминированные действия реализуются скриптом или проверкой;
адаптер конкретного агента только подключает общий источник и его инструменты.
Если при переезде с Claude Code на Codex приходится вручную переносить сотни правил — это не хороший повод заодно почистить старое, а скорее признак того, что знание слишком тесно приросло к одному рантайму.
И отдельный скилл тоже нужно тестировать. Задачи, на которых он должен работать, задачи, на которых не должен, ожидаемые входы и выходы, запрещенные действия. Перед сменой модели или версии агентской обвязки эти проверки прогоняются заново. То, что новая модель «умнее», может наоборот вылезти боком.
Куда складывать знания, чтобы переезд не стоил недель работы
При старте проекта в незнакомой области разумно отдать сильной модели исследование и ассистирование в проектировании, а более дешевым и быстрым — поручить хорошо специфицированную реализацию.
«Умные» пишут документацию, «глупые» — занимаются имплементацией.
Оценка, кому что поручить, должна учитывать:
цену ошибки;
объем и неоднородность контекста;
обратимость изменения;
качество автоматической проверки;
сложность архитектурного решения.
Простая модель отлично реализует рутинный адаптер по точному контракту. Сильная понадобится для запутанного рефакторинга или качественного ревью.
Инкапсулировать окружение
Когда агент может запускать команды, устанавливать зависимости и менять файлы, воспроизводимое окружение должно стать частью контракта.
Многие команды не стандартизируют это вообще. Проект запускается на хост‑машине, вне контейнера с прописанной конфигурацией — и ломается уже на этапе сборки, потому что локальные версии библиотек не совпадают. Теперь представьте, что разработчик недолго думая поручает это исправить агенту без рельсов, тот адаптирует проект под его локальную версию библиотеки и этот «фикс» вместе с фичей уезжает на ревью. Как все будут счастливы представлять не нужно: время тратится на исправление глупостей, а виновник, естественно, — тупой агент, который не шарит в разработке.
Контейнеры необходимы, потому что дают изоляцию, переносимость и так важный для стандартизации процессов — повторяемый результат.
среда поднимается документированной командой или набором команд;
версии зависимостей зафиксированы;
внешние сервисы имеют воспроизводимые тестовые замены;
состояние безопасно создается и очищается;
доступные каталоги и сетевые направления ограничены;
тот же набор проверок выполняется локально и в CI;
неудачный запуск не влияет на машину разработчика.
Где‑то для этого нужен compose с базой, очередью и примонтированным исходным кодом, чтобы изменения подхватывались без пересборки. Где‑то хватит легкого devcontainer. Где‑то понадобится отдельный удаленный sandbox.
Контейнер при этом — не волшебная пилюля сам по себе. Неправильно заданные границы безопасности — смонтированные каталоги, привилегированный режим, сокет Docker или лишний сетевой доступ — снова открывают агенту хост или внутреннюю инфраструктуру, и за этим тоже нужно следить.
Тесты проверяют обещание задачи
Агент, который написал код и отчитался о готовности, не доказал что задача выполнена на самом деле. Доказательством служат пройденные проверки по матрице соответствия и тесты, сделанные и написанные еще на этапе планирования фазы.
Я в своей практике и документации выделяю 3 положения строгости проверок:
Строгая проверка с полным прогоном тестов — перед мержем или доставкой.
Локальные и интеграционные проверки самой фичи и ближайшей области изменений, без полного прогона — убедиться, что реализация работает и не ломает непосредственно затронутые части системы.
Полный YOLO — тот самый режим «вайб‑кода», допустимый в мелких проектах, экспериментах и ранних этапах разработки — когда кода еще слишком мало чтобы ставить все на рельсы и можно просто гнать фичу за фичей, выкидывать и переписывать целые пласты проекта.
Но даже хороший и надежный прогон тестов и матриц — не стопроцентная гарантия что: а) все сделано; б) все сделано правильно. Чтобы работа считалась готовой к приемке человеком, нужно второе мнение.
Кросс‑проверка
Шутка гласит: если в инструкциях Claude Code упомянуть, что результат будет проверять Codex, дефолтное качество самопроверок и, соответственно, выдачи неиллюзорно возрастет. Насколько хорошо это работает на самом деле, сказать сложно. Но принцип второго мнения — одна из самых полезных практик, особенно для ресурсоемких задач.
Рабочая кросс‑проверка обычно выглядит так:
Агент‑имплементатор, более простая и дешевая модель, получает задачу, контекст и право изменить ограниченную заданную область.
Проверяющий получает исходные требования, код и результаты тестов. Репорт первого агента он не видит.
Он делает, по сути, ревью, и ищет конкретные классы проблем: пропущенные требования, хаки, ошибки безопасности, отсутствие тестов, несогласованные документы.
Замечания формируются в фикс‑план.
Фикс‑план передается имплементатору.
Иногда бывает нужна еще одна итерация проверок‑фиксов и задача выполняется. Но бывает и так, что даже после повторного фикс‑плана слабая модель не справляется с задачей; в таком случае, уместно отдать доделки и «причесывания» той же «умной» модели, что делала ревью — ей остается не так много и расход драгоценных токенов будет не таким большим, как на полную имплементацию задачи той же умной моделью. Получаются такие, буквально сеньорско‑джуниорские отношения.
Для рискованных изменений полезно кросс‑планирование: одна «умная» модель составляет план, другая — пытается его сломать до начала реализации. Выводы из этого делает, естественно, человек, и решение о том, как конечный план будет выглядеть остается за человеком.
Когда нельзя пускать ИИ на прод
Короткий ответ: всегда (нельзя). Прямой доступ с правом менять работающую систему исключен.
Все нужные принципы придуманы до ИИ: минимальные привилегии, разделение обязанностей, аудит, воспроизводимые артефакты и откат никуда не делись.
Практические границы такие:
агент не получает универсальные production‑ключи;
агент не подключается к production‑хосту по SSH;
агент не обходит CI/CD и не доставляет локально собранный артефакт;
агент не меняет инфраструктуру, секреты и права по собственному решению, даже на dev или стейджинге.
Видеть данные о production агенту при этом можно. Он может помочь с диагностикой через уже существующую инфраструктуру мониторинга. Строить магический мониторинг на агенте, который свободно ходит по проду и решает, что там происходит — идея так себе.
Агент может подготовить изменение, открыть pull request, собрать план миграции или даже инициировать пайплайн, если инициирование не дает права обойти гейты к продакшену. Решение о применении высокорискового изменения остается за человеком в отдельном контролируемом контуре.
Дать порезвиться агенту можно в других окружениях. Staging принимает уже проверенного кандидата в релиз, и там его видно почти живьем. Свалкой для любого результата агента staging при этом быть не должен: для этого есть dev.
Как понять, что автоматизация действительно работает
Количество сгенерированных строк, потраченных токенов, закрытых агентом подзадач и открытых pull request — сами по себе не показатель ценности. Быстрый генератор наращивает очередь на ревью вместе с объемом мусора в ней.
Примером — в Ghostty очередь на ревью в какой‑то момент раздулась настолько, что Митчелл Хашимото в начале года переписал правила приема изменений. По его словам, раньше даже плохой pull request требовал от автора времени и усилий, а агенты убрали этот естественный ограничитель. В результате плохих issues и PR стало примерно в десять раз больше. Теперь случайные AI‑сгенерированные pull request закрывают сразу, а тех, кто продолжает закидывать проект слопом, блокируют насовсем.
Если автоматизировать отдельный узел разработки, разрозненно выдав разработчикам доступ к системам для генерации кода, это ускорит только прохождение задач через данный узел — и увеличит время его простоя. То, с какой скоростью задачи генерируются, как они двигают проект и работу вперед — это то, что нужно покрывать метриками. Сколько времени проходит от готовой задачи до production, сколько она ждет на отдельных гейтах, как часто возвращается на доработку и сколько изменений после доставки требуют фикса или отката.
Вся система вокруг разработки должна двигаться в том же темпе. Если ваши задачи планируются раз в неделю или две, не имеет значения как быстро они выполнятся — сама процедура планирования ограничивает возможный объем доставки.
Качество задач, тоже важный фактор. Если все работает быстрее на всех узлах, но проект все равно буксует на роадмапе, возможно, вы зарылись в оптимизации или что‑то в этом пайплайне сломалось и вся скорость уходит не на продвижение вперед, а на остановку протечек и залатывание дыр.
Если разработчики стали генерировать код быстрее, задачи на доске летят одна за другой из колонки в колонку, а время поставки не изменилось — вы нашли узкое место процесса. Его и надо автоматизировать — либо разбираться, что там сломалось.
С чего начать
Платформа агентской оркестрации на все случаи жизни на первом этапе не нужна. Достаточно взять один повторяемый тип изменения и провести его по полному маршруту.
В начале можно задать себе вопросы:
Задокументировали ли мы критические инструкции и положения?
Эта документация — доступна всем в едином репозитории?
Работает ли эта документация вне зависимости от того, какой агент по ней работает?
Потом взять один небольшой подпроект, или придумать его внутри, или выделить тип задач, который выглядит оптимизируемей остальных — и убедиться, что на все вопросы ответом будет уверенное «да».
Если что‑то существует только в виде просьбы в промпте — это не автоматизировано. Процесс, который знает один разработчик — не стандартизирован. Если что‑то пошло не так, и нужен перенос документации на специфику другого агента — поддерживаемой документации в проекте пока нет.
Claude Code, Codex и другие агенты действительно радикально ускоряют разработку. Но какой ценой — зависит от того, насколько ответсвенно вы их внедряете. Купленная лицензия при этом меняет ровно один этап процесса, а производственную систему нужно перестраивать руками.
Автоматизация начинается там, где каждая задача получает воспроизводимый и проверяемый маршрут. Агент понимает намерение и находит ровно нужный контекст. Работает в ограниченном окружении, результат доказывает тестами и проходит независимые гейты. Расширить свои полномочия самовольно он не может. Полученное знание возвращается в общий репозиторий, поэтому следующий разработчик и следующий агент начинают с ненулевой отметки.
Тогда ускоряется способность команды безопасно поставлять изменения. Выработка отдельного разработчика тут только один из показателей.
Пока этого нет, каких бы агентов вы ни давали вашей команде, вы автоматизировали генерацию кода – но не разработку.
