Best Practices: Practical Rules for Daily Coding
📚 Навигация по серии: Предыдущая статья «35 Шпаргалка по командам и конфигурациям» собрала все параметры в краткую справочную таблицу. В этой главе мы перейдем на новый уровень: поговорим не о функциях по отдельности, а о том, как правильно сочетать их для выстраивания эффективного процесса разработки. В следующей статье «37 Поиск и устранение неисправностей» мы разберем действия при возникновении сбоев.
Короткий разбор того, почему стандартные советы не работают и какие практики действительно повышают эффективность программирования с ИИ.
Когда я только начинал работать с Codex, я совершил распространенную ошибку: прочитал официальный раздел best-practices от начала до конца, согласился с каждым пунктом, после чего... закрыл страницу и не изменил в своей работе ни одной привычки.
Проблема заключалась не во мне, а в абстрактном характере большинства подобных советов. Фразы вроде «пишите запросы точнее», «запускайте тесты» или «делайте небольшие шаги» звучат верно, но они не объясняют, насколько точно нужно писать, какие именно тесты запускать и каков размер этих самых шагов. Разработчик кивает головой, но продолжает совершать прежние ошибки. Подобные универсальные советы лишь перекладывают ответственность на пользователя.
В этой главе мы обойдемся без общих лозунгов. Я проанализировал официальные рекомендации, сопоставил их со своим опытом и выбрал только те практики, которые реально изменили мой стиль программирования и доказали свою эффективность. Каждое правило снабжено разбором «Зачем это делать», «Как это сделать» и «К каким ошибкам приводит игнорирование».
Большинство этих правил родились из моих собственных ошибок и потерянного на переделки времени.
Прочитав эту статью, вы получите:
- Понимание ментального подхода к Codex как к полноценному коллеге, а не простому генератору кода
- Правила наполнения файла
AGENTS.mdдля сохранения его эффективности - Четырехкомпонентную схему составления промптов для ежедневного использования
- Методику выбора уровней безопасности песочницы под разные задачи
- Обоснование важности предварительного планирования перед написанием кода
- Правила настройки закрытого цикла тестирования и самопроверки ИИ
- Регламент сбора доказательств при отладке критических ошибок на проде с правилами десенсибилизации (обезличивания) данных
- Сводную таблицу типичных ошибок и правильных подходов для самопроверки
⚠️ Имена команд, ключи настроек и системное поведение в этой статье соответствуют официальной документации Codex. Конкретные версии моделей и тарифы могут меняться, проверяйте их на вашем компьютере с помощью справки
codex --helpи в меню/model.
01 Меняем ментальный подход: Codex — это коллега, а не разовый калькулятор
Базовый принцип: эффективность работы с ИИ напрямую зависит от того, кем вы его считаете в процессе разработки.
Многие разработчики используют ИИ как поисковую строку: задают разовый вопрос, забирают сгенерированный кусок кода и закрывают чат. При таком подходе потенциал системы используется лишь на треть.
Аналогия: Codex — это новый разработчик, которого вы наняли в команду. Он отлично знает синтаксис языков, но совершенно не знаком со спецификой вашего проекта. Вы не ждете, что он сразу выдаст идеальный код. Сначала вы даете ему вводную памятку (файл AGENTS.md), показываете команды запуска тестов и один раз корректируете его типичные ошибки, чтобы он запомнил правила. Чем дольше вы работаете вместе, тем лучше он понимает требования. Если же вы каждый раз стираете контекст и нанимаете «временного рабочего» под отдельную задачу, вам придется бесконечно повторять вводные правила.
Как сказано в документации: «Не воспринимайте Codex как временного помощника — относитесь к нему как к коллеге, чьи инструменты и настройки вы будете постоянно развивать и оптимизировать». Все дальнейшие правила основаны именно на этой идее — переходе от разовых запросов к долгосрочной настройке окружения.
Мой перелом в работе произошел в начале 2026 года. До этого при создании каждого нового диалога я вручную писал ИИ: «В этом проекте используется pnpm, а не npm», «Тесты запускаются через pnpm test», «Текст коммита пиши на русском». Я делал это по несколько раз в день, пока не понял, что трачу время впустую. Я перенес эти правила в AGENTS.md один раз, и Codex начал соблюдать их автоматически. Я перестал использовать умный инструмент самым неэффективным образом.
💡 Резюме в одном предложении: Относитесь к Codex как к долгосрочному члену команды, чьи инструкции вы фиксируете в правилах проекта, а не как к разовому генератору кода.
02 Правильно заполняем файл AGENTS.md
Зачем это делать. Чтобы Codex автоматически считывал контекст проекта при каждом запуске, избавляя вас от необходимости прописывать одни и те же рамки в каждом сообщении.
Аналогия: AGENTS.md — это файл README для ИИ. Обычный README пишется для людей (описание проекта, установка). AGENTS.md ориентирован на робота: он описывает правила разработки, границы изменений и критерии приемки кода.
Как сделать. Официальные рекомендации предлагают включать в AGENTS.md следующие блоки:
- Структура папок проекта и ключевые модули.
- Команды сборки и запуска приложения.
- Команды запуска тестов и линтеров.
- Принятые соглашения по стилю кода и созданию PR.
- Ограничения и запрещенные к изменению зоны (красные линии).
- Критерии готовности задач и методы проверки.
Для быстрого создания шаблона введите команду /init в TUI. Но обязательно перепишите полученные заглушки под реальные требования вашего проекта.
Вы можете разделять правила по уровням: глобальные правила хранятся в ~/.codex/, правила репозитория — в корне проекта, а локальные настройки модулей — во вложенных папках. Приоритет имеют правила, расположенные ближе к изменяемому файлу.
Типичная ошибка: внесение в AGENTS.md временных задач («в этой ветке не меняй базу данных» или «сейчас правим только этот файл»). Файл правил начинает разрастаться устаревшими инструкциями, которые запутывают ИИ. Соблюдайте разделение:
Временные рамки пишите в промптах чата, а постоянные стандарты проекта фиксируйте в
AGENTS.md. Краткие правила работают лучше длинных трактатов.
Внедрите полезную привычку: если Codex дважды совершил одну и ту же системную ошибку в проекте, проведите краткий разбор и зафиксируйте запрет в AGENTS.md. Это позволит вашей базе правил расти на основе реального опыта разработки.
💡 Резюме в одном предложении: Фиксируйте постоянные правила проекта в
AGENTS.md, сохраняя файл кратким и избавляясь от устаревших временных инструкций.
03 Пишем промпты по схеме: Цель + Контекст + Ограничения + Критерии готовности
Зачем это делать. Чтобы ИИ не додумывал требования самостоятельно. Если промпт размыт, Codex выберет наиболее вероятное, по его мнению, решение, которое может не совпасть с архитектурой вашего проекта, что приведет к переделкам.
Используйте готовую структуру запроса как формулу:
| Компонент | Назначение | Риск при отсутствии |
|---|---|---|
| Цель (Goal) | Что конкретно нужно сделать или изменить | ИИ сделает лишнюю работу, не решив основную задачу |
| Контекст (Context) | Связанные файлы, логи ошибок, примеры кода (через @) | ИИ начнет искать код по всему проекту и запутается |
| Ограничения (Constraints) | Правила разработки, запрещенные к изменению модули | Код будет написан в чуждом для проекта стиле |
| Критерии готовности (Done when) | Признаки успешного завершения задачи | ИИ сдаст неработающий код, переложив тестирование на вас |
Как сделать. Перед отправкой любого сложного запроса проверьте наличие всех четырех компонентов в вашем сообщении.
Аналогия: постановка задачи строителям. Вы не говорите: «Сделайте кухню посимпатичнее». Вы указываете планируемый стиль (цель), даете схему разводки труб (контекст), запрещаете трогать несущие стены (ограничения) и требуете, чтобы при сдаче вода текла из крана без протечек, а свет включался с настенных выключателей (критерии готовности).
Чаще всего разработчики забывают прописать критерии готовности. Однажды я попросил ИИ добавить проверку формата номера телефона в форму регистрации. Codex успешно справился с задачей, но при этом случайно заблокировал валидацию адреса электронной почты. Если бы я указал в критериях готовности «проверить сохранение работы существующих валидаторов и запустить тесты», ошибка была бы локализована ИИ на этапе разработки.
💡 Резюме в одном предложении: Стройте запросы по формуле «Цель + Контекст + Ограничения + Готовность», обязательно указывая критерии успешной приемки работы.
04 Сложные задачи начинайте с планирования
Зачем это делать. Если задача масштабна или описана нечетко, написание кода сразу приведет к ошибкам. Codex начнет менять файлы на ходу, додумывая архитектуру. Обсуждение плана действий в текстовом формате позволяет скорректировать направление работы до изменения кода.
Аналогия: согласование чертежей перед стройкой. Дешевле исправить несколько линий на бумаге, чем сносить кирпичную стену, если она построена не в том месте. Текстовый план — это дешевый чертеж вашего будущего кода.
Как сделать. Используйте следующие подходы:
- Запуск Plan mode: переключите Codex в режим планирования через команду
/planили сочетание клавишShift+Tab. ИИ изучит файлы и предложит пошаговый план изменений без правки кода. - Интервьюирование: попросите ИИ провести экспресс-опрос: «Не пиши код сразу. Задай мне уточняющие вопросы по архитектуре, чтобы сформировать точный план».
- Использование
PLANS.md: для долгосрочных задач фиксируйте этапы выполнения в файле планов (согласно официальным рекомендациям по execution plans).
Отказ от предварительного планирования сложных задач часто приводит к сбоям. При переносе старого модуля на асинхронные методы async/await без предварительного плана ИИ может начать переписывать глобальные обработчики ошибок проекта, что сломает сборку. Проектирование изменений по шагам через /plan позволяет избежать хаотичных правок.
💡 Резюме в одном предложении: Для масштабных или нечетких задач всегда запускайте режим планирования
/planдля согласования архитектуры изменений до редактирования файлов.
05 Безопасная настройка уровней доступа песочницы
Зачем это делать. Песочница ограничивает Codex в доступе к системным файлам компьютера и сети. Запуск с избыточными правами безопасности повышает риск случайного повреждения файлов вашей операционной системы.
Аналогия: выдача пропусков стажерам. Вы даете им доступ в рабочий кабинет и блокируете проход в серверную и бухгалтерию.
Как сделать. Следуйте правилам:
- Используйте настройки безопасности по умолчанию для повседневной работы.
- Расширяйте права доступа только для проверенных репозиториев и конкретных задач, а не делайте это глобально.
Матрица выбора прав:
| Задача | Режим песочницы | Обоснование |
|---|---|---|
| Анализ незнакомого кода, проверка репозиториев | read-only | Исключает случайное изменение файлов |
| Повседневное написание кода в проекте | workspace-write + on-request | Разрешает менять файлы проекта с запросом прав на внешние действия |
| Запуск непроверенных внешних скриптов | Максимально жесткие ограничения | Защита от выполнения деструктивных системных команд |
Помните, что предоставление Codex полных прав администратора компьютера без контроля со стороны пользователя является критической ошибкой безопасности. Отключение подтверждений оправдано только в изолированных контейнерах или при запусках тестов в CI. Для доступа к внешним папкам используйте точечное добавление каталогов через параметр --add-dir, не отключая песочницу полностью.
💡 Резюме в одном предложении: Начинайте работу с минимально необходимых прав доступа песочницы (
workspace-write), расширяя их точечно при необходимости и избегая полного отключения защиты.
06 Организация замкнутого цикла тестирования и самопроверки ИИ
Зачем это делать. Это наиболее эффективный способ сэкономить время. Не проверяйте результаты работы ИИ вручную. Обяжите Codex написать тесты, запустить их и исправить ошибки до того, как он передаст вам готовую задачу.
Для этого ИИ должен знать команды запуска тестов и стандарты проекта, зафиксированные в AGENTS.md.
Как сделать. Включайте в критерии приемки кода следующие шаги:
- Написание или обновление юнит-тестов для измененных модулей.
- Запуск тестов проекта.
- Проверка кода линтерами и сборщиками.
- Валидация соответствия логики требованиям промпта.
- Анализ diff изменений на наличие ошибок сборки.
Используйте встроенную команду /review для автоматического анализа изменений перед коммитом. Она позволяет сравнить текущую ветку с базовой и указать на логические ошибки.
Типичная ошибка: отправка кода без тестирования. Если вы просите ИИ изменить метод обработки данных и не требуете запуска тестов, он может сдать код, который упадет при первом же запуске на граничных значениях. Всегда пишите в конце запроса: «После внесения изменений запусти команду проверки (например, pytest) и сдавай работу только при успешном прохождении тестов».
💡 Резюме в одном предложении: Перекладывайте рутину тестирования на Codex, обязывая его запускать проверки и исправлять ошибки до демонстрации вам готового кода.
07 Отладка ошибок в продакшене: сбор доказательств и защита данных
Зачем это делать. При поиске причин сбоев на проде ИИ может предложить неверное решение, если опирается только на гипотезы. Обяжите Codex сначала собрать факты (логи, коды ответов), составить цепочку доказательств и только потом приступать к изменениям.
Как сделать. Запретите ИИ менять код на первом этапе. Промпт для сбора информации должен выглядеть так:
Не вноси изменения в код. Собери доказательства сбоя по следующему плану:
1. Воспроизведи путь пользователя: зафиксируй метод запроса, код ответа и ключевые заголовки.
2. Проверь логи приложения за указанный период, выпиши строки с ошибками.
3. Найди связанные конфигурационные файлы и таблицы базы данных, не меняя их состояние.
4. Сформируй отчет по структуре: Факты / Гипотезы / Шаги проверки.
5. Обезличь данные перед выводом: скрой токены, адреса почты, ключи доступа и персональные данные.Это убережет систему от поспешных правок, основанных на неверных предположениях.
Внесите правила работы со сбоями продакшена в файл AGENTS.md:
## Работа со сбоями на проде
- Сначала воспроизвести ошибку и зафиксировать коды ответов и логи.
- Запрещено изменять данные пользователей, права доступа и биллинг без согласования.
- Все выводимые логи и ссылки должны быть обезличены (удалены токены, пароли, e-mail).
- Проверять устранение сбоя тем же путем, которым ошибка воспроизводилась.
- Если проверку провести невозможно, указать список недостающих доступов или данных.Правила обезличивания данных
При работе с логами продакшена следите за тем, чтобы конфиденциальные данные не попали в публичные репозитории или внешние системы аналитики.
Пример замены чувствительных данных:
| Исходные данные | Безопасный формат для ИИ |
|---|---|
https://example.com/private/path?token=secret_value | https://example.com/private/path?token=<token> |
user@example.com | <user-email> |
order_20260201_123456 | <order-id> |
Authorization: Bearer confidential_data | Authorization: Bearer <redacted> |
2026-02-01 14:03:22 status=500 | Сохраняйте время и коды ошибок для анализа |
Удаляйте только значения полей, сохраняя общую структуру лога, коды ответов сервера и временные метки — этого достаточно для локализации багов.
💡 Резюме в одном предложении: При разборе инцидентов требуйте от Codex сбора фактов и логов перед написанием кода, контролируя обезличивание данных при выводе отчетов.
08 Изоляция задач и управление сессиями
Зачем это делать. История общения накапливается в рамках диалога. Чем длиннее сессия и чем больше разнородных задач в ней обсуждалось, тем выше вероятность того, что ИИ запутается в контексте и начнет предлагать неверные решения.
Аналогия: чистота на рабочем столе. Если вы одновременно разложите документы по трем разным проектам, вы начнете путать данные. Для каждой задачи должен быть выделен чистый стол.
Как сделать. Соблюдайте правила:
- Одна задача — один диалог. Ведите общение по конкретной фиче в рамках одной ветки. При переходе к другой задаче открывайте чистый чат.
- Используйте ветвление
/forkпри необходимости пойти по альтернативному пути разработки, чтобы не засорять основную ветку. - Своевременно сжимайте контекст через
/compactв длинных обсуждениях для удаления устаревших сообщений из памяти ИИ. - При параллельной работе над несколькими задачами запускайте процессы в изолированных каталогах
git worktree, чтобы Codex не перезаписывал файлы, с которыми вы работаете в данный момент.
💡 Резюме в одном предложении: Не ведите обсуждение всех задач проекта в одном чате: открывайте новую сессию под каждую задачу, вовремя сжимайте историю по
/compactи изолируйте фоновые процессы.
09 Таблица типичных ошибок и правильных подходов
Мы объединили ключевые рекомендации в краткую таблицу самопроверки. Если вы чувствуете, что разработка с Codex идет медленно или ИИ часто совершает ошибки, сверьтесь с этим списком:
| ❌ Ошибочный подход (ведет к сбоям) | ✅ Правильный подход (экономит время) |
|---|---|
| Прописывать правила сборки проекта в каждом запросе | Зафиксировать стандарты и команды в AGENTS.md |
| Не указывать команды тестов в файле правил | Описать методы проверки в блоке ## Тестирование правил проекта |
| Запускать написание кода для сложных задач сразу | Согласовать пошаговый план изменений через режим /plan |
| Отключать песочницу или давать ИИ полные права | Держать доступ закрытым по умолчанию, открывая папки через --add-dir |
| Вести переписку по всем задачам в одной длинной сессии | Открывать новый чат для каждой отдельной задачи |
| Запускать параллельные сессии ИИ в одной папке | Использовать git worktree для изоляции фоновых процессов |
| Проверять работоспособность кода после ИИ вручную | Обязывать Codex запускать тесты и добиваться статуса OK |
| Начинать исправление бага на проде без сбора логов | Требовать от ИИ сбора фактов и кодов ответов до правок кода |
| Выкладывать сырые логи с токенами и почтой пользователей | Обезличивать данные, скрывая ключи и сохраняя структуру ошибок |
💡 Резюме в одном предложении: Периодически проверяйте свой рабочий процесс по этой таблице, исправляя ошибки настройки окружения и постановки задач ИИ.
Итоги
Мы разобрали практические приемы эффективного взаимодействия с Codex при разработке программного обеспечения.
Основные выводы главы:
- Отношение — воспринимайте Codex как полноценного разработчика вашей команды, развивая его инструкции.
- Стандарты — фиксируйте правила сборки и тестирования в
AGENTS.mdдля автоматического считывания контекста. - Запросы — пишите промпты по схеме «Цель + Контекст + Ограничения + Критерии готовности».
- Безопасность — используйте минимально достаточный уровень доступа песочницы для защиты системы.
- Проверка — доверяйте ИИ запуск тестов и линтеров для подтверждения работоспособности изменений.
- Гигиена диалогов — открывайте новую сессию под каждую отдельную задачу и вовремя очищайте память чата.
Соблюдение этих правил сделает вашу совместную работу с ИИ-ассистентом предсказуемой, быстрой и безопасной.
В следующей статье 37 · Поиск и устранение неисправностей мы поговорим о действиях при возникновении сбоев. Мы разберем типичные ошибки подключения к серверам, падения песочницы на разных ОС, конфликты Git при работе ИИ и дадим пошаговый алгоритм локализации неисправностей.