Продвинутые советы по использованию Codex
После базовой установки и первого разговора настоящая ценность Codex заключается в его встраивании в ваш ежедневный процесс разработки.
В этой статье рассматриваются пять продвинутых направлений: конфигурация проекта, управление сессиями, интеграция с редактором, автоматизация CI/CD и советы по составлению промптов; они помогут вам научить Codex понимать ваш проект, запоминать ваши соглашения и автоматически работать в конвейере.
1. Напишите «документ онбординга» для Codex с помощью AGENTS.md
AGENTS.md — это руководство по проекту, написанное для Codex. Если поместить его в корневой каталог проекта, оно автоматически загружается при каждом запуске и действует на протяжении всей сессии.
Зачем это нужно
По умолчанию Codex ничего не знает о вашем проекте.
Он не знает, используете ли вы App Router или Pages Router, не знает, через какой файл должны единообразно проходить операции с базой данных, и не знает, какие файлы не следует трогать.
Если вам приходится заново объяснять контекст в каждом разговоре, эффективность будет очень низкой, и вероятны ошибки.
AGENTS.md позволяет записать эту информацию один раз, и она остаётся действующей, избавляя от необходимости повторяться.
Что писать
Эффективный AGENTS.md обычно содержит четыре типа информации: обзор проекта, технологический стек, важные соглашения и запрещённые пункты.
Ниже приведён полный пример:
# AGENTS.md ## 项目概述 这是一个基于 Next.js 14 + Prisma + PostgreSQL 的 SaaS 应用。 使用 App Router,不使用 Pages Router。 ## 技术栈 - 前端:Next.js 14, React 18, TailwindCSS, shadcn/ui - 后端:Next.js API Routes, Prisma ORM - 数据库:PostgreSQL 15 - 认证:NextAuth.js ## 重要约定 - 所有数据库操作必须通过 lib/db.ts 中的 prisma 实例 - API 路由错误统一用 lib/api-error.ts 处理 - 环境变量在 .env.local 中,参考 .env.example ## 禁止事项 - 不要修改 prisma/schema.prisma,除非我明确要求 - 不要删除任何现有测试 - 生产环境的 .env 文件不要碰
Раздел «Запрещённые пункты» особенно важен. При выполнении задач Codex активно определяет, какие файлы нужно изменить. Без чётких границ он может затронуть места, которые вы не хотите, чтобы он трогал. Чётко прописать красные линии гораздо проще, чем исправлять проблемы после их возникновения.
Иерархическая структура конфигурации
AGENTS.md поддерживает три уровня вложенности с приоритетом от низкого к высокому.
Чем ближе файл к текущему каталогу, тем выше его приоритет. В одном и том же каталоге, если существует AGENTS.override.md, AGENTS.md того же уровня будет пропущен.
| Уровень | Путь | Область действия | Приоритет |
|---|---|---|---|
| Глобальный уровень | ~/.codex/AGENTS.md | Общие межпроектные соглашения | Низкая |
| Уровень проекта | repo/AGENTS.md | Соглашения уровня репозитория | Средняя |
| Уровень переопределения | repo/services/payments/AGENTS.override.md | Особые правила для подкаталогов | Высокая |
Глобальный уровень подходит для соглашений, действующих во всех проектах, например:
# ~/.codex/AGENTS.md ## 全局约定 - 安装依赖时优先使用 pnpm - 修改 JavaScript 文件后始终运行 npm test - 新增生产依赖前先请求确认
После завершения настройки можно использовать следующую команду, чтобы проверить, что загрузка выполнена правильно:
codex --ask-for-approval never "Summarize the current instructions."
2. Управление сессиями: продолжение больших задач в течение нескольких дней
Функция управления сессиями позволяет экспортировать текущее состояние разговора в файл и напрямую восстановить его в следующий раз без повторного воссоздания контекста.
Фон
Окно контекста Codex ограничено.
При работе с большой задачей, охватывающей несколько файлов и требующей поэтапного продвижения, если вы закроете терминал на полпути или переключитесь на что-то другое, контекст будет потерян, когда вы вернётесь — Codex не вспомнит, что обсуждалось ранее и какие решения были приняты.
Экспорт сессии может решить эту проблему, позволяя восстановить предыдущее состояние разговора в любой момент времени.
Базовое использование
Ниже приведены общие команды, связанные с управлением сессиями:
Пример
/export session-2024-01-15.json
# Восстановить при продолжении в следующий раз
/load session-2024-01-15.json
# Прямо возобновить последнюю сессию (чаще всего используется)
codex resume --last
# Просмотреть все сохранённые сессии
ls ~/.codex/sessions/
Когда экспортировать
Не нужно экспортировать каждый разговор. Следующие ситуации стоит сохранять:
| Сценарий | Описание |
|---|---|
| Многоэтапные задачи, занимающие несколько дней | Задача занимает несколько дней с чётким разделением по этапам; после сохранения в следующий раз можно продолжить непосредственно с последней контрольной точки. |
| Важные архитектурные решения | Обсудили важное архитектурное решение с Codex, и последующие задачи должны выполняться на основе этого решения. |
| Сложные процессы отладки | Отладка сложной ошибки, несколько направлений уже исключены, не хочется в следующий раз начинать заново. |
3. Интеграция с VS Code
Codex официально предоставляет расширение для VS Code. После установки можно начинать диалоги прямо в редакторе, не переключаясь в терминал.
Установка и вход
Шаги установки следующие:
Шаг 1: Откройте магазин расширений (Cmd/Ctrl + Shift + X).
-
Шаг 2: Найдите "Codex" или "OpenAI Codex" и установите официальный плагин.

-
Шаг 3: При первом использовании необходимо войти в свою учётную запись ChatGPT.
-
Шаг 4: Как только значок Codex появится на боковой панели, можно приступать к работе.
После установки вы можете использовать следующие сочетания клавиш для быстрых действий:
| Горячая клавиша | Функция |
|---|---|
| Alt + G | Отправить выделенный код в Codex, включая контекст текущего файла |
| Cmd + Shift + P | Откройте палитру команд, введите "Codex", чтобы просмотреть все доступные команды |
Режим BYO (для пользователей без подписки ChatGPT)
Если вы уже настроили свой API-ключ в CLI (Anthropic, OpenAI или других совместимых провайдерах), вы можете использовать бесплатную учетную запись ChatGPT для входа в плагин VS Code.
Плагин автоматически повторно использует конфигурацию модели CLI и не заставляет вас использовать ChatGPT Plus.
| Применимые сценарии | Описание |
|---|---|
| У вас уже есть API-ключ, но вы не хотите отдельно подписываться на ChatGPT | Используйте свой API-ключ напрямую, дополнительная платная подписка не требуется |
| Хотите, чтобы VS Code и CLI использовали одну и ту же модель | Плагин автоматически повторно использует конфигурацию CLI, поэтому на обоих концах обеспечивается идентичный опыт. |
4. Интеграция с CI/CD
Codex CLI поддерживает работу в headless-режиме, не требующем взаимодействия с человеком, что делает его подходящим для интеграции в автоматизированные рабочие процессы.
Что может делать Codex в пайплайне
Ниже приведены распространённые способы использования Codex в CI/CD в headless-режиме:
| Сценарий использования | Описание | Типичное время срабатывания |
|---|---|---|
| Автоматически обновлять CHANGELOG | После каждого слияния в основную ветку автоматически обновлять CHANGELOG.md на основе истории коммитов. | После слияния в основную ветку |
| Генерировать документацию API | Автоматически генерировать или синхронизировать документацию API на основе изменений в коде | После отправки кода |
| Автоматическое код-ревью | Автоматически запускать проверку кода в конвейере PR и оставлять комментарии | Когда PR создаётся или обновляется |
Пример GitHub Actions
Следующий рабочий процесс автоматически позволяет Codex обновлять CHANGELOG.md на основе последних коммитов каждый раз, когда код отправляется в ветку main:
Пример
name: Автообновление Changelog
на:
push:
branches: [main]
jobs:
update-changelog:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Настройка Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Установить Codex CLI
run: npm install -g @openai/codex
- name: Запустить задачу Codex
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
CODEX_QUIET_MODE: 1
run: |
codex exec --full-auto "Обнови CHANGELOG.md на основе последних коммитов"
- name: Зафиксировать изменения
run: |
git config --local user.email 'action@github.com'
git add CHANGELOG.md
git commit -m 'chore: update changelog [skip ci]'
git push
В конфигурации есть два ключевых момента, требующих особого внимания:
| Элемент конфигурации | Назначение | Описание |
|---|---|---|
| CODEX_QUIET_MODE: 1 | Подавить интерактивный вывод | Избежать зависания конвейера в ожидании интерактивного ввода |
| --full-auto | Запуск в headless-режиме | Позволить Codex выполняться напрямую без надзора, не дожидаясь подтверждения |
При использовании в CI рекомендуется явно указать в файле AGENTS.md в корне проекта, какие файлы Codex разрешено изменять в автоматическом режиме, чтобы избежать неожиданных изменений из-за неверной интерпретации промптов.
5. Советы по составлению промптов
Качество вывода Codex во многом зависит от того, как вы задаёте вопросы.
Следующие пять советов посвящены самым распространённым проблемам, с которыми сталкиваются новые пользователи; каждый совет сопровождается конкретными примерами.
Совет 1: Предоставьте достаточно контекста
Codex не умеет читать мысли. Инструкция вроде "исправь ошибку" заставит его гадать вслепую, и результат часто оказывается не тем, что вам нужно.
Вот пример для сравнения:
| Не рекомендуется | Рекомендуется |
|---|---|
| "Исправь ошибку" | "Когда пользователь входит в систему, возникает ошибка: TypeError: Cannot read properties of null. Ошибка возникает в строке 42 файла src/auth/login.ts. Эта функция отвечает за проверку JWT-токенов. Пожалуйста, найди и исправь эту проблему." |
Эффективный контекст включает три элемента:
| Элемент | Описание | Пример |
|---|---|---|
| Конкретный симптом | Сообщение об ошибке или конкретное поведение | TypeError: Cannot read properties of null |
| Задействованное местоположение | Файл и номер строки | Строка 42 в src/auth/login.ts |
| Ответственность кода | Изначальное назначение этого кода | Проверка JWT-токена |
Совет 2: Разделите сложные задачи на два шага
Для задач с большим объёмом изменений сначала поручите Codex проанализировать и составить план, затем выполняйте после подтверждения, что направление верное.
Выполнение всего за один шаг может показаться быстрее, но цена выше, если направление неверное.
Пример
codex "Проанализируй качество кода в каталоге src/api/ и перечисли основные проблемы. Не изменяй никакие файлы."
# Шаг 2: Выполните после подтверждения плана
codex "Хорошо, действуй по предложенному плану. Начни с проблем обработки ошибок; остальное я проверю позже."
Совет 3: используйте режим Ask, чтобы сначала понять кодовую базу
askРежим Ask — это режим только для чтения, подходящий для понимания структуры и логики существующего кода перед внесением изменений.
Понимание до внесения изменений экономит время по сравнению с возвращением к пониманию после внесения изменений.
Пример
# ask 模式不会触发任何文件修改 codex -a ask "这个项目是如何处理用户认证的?梳理完整的认证流程"
Как только у вас будет чёткое понимание, выйдите из текущей сессии и перезапуститесь в режиме редактирования:
# 可编辑模式(需要确认) codex -a auto # 全自动执行(谨慎使用) codex -a full-auto
Рекомендуемый рабочий процесс:
ask ↓ 理解代码结构 ↓ 确定修改方案 ↓ 重新启动 Codex ↓ 进入可编辑模式 ↓ 执行修改
Примечание: CLI больше не поддерживает переключение режимов разрешений во время выполнения; это необходимо указать через
/approvalsпараметр при запуске. Десктопный клиент по-прежнему поддерживает переключение в рамках сессии.-aпараметр. Десктопный клиент по-прежнему поддерживает переключение в рамках сессии.
Совет 4: используйте негативные инструкции, чтобы установить границы
Сказать Codex, чего не трогать, так же важно, как сказать ему, что делать.
Особенно для задач рефакторинга, затрагивающих несколько связанных файлов, нечёткие границы могут легко привести к ненужным сопутствующим изменениям.
Пример
codex "Переработайте функции форматирования даты в utils/date.ts. Не меняйте сигнатуры функций и не изменяйте тестовые файлы."
Совет 5: сначала попросите план, затем выполняйте
Для задач, в которых вы не уверены, сначала попросите Codex перечислить, как он намерен к ним подойти.
Этот шаг почти не занимает времени, но позволяет рано заметить отклонения от направления и не зайти слишком далеко по неверному пути.
# 先要计划 codex "你打算怎么实现这个功能?先列出步骤,不要执行" # 确认计划合理后再推进 codex "计划没问题,开始执行第一步"
Итог
Эти пять направлений охватывают весь путь от "конфигурации проекта" до "ежедневных операций" и до "автоматизации".
Необязательно использовать все их сразу. Рекомендуется идти по порядку: сначала напишите AGENTS.md, чтобы Codex понимал ваш проект, затем постепенно интегрируйте его в ваш рабочий процесс VS Code и конвейер CI/CD.
Техники промптинга лучше накапливать постепенно в повседневном использовании, чем заучивать всё сразу.
Другие расширения