Если практика недоступна: маршрут только для чтения
Отдельный разбор: выбор Luna, Terra, Sol и Astra без практики — четыре ситуации с исходными данными, вопросами и готовыми объяснениями. Установка и подписка не нужны.
Дополнение: боковые и связанные чаты и рабочие сценарии тоже можно изучить без установки и запуска программ.
Этот раздел можно пройти без компьютера с настроенной средой, доступа к модели и установки инструментов. Сначала прочитайте основной модуль, затем разбор с тем же номером ниже. Попробуйте ответить на вопрос до чтения объяснения. Ссылки «Углубление» ведут к официальным материалам, преимущественно на английском; русское объяснение и разбор уже находятся в этом файле и доступны офлайн.
Такой маршрут помогает понять процесс и распознавать ошибки в заданиях и отчётах. Он не подтверждает, что вы умеете установить окружение, запустить проверки или исправить программу. Это отдельный результат, который можно получить позже на практикуме.
Как выбрать чтение
| Сегодняшняя цель | Что прочитать |
|---|---|
| Понять, что вообще делает Codex | Основные модули 00–03 и разборы 00–03 ниже |
| Научиться ставить задачи | Модули 03–05, шаблоны заданий, разборы 03–05 |
| Понимать интеграции | Модуль 06 и разбор 06; затем 11 |
| Оценивать качество работы агента | Модуль 07, разбор 07 и практикум как текст |
| Разобраться с несколькими агентами | Модули и разборы 08–10 |
| Разобраться с Windows и ошибками окружения | Модули 01, 02, 12 и шпаргалка PowerShell |
| Поддерживать собственные материалы | Модуль 13, разбор 13 и таблица актуальности |
Можно вести короткие заметки: «что понял», «какой вывод основан на источнике», «что понадобится проверить на практике». Никаких новых файлов проекта создавать не требуется.
00. Прочитать: как выглядит проверенный результат
Ситуация. Агент отвечает: «Исправил загрузку файлов, теперь всё работает». Изменены компонент интерфейса и обработчик API. В отчёте нет команд, данных воспроизведения или результата запроса.
Подумайте: чего именно не хватает, чтобы принять изменение?
Разбор. Известно только, что агент сообщил об изменениях. Ещё неизвестно, воспроизводилась ли исходная ошибка, как изменилось поведение и не сломан ли соседний сценарий. Достаточное доказательство зависит от задачи: для ошибки схемы ответа нужны проверка API и связанный пользовательский сценарий; для опечатки сложный тестовый стенд не нужен. Хорошее продолжение: «Покажи воспроизведение исходного сбоя, выполни проверку изменённого поведения и назови то, что проверить не удалось». Ответ «не смог запустить сервер из-за отсутствующей зависимости» честнее неподтверждённого «всё работает».
Что запомнить: описание изменения, запуск команды и подтверждение поведения — разные уровни доказательства.
Углубление: что умеет Codex CLI. Читайте описание возможностей и выбора сценария; установочную часть сейчас можно пропустить.
01. Прочитать: инструкция и техническое ограничение
Ситуация. В задании написано «только читай файлы». Сессия при этом имеет право записи в рабочую папку. Пользователь считает, что случайное изменение технически невозможно.
Подумайте: верен ли этот вывод?
Разбор. Нет. Фраза задаёт требование агенту, а песочница задаёт реальные границы для выполняемых команд. Они дополняют друг друга. Режим read-only ограничивает файловые операции; политика согласований определяет обращения за дополнительным разрешением. Сетевые ограничения — ещё одна настройка. Нельзя вывести доступ к сети из возможности читать файл или обещать, что любое внешнее действие заблокировано файловой песочницей: для подключённых инструментов также действуют их собственные разрешения. Конкретную конфигурацию проверяют в выбранной среде.
Что запомнить: «агенту запрещено инструкцией» и «команда не может это выполнить из-за политики» — разные утверждения.
Углубление: Sandbox and approvals. Составьте мысленно три отдельные колонки: файлы, сеть, согласования.
02. Прочитать: почему команда может работать в одном терминале
Ситуация. В обычном PowerShell Python найден, а агент отвечает, что не может запустить тест. Пользователь предлагает переустановить Python.
Подумайте: какие объяснения стоит проверить раньше переустановки?
Разбор. Возможно, команды выполняются в другой среде: WSL вместо Windows, другом процессе с иным PATH или активированном виртуальном окружении. Может отличаться рабочая папка или разрешения песочницы. Сначала сравнивают среду, найденный исполняемый файл и точную ошибку. Для npm-установки PowerShell также может выбирать codex.ps1, когда доступна другая обёртка codex.cmd. Это не доказательство поломки самого Codex. У standalone-установки набор файлов отличается, поэтому имя .cmd нельзя считать универсальным.
Что запомнить: успешная команда в одном окружении не доказывает её доступность в другом.
Углубление: Windows app, разделы о терминале, WSL и диагностике. Не запускайте команды: достаточно сопоставить описанные среды.
03. Прочитать: как уточнить расплывчатое задание
Ситуация. Исходная просьба: «Сделай загрузку файлов нормально». Из обсуждения известно: пустой CSV приводит к бесконечному индикатору загрузки. API менять нельзя.
Подумайте: как записать проверяемую задачу в нескольких предложениях?
Разбор. Возможная формулировка: «Устрани бесконечную загрузку при выборе пустого CSV. Начни с обработчика загрузки и существующих тестов формы. Сохрани контракт API и не добавляй зависимости. Готово, когда пустой файл показывает понятную ошибку и освобождает форму для повторной попытки, а корректный файл обрабатывается как раньше. Покажи проверку обоих сценариев». Здесь названы симптом, точка входа, границы и поведение после изменения. Длинный план пока не обязателен: сначала нужно выяснить причину в существующем коде.
Что запомнить: хороший запрос уменьшает неопределённость результата, а не диктует каждую строку реализации.
Углубление: Prompting. Сравните свои формулировки с рекомендациями о контексте и последующих уточнениях.
04. Прочитать: какие правила сохранять в AGENTS.md
Ситуация. В корневом AGENTS.md есть команда проверки всего проекта. В services/api/AGENTS.md описана дополнительная проверка API. Агент запущен из services/api. Для сегодняшней задачи требуется поправить одно сообщение об ошибке.
Подумайте: какие сведения постоянные, а какие относятся только к текущему запросу?
Разбор. Подтверждённые команды проверки и границы подсистемы подходят для постоянных правил. Требование изменить конкретное сообщение относится к текущему заданию. В описанной цепочке инструкции от корня к рабочему каталогу учитываются вместе; более близкие могут переопределять ранние. Нельзя считать, что вложенный AGENTS.md в произвольной соседней папке автоматически участвует в той же стартовой цепочке. Наличие AGENTS.override.md и ограничение объёма также влияют на результат. Поэтому при неожиданном поведении проверяют фактические пути, а не просто наличие файла где-то в репозитории.
Что запомнить: постоянное правило должно иметь понятную область действия и оставаться полезным после завершения сегодняшней задачи.
Углубление: How Codex discovers guidance. Нарисуйте цепочку каталогов на бумаге.
05. Прочитать: когда нужен skill
Ситуация. В команде каждую неделю разбирают сбои CI. Обычно нужны одни шаги: прочитать лог, выделить первую значимую ошибку, отличить проблему окружения от ошибки кода, предложить проверяемое исправление. Однажды также понадобилось заменить слово в README.
Подумайте: для какого задания полезен skill и как проверить его пользу?
Разбор. Разбор CI — кандидат на повторяемую процедуру. Исправление слова обычно достаточно описать обычным запросом. Skill имеет ясное назначение и условия выбора; затем инструкции и, при необходимости, вспомогательные файлы. Качество проверяют на нескольких характерных и соседних заданиях. Важно не только, выбрал ли агент skill, но и помог ли он не пропустить значимую ошибку. Большой каталог инструкций сам по себе не доказывает улучшения. Перед использованием стороннего skill нужно прочитать действия и зависимости, особенно если предусмотрены публикация или удаление.
Что запомнить: skill ценен проверенной процедурой, которую неудобно и ненадёжно пересказывать каждый раз.
Углубление: Build skills, подразделы о структуре и способах активации.
06. Прочитать: подключение не равно разрешению на запись
Ситуация. MCP-сервер задач предоставляет поиск, чтение и изменение статусов. Пользователь просит: «Найди незавершённые задачи по загрузке CSV». Агент предлагает сразу закрыть найденные старые задачи.
Подумайте: какую часть работы пользователь действительно поручил?
Разбор. Поиск и чтение соответствуют запросу. Закрытие задач меняет внешние данные и выходит за его пределы. Наличие инструмента и действующей авторизации ещё не является поручением применить все его возможности. Для ответа достаточно найти записи, прочитать релевантные детали и вернуть ссылки с объяснением отбора. Если сервер не подключился, следует сообщить об этом; нельзя выдумывать результаты или подменять их устаревшей локальной заметкой без оговорки.
Что запомнить: отдельно проверяют подключение, полномочия внешней учётной записи и согласованный объём задания.
Углубление: MCP для Codex, официальный Docs MCP. Настройку сейчас можно читать как пример, не выполняя её.
07. Прочитать: зелёные тесты и пропущенная ошибка
Ситуация из практикума. Функция reserve(available, quantity) должна резервировать положительное целое количество товара. Два исходных теста проверяют обычную покупку и превышение остатка. Оба проходят. При reserve(5, -1) функция возвращает 6.
Подумайте: противоречит ли это прохождению тестов и что должен проверять новый тест?
Разбор. Противоречия нет: исходный набор не проверял отрицательное количество. Новый тест должен выразить нарушенное требование — такая заявка должна быть отклонена. Затем его выполняют на исходнике и получают неуспех, исправляют реализацию и повторяют проверку. Простое утверждение «теперь функция возвращает 5» может скрыть изменение контракта вместо отклонения некорректного ввода. Отдельно полезно проверить отклонение нуля и дробных значений, а для bool явно уточнить правило, поскольку Python считает его подтипом целого числа. Расширять задачу бесконтрольно не нужно.
Что запомнить: тесты подтверждают охваченные свойства, а не всю корректность программы. Числа в этом разборе получены на исходном учебном коде, а не на рабочем продукте.
Углубление: Code review. Затем прочитайте практикум как историю проверки, не выполняя команды.
08. Прочитать: узкая роль помощника
Ситуация. Основной агент исправляет обработчик API. Помощнику поручено: «Проверь тесты и помоги с реализацией». Оба начинают менять один тестовый файл.
Подумайте: как сделать поручение независимым?
Разбор. Например: «Только прочитай существующие контрактные тесты API. Верни отсутствующие сценарии с путями и объяснением, что они защищают. Файлы не меняй; реализация остаётся у основного агента». Это убирает пересечение записи и даёт проверяемый результат. Но формулировка «только чтение» остаётся инструкцией; custom agent наследует технические разрешения родителя. Основной агент должен оценить доказательства помощника и не превращать его гипотезы в установленные дефекты.
Что запомнить: помощнику передают ограниченную ответственность, а не расплывчатую просьбу «помогать во всём».
Углубление: Subagents, разделы о делегировании и разрешениях.
09. Прочитать: почему больше агентов не всегда быстрее
Ситуация. Три агента одновременно меняют backend, frontend и схему общего ответа. Каждый выбрал собственное имя поля. Локальные тесты частей проходят, но интерфейс не понимает ответ API.
Подумайте: чего не хватало до начала параллельной работы?
Разбор. Нужен общий контракт: формат ответа, примеры успеха и ошибки, правила совместимости и владелец его изменения. После этого можно разделить независимые части. Готовность каждого модуля не заменяет интеграционную проверку. Если контракт ещё исследуется, последовательное уточнение может оказаться быстрее параллельной переделки. Польза делегирования определяется размером независимой работы и затратами на объединение; число агентов само по себе не является показателем качества.
Что запомнить: сначала зависимости и владельцы, затем параллельность, после неё — общая проверка.
Углубление: официальный обзор субагентов. Схемы разделения файлов в основном модуле — учебные рекомендации.
10. Прочитать: как передать состояние без всей переписки
Ситуация. В следующую сессию скопировали длинный журнал. В начале обсуждался вариант A, затем выбрали B. Новый агент приступил к A, потому что не нашёл окончательного решения.
Подумайте: что должно быть в короткой передаче состояния?
Разбор. Цель, действующие ограничения, ветка и ревизия, подтверждённое решение B со ссылкой на основание, выполненные проверки, оставшиеся вопросы и следующее действие. Отклонённый вариант A достаточно обозначить как отклонённый и назвать причину, если она ещё полезна. Важно отделить «решили сделать» от «уже сделали и проверили». Неизвестные измерения стоимости или токенов следует оставить неизвестными. В новой сессии всё равно нужно сверить, не изменился ли репозиторий.
Что запомнить: полезный контекст — актуальное состояние и доказательства, а не максимальная длина истории.
Углубление: Best practices. Сопоставьте советы с шаблоном передачи состояния в этом руководстве.
11. Прочитать: из чего состоит автоматизация
Ситуация. Команда успешно просит Codex вручную объяснять ошибки CI. Теперь хочет запускать тот же процесс по расписанию и автоматически применять исправления.
Подумайте: какие новые вопросы возникают при переходе к автоматическому запуску?
Разбор. Нужно определить среду выполнения, доступ к рабочей копии, входные данные, границы записи, поведение при отказе, обработку результата и условие завершения. Успешное объяснение лога ещё не доказывает безопасность самостоятельного изменения кода. Можно начать с отчёта без прав записи, а затем отдельно решить, кому передавать предложенный diff на проверку. CLI exec, расписание приложения, plugin и hook решают разные задачи. Для hooks также нужно проверить событие, доверие к определению и то, что несколько обработчиков могут сработать вместе.
Что запомнить: повторяемый запрос становится надёжной автоматизацией только вместе с окружением, правами и обработкой неуспеха.
Углубление: Non-interactive mode, Scheduled tasks, Hooks. Прочитайте сначала назначение каждого механизма, затем его конфигурацию.
12. Прочитать: диагностика по слоям
Ситуация. После запуска тестов показано: «команда python не найдена». Агент предлагает изменить проверяемую функцию.
Подумайте: какой факт о качестве функции уже установлен?
Разбор. Никакой: тесты не запустились. Ошибка относится к обнаружению интерпретатора или среде запуска. Сначала находят реально установленный Python либо проверяют py -3, подтверждают запуск версии и только затем выполняют тесты. В PowerShell $LASTEXITCODE от предыдущей внешней команды может сохраниться, если следующая программа вообще не стартовала; проверка наличия команды важна отдельно. Ошибку доступа к сети тоже нельзя исправлять произвольным изменением бизнес-кода. Диагностическое действие должно дать новые сведения, а не повторять ту же неуспешную попытку.
Что запомнить: различайте ошибку инструмента, окружения, прав и самой программы.
Углубление: Windows sandbox — Troubleshooting. Выберите один описанный симптом и перескажите, какой слой проверяется.
13. Прочитать: как обновлять знание
Ситуация. В wiki записано, что профили Codex задаются секциями [profiles.name]. Текущая официальная документация описывает отдельные файлы name.config.toml и объясняет изменение с версии 0.134.
Подумайте: достаточно ли молча заменить старый пример?
Разбор. Для поддерживаемого руководства полезно обновить сам пример, дату проверки и источник, а также посмотреть, где старый формат повторяется в соседних документах и шаблонах. Нельзя утверждать, что все компьютеры команды уже используют новую версию: это отдельный факт. Если старый материал важен для истории, его сохраняют с явной пометкой применимости. Изменение знания не требует автоматически менять глобальные настройки пользователей. Сначала уточняется область действия, затем предлагается соответствующее изменение.
Что запомнить: у полезного факта есть источник, дата, область применимости и статус проверки.
Углубление: актуальный раздел Profiles, затем таблица сверки в конце этого руководства.
Чем завершить маршрут чтения
Возьмите один пример задания из шаблонов и объясните: что должен получить агент, где лежат источники, что ему разрешено менять и какое доказательство будет достаточно. Затем прочитайте любой пример отчёта и отделите подтверждённое от предположений. Если вы можете сделать это своими словами, цель теоретического маршрута достигнута. Когда появится возможность практиковаться, начните с быстрого старта и одного backend-упражнения, а не со всего каталога инструментов.