Рефакторинг легаси-кода с Codex: разведка репозитория, тесты и режимы одобрения

Коротко (TL;DR)

• Легаси ломает агента не «сложностью», а четырьмя измеримыми ограничениями: окно контекста 272 000 токенов, выключенная в песочнице сеть, требование git-репозитория и предел инструкций 32 KiB. Ни одно из них не лечится формулировкой промпта.
• Порядок работы обратный привычному: сначала разведка в режиме чтения, потом фиксация текущего поведения тестами, и только потом правки — этого требует и официальная методика OpenAI.
• Главный страх снимается флагом, а не доверием: в замере 13.08.2026 агент не смог записать ни байта в .git даже в режиме правок, а вот сборка легаси падает по умолчанию — сеть в песочнице выключена, curl возвращает ошибку резолва имени.
• У Codex есть задокументированная системная ошибка именно на рефакторинге: он правит вызывающую сторону раньше вызываемой и оставляет проект несобираемым посреди работы.
• Рефакторинг и миграция — два разных сценария с разными стартовыми промптами, и смешивать их в одну задачу официальная документация прямо запрещает.

Всё, что ниже, проверено на codex-cli 0.147.0 (13 августа 2026): часть — по официальной документации, часть — собственными запусками, вывод которых приведён дословно.

Что ломает агента на легаси: четыре ограничения, а не качество модели

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

Отсюда следует весь порядок работы. Нельзя «попросить починить» — сначала надо уместить задачу в окно, поднять сборку, дать агенту правила и только потом менять код. Именно так устроена и официальная методика: OpenAI разбирает модернизацию легаси в отдельном кукбуке «Modernizing your Codebase with Codex», где на весь пилотный поток приходится пять фаз и четыре документа, а генерация кода стоит только на четвёртой.

Если вы ещё не работали с этим агентом, начните с разбора OpenAI Codex — здесь дальше предполагается, что базовый цикл вам знаком.

BYBIT EARNЗаставь крипту работатьПроценты на USDT и BTC без блокировки — деньги остаются под рукой.Разместить

Разведка чужого репозитория: read-only режим и карта кода в JSON

Официальная страница сценария рефакторинга начинается с требования, которое почти все пропускают: «ask Codex to map the area before editing» — сначала картируем область, потом правим. Практически это означает запуск, в котором агент физически не может ничего изменить.

Nutanix заменила Copilot и Claude кластером за $20 млн: окупаемость — год

OpenAI раскрыла масштаб взлома Hugging Face: 1200 агентов и 12 дней без обнаружения

Codex и GitHub в работе команды: права, ветки, ревью и конфликты

Perplexity Portable Computer: агент считает на вашей RTX, счёт за токены — ноль

Ковенанты биткоина: пять лет после Taproot и 0% сигнализации за OP_CTV

Документация утверждает это прямо: «By default, codex exec runs in a read-only sandbox». Я проверил запуском без единого флага песочницы — шапка сессии 13.08.2026:

$ codex exec "list the files, do not change anything"
OpenAI Codex v0.147.0
model: gpt-5.6-terra
approval: never
sandbox: read-only

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

Разведочный запуск в самом простом виде официальная документация показывает так:

codex exec "summarize the repository structure and list the top 5 risky areas"

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

codex exec --sandbox read-only \
  "Составь карту репозитория: точки входа, модули без тестов, мёртвые куски, внешние зависимости" \
  --output-schema ./recon.schema.json -o ./recon.json

На выходе получается структура с фиксированными полями, которую можно сравнивать между прогонами и класть в тикеты. Если нужен не финальный ответ, а весь ход работы, тот же прогон запускается с --json — тогда stdout превращается в поток событий JSONL (thread.started, item.*, turn.completed с расходом токенов).

Отдельный случай — легаси вне git. Это не редкость: архив с исходниками, папка с сервера, код, который никогда не заводили в репозиторий. Codex такой запуск останавливает:

BYBIT EARNЗаставь крипту работатьПроценты на USDT и BTC без блокировки — деньги остаются под рукой.Разместить

$ codex exec --sandbox read-only "list the files"
Not inside a trusted directory and --skip-git-repo-check was not specified.

Требование намеренное: git — это способ откатить всё, что агент сделает. Обойти его можно флагом --skip-git-repo-check, и в моём замере после этого прогон отработал штатно. Но правильный порядок другой: сначала git init и первый коммит, и только потом агент. Иначе вы теряете единственный дешёвый механизм отката.

AGENTS.md для легаси-репозитория: предел 32 KiB и вложенные override

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

Механика сборки инструкций такая: сначала глобальный файл из домашнего каталога Codex, затем файлы от корня проекта вниз до текущей папки, не более одного на каталог, и файлы ближе к рабочей директории перекрывают ранние. В том же каталоге AGENTS.override.md имеет приоритет над AGENTS.md. Подробный разбор самого файла — в уроке про AGENTS.md; здесь важны три вещи, которые всплывают именно на старом коде.

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

Второе — вложенные override под каждый модуль. У легаси-монорепозитория обычно нет единой команды сборки: один сервис собирается через make, другой через древний скрипт, третий не собирается вовсе. Документация показывает ровно этот приём — свой файл в каталоге модуля:

# services/payments/AGENTS.override.md

## Правила сервиса платежей
- Тесты запускать только `make test-payments`, общий `npm test` здесь не работает.
- Файлы в legacy/ не трогать без явной просьбы: они собираются отдельным пайплайном.

Третье — если в репозитории уже есть свой файл правил. Старые команды часто держат TEAM_GUIDE.md или CONTRIBUTING.md с реальными договорённостями. Их не нужно переписывать — достаточно добавить имя в список:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

Проверить, что агент действительно прочитал нужное, можно одной командой: codex --ask-for-approval never "Summarize the current instructions." — в ответе он перечислит загруженные правила в порядке приоритета.

ExecPlan: формат OpenAI для миграции, которая идёт часами

Для крупной миграции OpenAI предлагает не промпт, а документ — ExecPlan. Это живой проектный файл, по которому агент ведёт изменение неделями и к которому возвращается после каждой паузы. Термин произвольный: модель на нём не обучалась, его смысл вы задаёте сами в AGENTS.md.

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

• Progress — чекбоксы с отметками времени, честно отражающие текущее состояние;
• Surprises & Discoveries — что вскрылось по ходу, с короткими доказательствами (идеально — вывод тестов);
• Decision Log — каждое решение с обоснованием и датой;
• Outcomes & Retrospective — что получилось, что осталось, чему научились.

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

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

Migrate this codebase from JavaScript to TypeScript. Preserve existing behavior,
compile in strict mode without explicit `any` types, and make the full test suite pass.

Здесь видна правильная форма задачи для легаси: результат, ограничение («поведение сохранить») и проверка («весь набор тестов проходит»). Методологию разработки от спецификации мы отдельно не разбираем — она не привязана к конкретному агенту и разобрана в статье про spec-driven development.

Тесты-предохранители, когда тестов нет: парити-прогон двух версий

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

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

Порядок такой:

1. Зафиксировать текущее поведение. Не «правильное», а фактическое — вместе со странностями, округлениями и багами, на которые кто-то уже полагается. Официальный кукбук этот шаг не формулирует, но у практиков, разбиравших рефакторинг легаси с агентом, он сводится к одной просьбе: написать тесты на текущее поведение модуля и пока не трогать реализацию.
2. Описать, что считается совпадением. Какие выходы сравниваем: файлы, строки в таблицах, логи. Это отдельный пункт, потому что «результат совпал» на легаси почти всегда означает «совпал с точностью до формата даты и порядка строк».
3. Достроить парити-тест. Официальный промпт требует, чтобы тест вызывал и старый поток, и новую реализацию и сравнивал выходы по описанной стратегии.
4. Записать команды параллельного прогона. Упорядоченным списком: подготовить данные → прогнать старое → прогнать новое → сравнить, с точными путями и описанием того, как выглядит успех.

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

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

Песочница Codex на легаси: почему падает сборка и что защищено

Самый частый страх звучит так: «агент снесёт рабочий код». Самая частая реальная проблема звучит иначе: «у агента не собирается проект». Я замерил обе, прогнав команды под песочницей Codex на macOS 13.08.2026.

Дословный вывод, на котором построена таблица:

$ codex sandbox -c sandbox_mode="workspace-write" bash -lc 'echo z > .git/probe.txt || echo git_dir_BLOCKED'
git_dir_BLOCKED
bash: .git/probe.txt: Operation not permitted

$ codex sandbox -c sandbox_mode="workspace-write" bash -lc 'curl -sS -m 8 https://registry.npmjs.org/ -o /dev/null; echo curl_exit=$?'
curl: (6) Could not resolve host: registry.npmjs.org
curl_exit=6

Из этого следуют два практических вывода.

Историю репозитория агент не испортит. .git объявлен доступным только для чтения внутри записываемого корня, защита рекурсивная, и то же касается каталогов .agents и .codex. То есть «агент перепишет историю» — не тот риск, о котором стоит думать.

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

[sandbox_workspace_write]
network_access = true

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

Посмотреть, что именно запретит песочница вашему легаси-скрипту, можно заранее, прогнав его в тех же ограничениях: codex sandbox bash -lc "./build.sh". Здесь стоит предупредить о расхождении: документация показывает форму codex sandbox macos … с подкомандой платформы, но в 0.147.0 такой подкоманды нет — слово macos принимается за исполняемую команду, и запуск падает с execvp() of 'macos' failed. Рабочая форма — без имени платформы.

Режимы одобрения на рискованных правках: untrusted и авто-ревью

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

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

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

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

Массовые однотипные правки: codex exec, JSON-вывод и проверка пачки

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

Базовая форма с явными правами:

codex exec --sandbox workspace-write \
  "Замени вызовы устаревшего logger.log(...) на logger.info(...) во всём каталоге src/. \
   Поведение не менять, публичные сигнатуры не трогать, тесты не переписывать."

Двухшаговый сценарий, когда после прогона надо что-то поправить, держится на resume:

codex exec "прогони линтер и опиши, какие правила падают после замены"
codex exec resume --last "почини только те падения, которые вызваны заменой, остальное не трогай"

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

codex review --uncommitted          # всё несохранённое, включая новые файлы
codex review --base main            # ветка против базовой
codex review --commit <SHA>         # ровно один коммит

В интерактивной сессии то же самое делает /review. При желании ревью можно гонять на другой модели, чем сама работа, — за это отвечает ключ review_model в конфигурации.

Важное предупреждение для тех, у кого уже есть скрипты автоматизации. Флаг --full-auto, который годами кочует по чужим примерам, в версии 0.147.0 не работает:

$ codex exec --full-auto "say ok"
error: unexpected argument '--full-auto' found

Я проверил это с контролем метода — рядом прогнал заведомо несуществующий флаг, и ответ оказался идентичным, то есть флаг именно отсутствует, а не «устарел с предупреждением». При этом официальная страница на ту же дату утверждает обратное: что флаг сохранён как совместимый и печатает предупреждение. Если ваш пайплайн миграции построен на --full-auto, после обновления CLI он остановится; замена — явный --sandbox workspace-write.

Типовые миграции легаси: версия языка, фреймворк, сборка, типизация

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

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

Миграция меняет стек. Здесь промпт требует другого: инвентаризовать легаси-допущения (роутинг, модели данных, авторизация, конфигурация, сборка, тесты, деплой, внешние контракты), составить карту соответствий старого и нового, назвать то, чему прямого соответствия нет, и предложить инкрементальный план с прослойками совместимости вместо большого переписывания. Стратегия выбирается из известных: прослойка совместимости, перенос модуль за модулем, branch-by-abstraction или strangler — замещение по одной границе за раз.

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

Большая миграция по кускам: облачные задачи и worktree

Когда миграция не помещается в один заход, её режут. Здесь есть развилка, которую стоит понимать буквально.

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

Параллелить запись — через отдельные checkout’ы. Механизм для этого — worktree, второй рабочий каталог того же репозитория. Codex создаёт их в своём домашнем каталоге в состоянии detached HEAD, чтобы не засорять ветки. Здесь прячется мелочь, которая решает половину проблем со сборкой старого проекта: файл .worktreeinclude в корне репозитория перечисляет игнорируемые git-ом локальные файлы, которые нужно скопировать в новый worktree. Без него легаси, зависящий от локального конфига или вендоренных библиотек, в свежем checkout’е просто не поднимется.

Резать на облачные задачи имеет смысл, когда кусок самодостаточен и заканчивается пулл-реквестом. Устройство облачной задачи стоит учитывать при планировании: она двухфазная — на фазе подготовки есть сеть и ставятся зависимости, а фаза работы агента по умолчанию идёт офлайн. И отдельно: секреты окружения доступны только на подготовительной фазе и удаляются до старта агента, так что схема «положу токен в секреты и агент им воспользуется» в облаке не работает. Подробнее механика разобрана в уроке про облачные задачи Codex.

Практический размер куска — тот, который заканчивается зелёной проверкой: парити-прогоном на общих данных или чистым codex review --base по ветке этого куска. Если веха не может закончиться ни тем, ни другим, это не веха, а просто много изменений — и на легаси такой кусок разбирать будет некому.

Где Codex системно ошибается на легаси: порядок правок и issue #21920

У агента есть ошибка, которая на рефакторинге воспроизводится систематически, и она зафиксирована в репозитории самого продукта — issue #21920 (открыт 09.05.2026, метки enhancement и model-behavior).

Суть: Codex правит вызывающую сторону раньше вызываемой. Разбирая модуль на несколько, он сначала добавит объявление mod foo, и только потом создаст foo.rs. Автор описывает последствие прямо: проект «unable to be compiled, tested» на протяжении длинных отрезков работы, и называет это систематическим наблюдением по множеству рефакторингов.

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

Лечится это тем же способом, который предлагает автор issue, — инструкцией:

## Порядок правок
- Сначала определяй, потом вызывай: новый файл/функция появляется РАНЬШЕ ссылки на неё.
- Дерево должно собираться после каждого шага. Если шаг невозможно сделать
  без временной поломки сборки — сначала опиши план, не начинай правку.

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

Для повторяющихся сценариев наработанную инструкцию удобно оформить как скилл — переиспользуемый набор правил, который подключается к любому репозиторию. Материалов на русском по этой теме почти нет, а англоязычные ищутся предсказуемо: сам сценарий — по запросу codex refactoring, готовые заготовки правил — по codex refactoring skill, формулировки задач — по codex refactoring prompt. Оговорка та же, что и с любым чужим шаблоном: перед применением к своему легаси его надо прочитать целиком — скилл может тянуть за собой правила, которые вашему проекту не подходят.

Окно контекста 272 000 токенов: сколько легаси помещается за раз

Цифра, из которой следует вся стратегия нарезки: на 13 августа 2026 окно контекста у всех моделей Codex одинаковое — 272 000 токенов. Это видно в метаданных моделей в репозитории продукта: одно и то же значение у gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna и у более старых.

Причём окно не росло, а сжалось: PR #33972, влитый 18 июля 2026, поменял значение с 372 000 на 272 000.

Сколько это в коде? Я измерил на 12 реальных файлах проекта токенизатором o200k_base — тем же, что используют модели OpenAI: 296 433 символа, 5 919 строк, 86 997 токенов. Отсюда 3,41 символа на токен и 14,7 токена на строку.

• ≈18 500 строк — теоретический потолок, если бы окно занимал только код;
• ≈13 000 строк — реалистичная оценка, если считать, что около 30% окна уходит на системный промпт, инструкции, схемы инструментов и сам диалог.

Плотность зависит от языка: на многословных легаси-языках вроде COBOL, Java или PL/SQL строк поместится меньше, на плотных вроде Python или Go — больше. Но порядок величины ясен: средний легаси-модуль в окно влезает, монолит на сотни тысяч строк — нет. Работать приходится подсистемами, а карту целого держать в документах, а не в контексте. Как расходуется окно и что делать, когда оно кончается, разобрано в уроке про лимиты и окно контекста Codex.

Отдельно про выбор модели под разные части миграции.

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

Что устареет первым. Версии и модели в этой теме живут месяцами: gpt-5.4 и gpt-5.4-mini уходят из Codex 31 августа 2026, а gpt-5.2 и gpt-5.3-codex уже сняты — при том, что официальный кукбук по планам на 13.08.2026 всё ещё рекомендует gpt-5.2-codex. Поэтому перед переносом чужого конфига миграции проверьте актуальность у себя: codex --version, codex exec --help и /status в сессии покажут реальную картину быстрее любого гайда.

Частые вопросы

Можно ли доверить Codex рефакторинг легаси, если тестов в проекте нет?

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

Почему сборка старого проекта падает под агентом, хотя руками собирается?

Потому что в песочнице выключена сеть. В замере 13.08.2026 curl внутри песочницы завершился с кодом 6 и сообщением «Could not resolve host» — то есть отказ происходит на резолве имени, ещё до скачивания. Любая установка зависимостей падает по этой причине. Лечится ключом network_access = true в секции sandbox_workspace_write либо тем, что зависимости ставятся заранее вручную.

Что делать, если легаси-проект вообще не под системой контроля версий?

Завести репозиторий до первого запуска агента. Codex отказывается работать вне git — прогон останавливается сообщением «Not inside a trusted directory». Формально это обходится флагом --skip-git-repo-check, и он работает, но так вы лишаетесь единственного дешёвого способа откатить правки. Минимально достаточно git init и одного коммита с исходным состоянием.

Сколько кода Codex видит за один раз?

Окно контекста на 13 августа 2026 — 272 000 токенов, одинаково у всех моделей. По моему замеру на реальных файлах это около 18 500 строк кода в теории и порядка 13 000 на практике, когда часть окна занята инструкциями и диалогом. Средний модуль помещается целиком, крупный монолит — нет, поэтому работа идёт подсистемами.

Чем миграция отличается от рефакторинга в терминах Codex?

Это два разных сценария с разными стартовыми промптами. Рефакторинг меняет форму кода на месте и обязан сохранять поведение и публичные интерфейсы; всё, что тянет за собой смену фреймворка или зависимости, документация требует выносить в отдельную задачу. Миграция меняет стек и требует инвентаризации допущений, карты соответствий, плана с контрольными точками и видимого пути отката.

Нужен ли AGENTS.md, если я в чужом репозитории разово?

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