Как использовать OpenAI Codex для малой задачи в репозитории

Чтобы использовать OpenAI Codex для небольшой задачи в репозитории, поручите ему изменить одно наблюдаемое поведение, потребуйте прочитать инструкции репозитория и начните с проверки только для чтения. Разрешайте узкую реализацию только после того, как в плане будут указаны затрагиваемые файлы, крайние случаи и команда проверки. Затем просмотрите фактический diff и результаты тестов. Уверенное резюме агента не доказывает, что код корректен.

В этом руководстве рассматривается одна синтетическая задача: обновить normalizeTag, чтобы после удаления пробелов по краям и приведения к нижнему регистру последовательность дефисов сворачивалась в один дефис, сохранив существующую ошибку для пустого ввода. Руководство не обучает программированию с ИИ в целом и не повторяет описанный для Cursor процесс с карточкой задачи и контрольными точками. Более широкий контекст — в руководствах как использовать ИИ и основы программирования с помощью ИИ.

Ключевые выводы

• Опишите одно поведение, его нецели и доказательство выполнения.
• Перед планированием попросите Codex прочитать AGENTS.md и ближайшие инструкции репозитория.
• Отделяйте проверку только для чтения от разрешения на редактирование или команды с побочными эффектами.
• Сохраняйте существующие незакоммиченные изменения и запрещайте постороннюю очистку.
• Предпочитайте самый маленький патч и самые узкие значимые тесты.
• Сами проверяйте статус, diff, команду, код выхода и оставшиеся пробелы.

Когда использовать OpenAI Codex для небольшой задачи репозитория?

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

Параметр	Задача достаточно мала	Остановиться и планировать отдельно
Поведение	Одно наблюдаемое правило	Несколько несвязанных результатов
Файлы	Несколько найденных файлов	Неясная ответственность между сервисами
Интерфейс	Существующий контракт сохранён	Изменение схемы или публичного API
Данные	Синтетические фикстуры	Производственные или конфиденциальные данные
Проверка	Целевая локальная команда	Деструктивная миграция или тестирование в рабочей среде
Полномочия	Локальное редактирование	Внешняя запись, релиз, покупка или использование учётных данных

Если проверка выявила решение о публичной совместимости, новую зависимость, секрет или побочный эффект в рабочей среде, правильный результат — пересмотреть план, а не незаметно расширять патч.

Как написать контракт задачи?

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

Цель: нормализовать повторяющиеся дефисы в normalizeTag.
Примеры: "  Alpha---Beta  " -> "alpha-beta"; "alpha" -> "alpha".
Сохранить: пустой ввод по-прежнему вызывает существующий тип ошибки и сообщение.
Разрешенные файлы: src/normalizeTag.ts и test/normalizeTag.test.ts.
Не входит в задачу: изменение экспорта, вызывающего кода, пакета, форматирования или маршрута.
Проверка: только для чтения; изучить инструкции, реализацию, места вызова и тесты.
Реализация: после представления плана дождитесь явного одобрения.
Проверка результата: запустите существующий файл тестов для normalizeTag и сообщите код выхода.
Остановитесь, если: необходим другой файл, зависимость, доступ к сети, разрушительная команда или секрет.

Примеры задают поведение точнее, чем «почистить теги». Включите обычный случай, случай без изменений, граничный случай и сохраняемую ошибку. Не диктуйте реализацию до того, как Codex проверит локальные соглашения.

Почему Codex должен сначала прочитать инструкции репозитория?

Codex может находить файлы AGENTS.md от корня репозитория до рабочего каталога, а ближайшие инструкции уточняют применимые правила.［2］ Эти файлы могут определять тестовые команды, именование, границы сгенерированных файлов, требования безопасности или запрещенные операции.

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

Иерархия инструкций не заменяет текущий запрос. Она помогает Codex соблюдать правила проекта, а карточка задачи задает цель и полномочия именно этой работы.

Как начать проверку только для чтения?

Первый запрос должен просить факты и план, а не правки:

Прочтите карточку задачи и применимые инструкции репозитория. Проверьте текущую
реализацию, прямые места вызова, тесты и статус Git. Не редактируйте файлы,
не устанавливайте зависимости, не используйте сеть и не изменяйте состояние Git.
Верните описание текущего поведения, минимальный список предлагаемых файлов,
крайние случаи, точную целевую команду теста, конфликты с существующими изменениями,
предположения и причины, по которым задача может оказаться не маленькой.

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

В рекомендациях OpenAI предлагается указывать цель, контекст, ограничения и желаемый результат, а затем уточнять результат последующими сообщениями.［1］ Для работы с репозиторием критерии успеха и границы полномочий являются частью этого контекста.

Как разрешить реализацию?

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

Реализуйте только утверждённое поведение normalizeTag в двух названных файлах.
Сохраните текущий контракт для пустого ввода и несвязанные незакоммиченные изменения.
Не добавляйте зависимости, не редактируйте сгенерированные файлы, не получайте доступ к сети и не изменяйте
внешние системы. После изменения покажите патч и запустите целевой тест. Если потребуется
другой файл, остановитесь и объясните причину до его изменения.

В средах Codex используются песочницы и средства подтверждения для ограничения доступа к файлам и сети; точная политика зависит от интерфейса и конфигурации.［3］ Песочница снижает риск, но не делает каждое разрешенное действие уместным. Владелец задачи по-прежнему должен ограничивать объем и проверять последствия.

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

Как будет выглядеть минимальная реализация?

Следуйте стилю репозитория. Возможное преобразование может выглядеть так:

export function normalizeTag(value: string): string {
  const normalized = value.trim().toLowerCase().replace(/-+/g, "-");
  if (!normalized) {
    throw new Error("tag must not be empty");
  }
  return normalized;
}

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

Целевые тесты могут охватывать:

Ввод	Ожидается	Цель
Alpha---Beta	alpha-beta	Новое поведение для повторных дефисов
alpha-beta	alpha-beta	Существующая обрезка пробелов и перевод в нижний регистр
alpha	alpha	Простой ввод без изменений
---	Результат, определённый проектом	Граничный случай, требующий изучения контракта
только пробелы	Существующая ошибка	Сохранённое поведение при ошибке

Не придумывайте ожидаемый результат для ---. Изучите текущую семантику и требования к продукту; если ни то ни другое не даёт ответа, остановитесь и дождитесь решения человека.

Как проверить патч, прежде чем доверять ему?

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

Задайте эти вопросы:

1. Изменяет ли реализация только запрошенное преобразование?
2. Сохраняются ли тип ошибки, сообщение, экспорт и сигнатуры вызовов?
3. Падают ли тесты без исправления и проходят ли с ним?
4. Представлены ли обычный путь, путь без изменений, новое поведение и путь ошибки?
5. Не изменились ли форматирование, снимки, lock-файлы, конфигурация или сгенерированные файлы?
6. Выполнил ли агент именно указанную команду в правильном каталоге?
7. Перечислены ли все непроверенные предположения?

Руководство по проверке кода, сгенерированного ИИ предлагает более глубокую проверку безопасности и корректности. Официальное руководство OpenAI также рассматривает результат Codex как изменение, которое нужно изучить, а не как доказательство корректности.［4］ Сгенерированный код остается ненадежным до проверки и тестирования.

Как следует запускать и интерпретировать проверку?

Начните с самого узкого теста, который проверяет измененное поведение. Запишите команду, рабочий каталог, код выхода, количество тестов и соответствующие выходные данные об ошибке. Если инструмент запуска тестов обновляет снимки или сгенерированные файлы, проверьте diff ещё раз.

Далее расширяйте проверку только в соответствии с политикой репозитория и затронутыми местами вызова: тесты пакета, проверка типов, линтер или более широкий набор тестов. Целевой успешный запуск подтверждает только названную область, а не весь репозиторий. О несвязанном сбое следует сообщить с доказательствами, а не сбрасывать или «исправлять» чужие изменения.

Для идей по проектированию тестов используйте руководство по созданию тестов с помощью ИИ, но опирайте проверки на реальный контракт.

Какие границы безопасности и разрешений важны?

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

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

Одобрение относится к конкретной операции. Разрешение редактировать два локальных файла не означает разрешения на push, публикацию или обновление внешней задачи в трекере. Руководство OpenAI по безопасности описывает песочницу и границы одобрений, но действия с серьёзными последствиями пользователь всё равно должен проверять.［3］

Как написать итоговый протокол приемки задачи Codex?

Используйте факты, которые можно проверить:

Цель и принятое поведение:
Изменённые файлы:
Сохранённые существующие незакоммиченные файлы:
Проверка diff:
Команды, рабочий каталог и коды выхода:
Пройденные тесты и точный объём:
Невыполненные тесты:
Допущения и оставшиеся риски:
Невыполненные внешние действия:

Не говорите «готово», если команда не завершилась, код выхода отсутствует, соответствующий тест был пропущен или другая необходимая среда остается непроверенной. Если тест не удалось запустить из-за границ песочницы или платформы, сообщите о пробеле в покрытии, а не ослабляйте тест.

Итоговый контрольный список

• Одно наблюдаемое поведение и его нецели заданы явно.
• Применимый AGENTS.md и местные правила были прочитаны.
• Первичная проверка прошла без правок и побочных эффектов.
• В плане названы файлы, крайние случаи, тесты и условия остановки.
• Полномочия на реализацию ограничены уже, чем доступ ко всему репозиторию.
• Имеющиеся незакоммиченные изменения сохранены.
• В diff нет посторонней очистки или неожиданных изменений.
• Целевые тесты охватывают новые, неизмененные, граничные и ошибочные пути.
• О более широких проверках сообщается отдельно от целевых доказательств.
• Внешние, деструктивные, привилегированные и сетевые действия одобряются отдельно.

Часто задаваемые вопросы (FAQ)

Какой должна быть первая задача Codex в репозитории?

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

Стоит ли сразу просить Codex внести изменения?

Нет, если репозиторий или последствия изменения вам незнакомы. Проверка только для чтения позволяет проверить текущий путь, правила, тесты и конфликты перед предоставлением полномочий на запись.

Что должно быть в AGENTS.md?

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

Обеспечивает ли песочница Codex безопасность каждой команды?

Нет. Песочница ограничивает технический доступ согласно конфигурации, но не подтверждает намерение, правильность, стоимость или полномочия в бизнесе. Внимательно проверяйте запросы на расширение разрешений.［3］

Следует ли Codex запускать полный набор тестов?

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

Как защитить существующую незафиксированную работу?

Попросите Codex проверить статус Git, сохранить существующие незакоммиченные файлы и не выполнять сброс или массовое форматирование. После изменения снова проверьте статус и diff.

Может ли Codex отправить или опубликовать результат после исправления?

Только если это разрешено отдельными полномочиями и политикой репозитория. Разрешение на локальное редактирование не означает разрешения на коммит, push, релиз, сообщение или развёртывание.

Что делать, если Codex понадобится еще один файл?

Следует остановиться, назвать файл, объяснить, зачем он нужен, и пересмотреть план. Не позволяйте узкой задаче расти молча.

Кто решает, принято ли задание?

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

Источники

1. OpenAI, “Prompting” — https://learn.chatgpt.com/docs/prompting
2. OpenAI, “Custom instructions with AGENTS.md” — https://learn.chatgpt.com/docs/agent-configuration/agents-md
3. OpenAI, “Agent approvals & security” — https://learn.chatgpt.com/docs/agent-approvals-security
4. OpenAI, “Code review with Codex” — https://learn.chatgpt.com/docs/code-review

Sources checked 5 сентября 2026 г.

Рекомендуемые статьи

• Практическая основа использования ИИ
• Как использовать ИИ в рабочем процессе кодирования
• Аналогичный рабочий процесс для небольших задач в Cursor
• Как просмотреть код, сгенерированный ИИ
• Как разрабатывать тесты с помощью ИИ