Выполнение первой задачи
📚 Навигация по серии: Предыдущая статья 05 · Подключение DeepSeek и сторонних моделей подробно описала интеграцию альтернативных моделей. На этом блок настроек завершен — в этой статье мы переходим к практической работе: запустим Codex для редактирования кода и пройдем весь путь от постановки задачи до проверки diff-файлов изменений. В следующей статье 07 · Настольное приложение мы изучим графический интерфейс клиента.
Друзья, для начала поделюсь забавным случаем из личной практики в самом начале работы с Codex.
В первый вечер после установки CLI-клиента Codex мне не терпелось проверить его в деле. Я перешел в терминале в рабочий каталог основного репозитория нашей компании, который развивался более двух лет и содержал сотни файлов, и отправил запрос: «перепиши модуль пользователей, там слишком грязно». Codex сканировал файлы около десяти секунд, а затем вывел огромный лог изменений, затрагивающий семь или восемь различных файлов. Я подумал: «наверное, все хорошо», и одобрил изменения, даже не вчитываясь в детали.
Результат? Агент действительно провел рефакторинг, но попутно изменил сигнатуры двух смежных интерфейсов, которые я не просил трогать. Локальные тесты мгновенно посыпались ошибками. В итоге я потратил около часа на ручной разбор изменений, возвращая код в исходное состояние. Главный урок, который я вынес: проблема была не в возможностях Codex, а в том, что я пропустил важнейший этап — аудит сравнения изменений (diff).
В этой статье мы подробно разберем этот этап контроля. Мы не будем использовать рабочий репозиторий, а создадим тестовый проект из трех строк кода, чтобы за 5 минут пройти весь цикл: постановка задачи → изменение кода в песочнице → проверка сравнения (diff) → коммит или откат изменений. Это поможет вам понять принципы безопасного управления агентом. Мы разберем как работу в CLI, так и в настольном приложении.
После прочтения этой статьи вы получите:
- Пошаговый алгоритм выполнения первой задачи от открытия терминала до сохранения изменений
- Выработанный навык обязательного аудита сравнения файлов (diff) — ключевое отличие профессионала от новичка
- Сравнение работы в CLI и графическом приложении с критериями проверки результатов
- Инструкции по исправлению ошибок в процессе (как переформулировать запрос при отклонении изменений или вернуть код назад)
01 Использование тестового проекта для первого запуска
Первое правило безопасной работы: никогда не запускайте Codex на рабочих проектах при первом знакомстве. Создайте простейший тестовый файл.
Как показал мой личный опыт, в крупном проекте со сложной структурой файлов тяжело отслеживать изменения, вносимые AI. При больших масштабах велик риск пропустить критическую ошибку в коде. В тестовом проекте из нескольких строк любое изменение видно как на ладони.
Аналогия: обучение езде на велосипеде. Никто не выезжает на оживленную автостраду во время первого урока. Сначала тренируются на пустой площадке, где падения безопасны. Тестовая папка — это ваша тренировочная площадка: если код поврежден, ее можно пересоздать за минуту без какого-либо риска.
Кому особенно важно следовать этому совету:
- Пользователям без опыта работы в консоли — обилие логов при первом запуске на реальном проекте вызывает растерянность;
- Разработчикам, переходящим с других инструментов (например, Claude Code) — логика работы песочницы и подтверждений в Codex имеет свои особенности (см. Статьи 02 и 05);
- Специалистам, спешащим выполнить задачу — предварительное тестирование цепочки вызовов на простом примере сэкономит время при работе со сложным кодом.
Создайте каталог в терминале (в Windows используйте PowerShell):
mkdir hello-codex
cd hello-codexКоманды создадут папку hello-codex и переведут вас в нее.
Создайте простейший файл Python (для macOS и Linux):
echo 'def add(a, b):
return a + b' > main.pyВ ОС Windows откройте Блокнот, вставьте следующие строки и сохраните файл под именем main.py:
def add(a, b):
return a + b💡 Краткий вывод: Начните тестирование с изолированного проекта из нескольких строк кода — так вы сможете легко контролировать изменения без риска повредить рабочую систему.
02 Формулирование требований: цикл «подумать → сделать → проверить»
Перед запуском сформулируйте точные требования к задаче.
Помните: Codex не выполняет абстрактные желания. Качество результата зависит от точности постановки задачи. В Статье 02 мы говорили, что агент работает в цикле вызова функций (чтение, запись, тестирование), который сводится к этапам: подумать → сделать → проверить.
Аналогия: постановка задачи строительной бригаде. Фраза «наведи порядок в комнате» приведет к непредсказуемому результату. Четкое требование: «покрась стены спальни в белый цвет, установи раковину на балконе и закончи к пятнице» гарантирует соответствие ожиданиям. Чем детальнее описаны шаги и критерии проверки, тем точнее сработает Codex. Официальное руководство выделяет два правила работы с промптами:
- Возможность самопроверки: указывайте в запросе команды запуска линтеров и тестов для контроля результатов самим агентом.
- Декомпозиция задач: разделяйте крупные задачи на мелкие шаги, которые легко отлаживать и проверять. Если вы не знаете, с чего начать, попросите Codex сначала составить план действий (plan).
Сравнение размытых и точных промптов:
| Неэффективный запрос ❌ | Правильный запрос ✅ |
|---|---|
| «Оптимизируй эту функцию» | «Добавь аннотацию типов для add и вызови TypeError при передаче нечисловых параметров» |
| «Почему падает тест?» | «Запусти pytest, найди причину сбоя, исправь код и перезапусти тесты для проверки» |
| «Сделай рефакторинг проекта» | «Не меняй файлы сразу. Подготовь план рефакторинга, и после моего согласования приступай к шагам» |
Последняя строка — лучший способ начать работу со сложной кодовой базой. Попросите агента сначала составить текстовый план изменений. Это позволит вам скорректировать направление разработки до того, как файлы будут отредактированы.
💡 Краткий вывод: Codex работает по циклу «подумать → сделать → проверить». Точные запросы с критериями завершения гарантируют качественный результат. При масштабных изменениях всегда запрашивайте предварительный план действий.
03 Первая задача: Чтение файлов без записи
Для первой проверки попросите агента объяснить существующий код без внесения изменений.
Это решает две задачи: подтверждает, что Codex действительно имеет доступ к локальным файлам (а не придумывает ответ на основе общих знаний), и исключает риск повреждения файлов на этапе тестирования.
Аналогия: первый день стажера в команде. Вы не поручаете ему переписывать ядро системы в первый час. Сначала вы просите его изучить код и рассказать, как работают основные модули. Это подтверждает понимание логики проекта.
Отправьте запрос в терминале или приложении:
解释 main.py 这个文件在做什么，用新手能听懂的话说Нажмите Enter. Codex самостоятельно откроет main.py (вам не нужно копировать код в чат) и выведет описание работы функции: сложение двух входящих параметров a и b.
Успешное выполнение этого запроса подтверждает две вещи: клиент настроен корректно, и агент видит файловую систему вашего компьютера. Теперь можно переходить к редактированию кода.
Классификация типов запросов к агенту:
| Тип запроса | Описание операции | Пример | Уровень риска |
|---|---|---|---|
| Чтение и аудит | Анализ и объяснение кода | «Объясни работу модуля» | Нулевой (файлы не изменяются) |
| Рефакторинг | Внесение изменений в существующие файлы | «Добавь типизацию параметров» | Средний (изменяет файлы, требуется проверка diff) |
| Генерация | Создание новых файлов и структур | «Напиши тесты для функции» | Средний (создает файлы, требуется проверка diff) |
Рекомендуемая практика при начале работы со сторонним проектом: попросите Codex визуализировать структуру каталогов. Это подтвердит доступ к файлам и сэкономит время на ознакомление с проектом.
💡 Краткий вывод: Проверьте работоспособность клиента запросом на объяснение кода. Это безопасно и подтверждает доступ к файлам. Любые операции записи и генерации потребуют от вас обязательной проверки изменений (diff).
04 Проверка сравнения изменений (diff)
Перейдем к изменению кода. Этот этап требует максимального внимания.
Отправьте следующий запрос в текущей сессии:
给 main.py 里的 add 函数加上类型注解，并补充基本的错误处理Учитывайте важную особенность поведения по умолчанию: при работе в рабочем каталоге Codex вносит изменения в файлы напрямую, не запрашивая разрешение на каждую операцию записи. Это связано с тем, что в режиме workspace-write + on-request запись файлов внутри рабочей папки является штатной разрешенной операцией песочницы. Подтверждение запрашивается только при выходе за пределы контура (сетевые запросы, редактирование внешних папок). Стандартная логика выглядит так:
- Агент находит нужный файл (
main.py) и записывает изменения в локальный файл. - Изменения выводятся на экран в виде сравнения строк (diff), также вы можете вызвать команду
git diffв терминале. - Вы контролируете результат: анализируете diff, сохраняя корректный код или откатывая изменения при обнаружении ошибок (подробнее ниже).
Поэтому проверка сравнения изменений (diff) переносится с этапа «согласования перед записью» на этап «проверки записанного». Пока коммит не создан, вы можете отменить любые действия одной командой. Это основа безопасности при автоматической генерации кода.
⚠️ Примечание: Использование
git diffи откат версий требуют предварительной инициализации Git-репозитория в папке проекта. При отсутствии Git вы не сможете увидеть разницу изменений стандартными системными командами (вывод diff в самом клиенте Codex при этом будет работать исправно). Инициализируйте репозиторий перед началом редактирования.
Аналогия: коллега отправляет изменения в отдельную ветку Git и запрашивает ревью. Он написал код без пошагового контроля с вашей стороны, но эти изменения еще не попали в основную ветку. Вы изучаете diff и принимаете решение о слиянии или откате коммита. Так же действует и Codex.
Если вы хотите, чтобы агент запрашивал подтверждение перед редактированием каждого файла, переключите профиль прав на
read-onlyс помощью команды/permissionsили явно просите его составить предварительный текстовый план изменений.
Как читать разметку diff
Чтение сравнения строк строится на простых правилах:
- Красные строки со знаком
-в начале: удаленный оригинальный код; - Зеленые строки со знаком
+в начале: добавленный новый код; - Строки без знаков: неизмененный контекст для понимания структуры.
Исходный файл main.py:
def add(a, b):
return a + bПревратится в следующую структуру:
def add(a: float, b: float) -> float:
if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
raise TypeError("a 和 b 必须是数字")
return a + bПри анализе diff проверьте три основных аспекта:
- Затрагивают ли изменения только целевой блок кода? (убедитесь, что смежные интерфейсы не были изменены)
- Корректна ли логика добавленного кода?
- Не были ли удалены важные существующие фрагменты кода?
Если все параметры верны — сохраняйте изменения. При обнаружении ошибок попросите агента переписать код или выполните откат через Git. Этот аудит занимает менее 10 секунд, но предотвращает большинство сбоев.
В каких случаях запрашивается подтверждение
По умолчанию запись файлов в рабочей папке не прерывает сессию запросами. Подтверждение прав выводится только при потенциальном выходе за рамки песочницы:
| Действие Codex | Поведение по умолчанию | Отображаемый интерфейс |
|---|---|---|
| Чтение/запись в рабочем каталоге | Выполняется автоматически | Лог diff в консоли по окончании |
| Запуск тестов и сборщиков в рабочей папке | Выполняется автоматически | Логи выполнения команды |
| Команды установки внешних библиотек (с доступом к сети) | Приостановка работы | Интерактивный запрос Approve/Deny |
| Изменение файлов вне рабочей папки, доступ к сети | Приостановка работы | Интерактивный запрос Approve/Deny |
Для новичков: не переключайте политики в самый мягкий режим (вроде never или полного доступа) на старте. Без должного контроля агент может изменить множество файлов в системе, что затруднит поиск причин сбоев. Сохраняйте базовые ограничения безопасности песочницы.
Вы можете переключать уровни разрешений (см. Статью 02 и 15). В строгом режиме
read-onlyподтверждение требуется для каждой файловой операции; в мягких режимах блокировки сетевых соединений отключаются.
💡 Краткий вывод: В стандартном режиме Codex редактирует файлы рабочей папки автоматически, выводя diff на экран. Подтверждение требуется лишь при выходе за границы контура безопасности. Анализируйте diff по критериям точности, корректности логики и сохранности важного кода.
Схема описывает процесс: стандартная ветка записи в рабочей папке проходит автоматически, сетевые вызовы уходят на согласование к пользователю. По окончании записи вы принимаете решение о коммите или возврате изменений.
05 Доработка по текстовым комментариям
Отклонение предложенного кода не означает сброс прогресса. Это возможность направить рассуждения агента в нужную сторону.
Codex работает в рамках одной сессии (Thread), сохраняющей контекст диалога. Если сравнение diff показало ошибки или вы отклонили сетевой запрос, просто напишите текстовое уточнение в текущей строке чата — агент пересчитает логику.
Аналогия: заказ блюда в ресторане. Если вам принесли пересоленное блюдо, вы не уходите из ресторана, а просите официанта приготовить его повторно с меньшим количеством соли. Повар помнит ваш заказ, корректируя лишь одну деталь. Уточнение в чате работает так же.
Пример: при добавлении кэширования Codex импортировал стороннюю библиотеку, которой не было в зависимостях проекта. Я отклонил изменения и написал в чат:
别引第三方库，用 Python 标准库 functools.lru_cache 实现就行Агент моментально переписал импорты на использование стандартного модуля lru_cache. Вся доработка прошла в рамках одного репозитория без перезапуска клиента.
Сравнение подходов к доработке кода:
| Ошибочное представление ❌ | Фактическая логика работы ✅ |
|---|---|
| Отклонение сбрасывает весь прогресс | Отклонение дает возможность скорректировать логику |
| Ошибки приходится править вручную | Вы описываете ошибку текстом, и AI переписывает код |
| При сбоях нужно открывать новую сессию | Все итерации выполняются в рамках одного сохраненного контекста |
💡 Краткий вывод: Отклонение изменений — стандартный этап рефакторинга. Опишите ошибки в текущем чате, и Codex перепишет код, не теряя контекста диалога.
06 Использование Git для отката изменений
Если некорректный код был сохранен на диск, вы легко можете вернуть систему в исходное состояние при наличии предварительного коммита Git.
В официальном руководстве содержится рекомендация: «Агент вносит изменения в файлы вашего проекта. Всегда фиксируйте состояние репозитория (Git checkpoint) перед началом выполнения сложных задач для возможности быстрого отката». Основным инструментом отката версий выступает стандартный Git.
Аналогия: сохранение игры перед сложным боем. Вы создаете файл сохранения, чтобы в случае поражения загрузиться с этой точки, не проходя всю игру заново. Команда git commit — это точка сохранения вашего кода.
Инициализируйте репозиторий и сделайте коммит перед запуском Codex:
git init
git add -A && git commit -m "codex 动手前的存档点"Для отмены всех изменений выполните команду:
git restore .⚠️ Внимание: команда
git restore .сбрасывает все незафиксированные изменения в текущем рабочем каталоге. Используйте ее только при полной отмене результатов работы сессии. Для точечного отката используйте комментарии в чате.
Вы также можете попросить агента вернуть код к исходному состоянию прямо в чате:
刚才那次改动我不满意，帮我退回到改之前的样子Два способа отката изменений:
| Метод отмены | Как выполнить | Применение | Ограничение |
|---|---|---|---|
| Запрос в чате | Текстовая команда в текущей сессии | Мелкие недочеты сразу после генерации | Требует понимания со стороны AI |
| Откат коммита Git | Предварительный git commit, сброс через git restore . | Серьезные сбои логики, повреждение файлов | Сбрасывает все файлы в каталоге |
Перед началом работы с Codex всегда делайте коммит Git. Это избавит вас от необходимости исправлять поврежденный код вручную.
💡 Краткий вывод: Делайте
git commitперед каждым запуском агента. Для полной отмены изменений используйтеgit restore .. Мелкие правки можно отменить текстовым запросом в чате.
07 Практика в интерфейсе CLI
Выполним тестовый цикл сборки в CLI-клиенте:
Шаг 1: Создание проекта и фиксация в Git (macOS/Linux)
mkdir hello-codex && cd hello-codex
echo 'def add(a, b):
return a + b' > main.py
git init && git add -A && git commit -m "初始版本"Пользователям Windows: создайте файл main.py через Блокнот и выполните команды Git в PowerShell.
Ожидаемый результат: создание каталога с файлом main.py и фиксация первой версии коммитом.
Шаг 2: Запуск сессии Codex в рабочем каталоге
codexОжидаемый результат: открытие диалоговой строки CLI-клиента. Пройдите авторизацию при необходимости.
⚠️ Важно: запускайте
codexстрого внутри созданного каталога. Агент считывает файлы текущей рабочей директории. Запуск в системных папках приведет к ошибкам сканирования контекста.
Шаг 3: Проверка чтения файлов
Отправьте запрос:
解释 main.py 这个文件在做什么，用新手能听懂的话说Ожидаемый результат: текстовое описание работы функции сложения. Это подтверждает доступ агента к файлу.
Шаг 4: Изменение кода и проверка diff
Отправьте запрос:
给 main.py 里的 add 函数加上类型注解，并补充基本的错误处理Ожидаемый результат: Codex запишет новый код в файл и выведет разметку diff в консоль. Проанализируйте изменения.
Шаг 5: Проверка изменений в системе
Выйдите из сессии (Ctrl + C или /exit) и откройте измененный файл:
cat main.py(В Windows PowerShell используйте type main.py):
Ожидаемый результат: появление аннотации типов и исключения TypeError в файле.
Проверьте изменения через Git:
git diffОжидаемый результат: вывод diff, совпадающий с логами Codex.
💡 Краткий вывод: Шаги в CLI: коммит-архив → запуск
codex→ чтение файлов → запись изменений с аудитом diff → проверка файлов в консоли. Запуск выполняйте строго в рабочей директории.
08 Практика в настольном приложении
Настольное приложение заменяет консольный ввод визуальным управлением (доступно для macOS и Windows).
Логика работы идентична CLI, меняется лишь визуальное представление этапа проверки diff:
- Авторизация: запустите приложение и войдите в аккаунт.
- Выбор каталога: укажите рабочую папку
hello-codex. - Выбор режима: убедитесь, что переключатель установлен в положение Local (локальный режим выполнения задач).
- Первый запрос: отправьте команду объяснения кода:
解释 main.py 这个文件在做什么，用新手能听懂的话说После подтверждения отправьте запрос на рефакторинг:
给 main.py 里的 add 函数加上类型注解，并补充基本的错误处理Ожидаемый результат: Codex запишет изменения в файл, а графический интерфейс откроет панель ревью (review pane) с подсветкой измененных строк. Вы сможете визуально оценить код, сделать коммит или отменить изменения с помощью системных кнопок.
В отличие от CLI, настольный клиент содержит встроенную интеграцию с Git, позволяя коммитить или сбрасывать изменения прямо в графическом окне.
Сравнение CLI и настольного приложения:
| Параметр | CLI (командная строка) | Настольное приложение |
|---|---|---|
| Поддержка систем | ✅ Все три ОС (macOS, Windows, Linux) | ❌ Только macOS и Windows |
| Порог входа | Требует базовых навыков работы в консоли | ✅ Визуальное управление |
| Чтение diff | Текстовая подсветка в консоли | ✅ Визуальная двухпанельная подсветка |
| Параллельная работа | Открытие новых вкладок терминала | ✅ Удобное переключение каталогов в боковом меню |
| Логика процессов | Идентична (Постановка задачи → Запись → Аудит diff) | Идентична |
Оба варианта используют общую базу. Вы можете вызывать CLI для написания кода и открывать графический интерфейс для контроля больших файлов diff изменений.
💡 Краткий вывод: Настольное приложение предоставляет графическую обвязку для тех же процессов. Убедитесь в активации локального режима (Local). Панель ревью упрощает контроль больших файлов изменений.
09 Общая схема выполнения задачи
Последовательность действий при решении любых задач в Codex:
Главным этапом схемы является развилка проверки diff: записанный в песочнице код подлежит вашему обязательному анализу перед фиксацией.
💡 Краткий вывод: Базовый рабочий цикл: постановка задачи → запись изменений в песочнице → аудит diff → коммит или сброс. Всегда проверяйте сгенерированный код.
10 Резюме
Мы выполнили первую задачу программирования в Codex от инициализации до проверки результатов:
Чек-лист основных этапов:
| Этап | Действие | Описание |
|---|---|---|
| Подготовка | Создание каталога, файлов и коммит Git | Тестирование на изолированной папке |
| Запрос | Описание задачи на естественном языке | Четкие требования с критериями проверки |
| Проверка чтения | Запрос на объяснение структуры кода | Подтверждение доступа агента к файлам |
| Модификация | Запрос на рефакторинг | Автоматическая запись изменений в песочнице |
| Аудит diff | Проверка изменений по критериям | Обязательный контроль записанного кода |
| Отмена | Команда в чате или сброс через git restore . | Возврат системы в исходное состояние при ошибках |
Теперь вы готовитесь запускать сессии Codex, ставить текстовые задачи рефакторинга, читать разметку diff и управлять фиксацией изменений.
Цикл запрос → запись → аудит diff → коммит/откат является основой взаимодействия с AI-агентами. Любые сложные расширения (MCP, субагенты, Skills) накладываются поверх этой базовой схемы.
💡 Краткий вывод: Главная цепочка: запрос → запись → проверка diff → коммит или откат. По умолчанию Codex вносит изменения автоматически, оставляя за вами право контроля записанного кода.
В следующей статье 07 · Настольное приложение мы подробно изучим графический интерфейс клиента, включая управление несколькими проектами, изолированные рабочие деревья (worktrees), встроенный браузер и автоматизацию задач.