Почему Codex ломается на запуске: как один раз описать рабочую среду проекта
Иногда Codex ошибается не потому, что плохо понял задачу. Он ошибается раньше: не знает, как правильно запустить проект. В одном чате агент пробует npm run dev, в другом ищет pnpm, в третьем забывает собрать зависимости, в четвертом запускает тесты не той командой. Снаружи это выглядит как слабый ИИ. На деле часто сломана рабочая среда.
В официальной документации OpenAI по local environments Codex app описывает настройку локальной среды через settings. Конфигурация хранится внутри папки .codex в корне проекта, ее можно положить в Git-репозиторий и разделять с командой. Там же описаны setup scripts и actions: сценарии подготовки среды, запуска приложения, тестов и других типовых действий.
Для владельца проекта это важнее, чем кажется. Рабочая среда - это инструкция "как здесь вообще работать". Если ее нет, Codex вынужден гадать.
Среда - это не техническая мелочь
У проекта почти всегда есть ритуал запуска. Установить зависимости. Собрать фронтенд. Поднять сервер. Применить миграции. Запустить тесты. Проверить страницу. Открыть лог. Иногда это знают только разработчики, иногда это спрятано в истории терминала, иногда передается устно.
Для человека это привычка. Для Codex это неопределенность.
Хороший local environment отвечает на четыре вопроса:
| Вопрос | Что нужно зафиксировать |
|---|---|
| Как подготовить проект | команды установки, сборки, генерации файлов |
| Как запустить работу | dev server, worker, тестовый режим, preview |
| Как проверить результат | тесты, lint, smoke-check, browser check |
| Где остановиться | секреты, production-действия, команды с риском |
Когда эти ответы есть, Codex работает не с догадками, а с процедурой.
Setup script: подготовка без шаманства
В документации Codex setup script описан как место, где можно выполнить команды, необходимые для настройки среды: установить зависимости, запустить сборку или другой подготовительный процесс. Это не значит, что туда нужно сложить все подряд. Setup script должен делать проект пригодным к работе, но не принимать бизнес-решения.
Пример плохой идеи: "настрой среду и сразу задеплой". В такой команде смешаны подготовка, изменение и выпуск наружу.
Пример хорошей идеи:
Подготовь среду: установи зависимости, проверь, что проект собирается, но не запускай публикацию и не меняй production. Если команда требует секретов, остановись и напиши, чего не хватает.
Так Codex получает рабочую дорогу, но не получает лишнюю власть.
Actions: быстрые кнопки для повторяемых проверок
В Codex app actions нужны для общих задач вроде запуска dev server или тестов. Они появляются в верхней панели приложения и выполняются во встроенном терминале. Для не-программиста это можно перевести так: вместо того чтобы каждый раз просить "проверь как-нибудь", вы даете Codex именованные рабочие кнопки.
Например:
| Action | Когда нужна | Что проверяет человек |
|---|---|---|
| Start app | посмотреть страницу или интерфейс | открылось ли то, что нужно |
| Run tests | проверить, не сломалась ли логика | есть ли failed tests и почему |
| Build preview | собрать публичный результат | нет ли ошибок сборки |
| Open logs | понять причину сбоя | лог относится к задаче или нет |
Главное правило: action должна быть понятной по результату. Если после команды непонятно, хорошо или плохо, это не проверка, а шум.
Что дать Codex на вход
Не нужно писать длинный роман про проект. Достаточно карточки:
Это проект [название]. Работать можно только в этой папке. Подготовка: [команда]. Запуск: [команда]. Проверка: [команда]. Если не хватает переменных окружения или доступа, не придумывай значения и не проси секреты в тексте ответа; остановись и напиши, какая переменная нужна. Production-команды не запускать без отдельного подтверждения.
Эта карточка делает две полезные вещи. Во-первых, Codex перестает каждый раз искать вход. Во-вторых, человек видит границы: что агент может запускать, а где должен остановиться.
Как проверить среду без программирования
Не-программисту не нужно понимать все команды. Нужно проверить четыре признака:
- Есть отдельная команда подготовки.
- Есть отдельная команда запуска.
- Есть отдельная команда проверки.
- Опасные действия отделены от обычной работы.
Если Codex после настройки среды может сам запустить preview, показать ошибку сборки, повторить тест и открыть страницу, это уже рабочий контур. Если он каждый раз спрашивает "а как запускать?", среды фактически нет.
Где остается человек
Codex может подготовить проект, запустить проверку, прочитать лог и предложить исправление. Но человек решает, какие секреты выдавать, какие production-действия разрешать, какие проверки считать достаточными и когда результат можно выпускать наружу.
Local environment нужен не для красоты. Это способ превратить "попроси ИИ что-нибудь сделать" в повторяемую работу: одна и та же среда, одни и те же команды, один и тот же критерий проверки. Чем меньше Codex гадает на старте, тем больше сил остается на задачу.
