Как писать промпты для Codex: структура задачи, ограничения и ожидаемый результат

Почему обычный промпт для кода часто не работает

Слабый промпт:

Исправь ошибку на сайте.

Проблема в том, что Codex не знает:

В результате инструмент может начать искать проблему слишком широко и затронуть больше кода, чем нужно.

Сильный промпт выглядит иначе:

Задача:
исправить ошибку 500 при сохранении формы редактирования профиля.

Контекст проекта:
PHP 8.4, собственная MVC-архитектура без фреймворков, MariaDB, русскоязычный интерфейс.

Проблема:
после отправки формы /profile/edit пользователь получает ошибку 500. Данные не сохраняются.

Ожидаемое поведение:
форма должна валидировать данные, сохранять изменения текущего пользователя и возвращать его на страницу профиля с flash-сообщением.

Файлы для проверки:
- app/routes.php
- app/Controllers/ProfileController.php
- app/Services/ProfileService.php
- app/views/profile/edit.php

Ограничения:
- не переписывать модуль с нуля;
- не менять маршруты без необходимости;
- не удалять существующую CSRF-защиту;
- сохранить multi-user изоляцию;
- не добавлять новые зависимости.

После изменений:
- кратко указать, что исправлено;
- перечислить изменённые файлы;
- указать, какие проверки выполнить вручную.

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

Промпт для Codex — это не просьба, а инженерная задача

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

Если этих данных нет, Codex будет додумывать задачу. В разработке это рискованно.

Базовая структура промпта для Codex

Рабочий промпт для Codex можно строить по такой схеме:

Контекст проекта:
[стек, архитектура, важные правила]

Задача:
[что именно нужно сделать]

Проблема:
[что сейчас работает неправильно]

Ожидаемый результат:
[как должно работать после изменений]

Файлы и зоны ответственности:
[какие файлы проверить или изменить]

Ограничения:
[что нельзя менять]

Требования:
[что обязательно учесть]

Проверки:
[что нужно проверить после изменений]

Миграции:
[нужны ли изменения БД]

Формат ответа:
[что Codex должен сообщить после выполнения]

Эта структура подходит для багфиксов, рефакторинга, добавления функций, code review, UI-правок, миграций и аудита безопасности.

1. Контекст проекта

Контекст помогает Codex не принимать случайные архитектурные решения.

Слабый вариант:

Добавь форму обратной связи.

Сильный вариант:

Контекст проекта:
PHP 8.4, собственная MVC-архитектура без фреймворков, MariaDB, роутинг в app/routes.php, шаблоны в app/views, вся админка и публичный интерфейс на русском языке.

Задача:
добавить форму обратной связи без нарушения текущей архитектуры.

Контекст может включать:

Пример контекста:

Контекст проекта:
проект работает без фреймворков. Нельзя предлагать Laravel, Symfony или полную переработку архитектуры. Нужно работать в текущей структуре: routes, controllers, services, views.

Такой блок сразу отсекает неподходящие решения.

2. Конкретная задача

Задача должна быть сформулирована как действие.

Плохо:

Посмотри код.

Лучше:

Проверь код формы регистрации на ошибки валидации, CSRF-защиты и записи пользователя в БД.

Плохо:

Улучши админку.

Лучше:

Приведи страницу списка пользователей в админке к единому list-pattern: заголовок страницы, панель фильтров, таблица, пустое состояние, пагинация и inline-действия.

Плохо:

Сделай SEO.

Лучше:

Добавь SEO-поля для статей блога: SEO-заголовок и SEO-описание. Сохрани существующие поля и не меняй публичные URL.

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

3. Описание проблемы

Если задача связана с ошибкой, нужно описать текущее поведение.

Слабый вариант:

Форма не работает.

Сильный вариант:

Проблема:
при отправке формы создания статьи появляется ошибка 500. В логах ошибка указывает на отсутствие поля seo_description. Форма открывается, но сохранение не проходит.

Хорошее описание проблемы включает:

Пример:

Проблема:
при удалении комментария из админки комментарий удаляется, но пользователь остаётся на белой странице. Нужно вернуть редирект обратно на список комментариев с flash-сообщением.

Так Codex не будет искать проблему в неправильном месте.

4. Ожидаемый результат

Ожидаемый результат — это описание правильного поведения после изменений.

Плохо:

Сделай нормально.

Лучше:

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

Для багфикса:

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

Для UI-задачи:

Ожидаемый результат:
страница визуально соответствует остальной админке: тёмная тема, единые отступы, одинаковые кнопки, таблица не разваливается на мобильной ширине.

Для миграции:

Ожидаемый результат:
новые поля добавлены в БД через отдельный SQL-файл, существующие данные не теряются, код корректно работает как с новыми, так и со старыми записями.

Без ожидаемого результата Codex может выполнить задачу формально, но не так, как нужно проекту.

5. Файлы и зоны ответственности

Если вы знаете, где находится нужный код, укажите файлы.

Плохо:

Найди, где это сделано, и исправь.

Лучше:

Файлы для проверки:
- app/routes.php
- app/Controllers/BlogController.php
- app/Services/BlogService.php
- app/views/admin/blog-form.php
- database/migrations/

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

Начни с поиска по:
- маршрутам, связанным с /admin/blog;
- контроллерам блога;
- view-файлам формы статьи;
- сервисам сохранения статей.

Файлы помогают сократить область изменений. Это особенно важно в больших проектах.

6. Ограничения

Ограничения защищают проект от лишних правок.

Примеры хороших ограничений:

Ограничения:
- не переписывать модуль с нуля;
- не менять публичные URL;
- не удалять существующие поля;
- не ломать обратную совместимость;
- не добавлять тяжёлые зависимости;
- не менять схему БД без миграции;
- не трогать авторизацию без необходимости;
- не менять дизайн других страниц;
- не выводить полный листинг кода в ответ.

Для проекта без фреймворков:

Ограничения:
- не предлагать Laravel, Symfony или другой фреймворк;
- не переносить текущую архитектуру;
- работать в существующей структуре проекта.

Для безопасности:

Ограничения:
- не ослаблять CSRF-защиту;
- не убирать проверку прав доступа;
- не доверять данным из запроса без валидации;
- не выводить пользовательский HTML без экранирования.

Ограничения должны быть конкретными. Формулировка «не ломай ничего» слишком слабая. Нужно указать, что именно нельзя нарушать.

7. Требования к реализации

Требования описывают, что обязательно нужно сделать.

Пример для формы:

Требования:
- добавить server-side валидацию;
- сохранить CSRF-защиту;
- показывать ошибки рядом с полями;
- сохранять введённые значения при ошибке;
- после успешного сохранения делать редирект;
- все тексты интерфейса оставить на русском языке.

Пример для API:

Требования:
- возвращать JSON-ответы;
- использовать корректные HTTP-статусы;
- валидировать входные данные;
- не раскрывать внутренние ошибки пользователю;
- логировать критические ошибки.

Пример для админки:

Требования:
- сохранить текущие действия администратора;
- добавить фильтр по статусу;
- добавить пустое состояние;
- сохранить пагинацию;
- привести кнопки к единому стилю.

Требования должны быть такими, чтобы результат можно было проверить.

8. Миграции БД

Если задача затрагивает базу данных, это нужно указать отдельно.

Слабый промпт:

Добавь новое поле к пользователю.

Сильный промпт:

Добавь поле display_name для пользователя.

Требования к БД:
- создать отдельный SQL-файл миграции;
- не удалять существующие поля;
- не менять типы существующих колонок без необходимости;
- предусмотреть безопасное значение по умолчанию;
- указать, что миграцию нужно применить.

Если миграция не нужна, тоже стоит указать:

Миграции БД:
не нужны. Не меняй структуру базы данных.

Это защищает проект от неожиданных изменений схемы.

9. Проверки после изменений

Codex должен не только изменить код, но и указать, как проверить результат.

Примеры проверок:

Проверки:
- открыть страницу /admin/blog/create;
- отправить форму с пустыми полями и проверить ошибки;
- отправить форму с корректными данными;
- убедиться, что статья сохраняется;
- проверить flash-сообщение;
- проверить, что SEO-поля сохраняются и отображаются при редактировании.

Для багфикса:

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

Для code review:

Проверки:
- разделить найденные проблемы по критичности;
- указать риск каждой проблемы;
- предложить точечные исправления;
- не переписывать код без необходимости.

Проверки нужны, чтобы задача не заканчивалась фразой «готово» без контроля результата.

10. Формат ответа Codex

Формат ответа должен быть коротким и полезным.

Хороший формат:

Формат ответа:
кратко сообщи:
1. Что изменено.
2. Какие файлы изменены.
3. Нужны ли миграции.
4. Какие проверки выполнить.
5. Есть ли риски или нерешённые вопросы.

Плохой формат:

Расскажи подробно всё, что сделал.

Такой ответ может превратиться в длинный отчёт без пользы.

Для работы через Codex лучше требовать не полный код в чате, а краткий отчёт:

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

Это особенно важно, если код меняется прямо в проекте.

Универсальный шаблон промпта для Codex

Контекст проекта:
[стек, архитектура, важные правила проекта]

Задача:
[что именно нужно сделать]

Проблема:
[что сейчас работает неправильно или чего не хватает]

Ожидаемый результат:
[как должно работать после изменений]

Файлы и зоны поиска:
- [файл или папка 1]
- [файл или папка 2]
- [файл или папка 3]

Требования:
- [что обязательно сделать]
- [что обязательно сохранить]
- [какие сценарии учесть]

Ограничения:
- не переписывать модуль с нуля;
- не менять архитектуру без необходимости;
- не добавлять тяжёлые зависимости;
- не удалять существующий функционал;
- не менять БД без отдельной миграции;
- не выводить полный код в ответ.

Миграции БД:
[нужны / не нужны / если нужны — создать отдельный файл и указать, что его применить]

Проверки:
- [сценарий проверки 1]
- [сценарий проверки 2]
- [сценарий проверки 3]

Формат ответа:
кратко укажи:
1. Что сделано.
2. Какие файлы изменены.
3. Какие миграции созданы, если они есть.
4. Что нужно проверить вручную.
5. Какие риски остались, если они есть.

Этот шаблон можно использовать как базу для большинства задач по коду.

Пример 1. Промпт для исправления бага

Контекст проекта:
PHP 8.4, MariaDB, собственная MVC-архитектура без фреймворков. Интерфейс на русском языке. Авторизация уже реализована, CSRF-защиту нельзя отключать.

Задача:
исправить ошибку при сохранении статьи в админке.

Проблема:
при отправке формы редактирования статьи появляется ошибка 500. Предположительно проблема связана с сохранением SEO-полей.

Ожидаемый результат:
статья должна сохраняться без ошибки. SEO-заголовок и SEO-описание должны сохраняться и отображаться при повторном открытии формы.

Файлы для проверки:
- app/routes.php
- app/Controllers/AdminBlogController.php
- app/Services/BlogService.php
- app/views/admin/blog-form.php
- database/migrations/

Требования:
- сохранить существующие поля статьи;
- не ломать создание новых статей;
- не ломать редактирование старых статей;
- сохранить CSRF-защиту;
- ошибки валидации показывать на русском языке.

Ограничения:
- не переписывать блог-модуль с нуля;
- не менять публичные URL статей;
- не добавлять зависимости;
- не менять структуру БД без миграции;
- не выводить полный код в ответ.

Миграции БД:
если SEO-полей нет в таблице, создай отдельный SQL-файл миграции и укажи, что его нужно применить.

Проверки:
- открыть создание статьи;
- сохранить статью с SEO-полями;
- открыть редактирование и проверить, что поля заполнены;
- сохранить старую статью без SEO-полей;
- проверить лог ошибок.

Формат ответа:
кратко: что исправлено, какие файлы изменены, создана ли миграция, что проверить.

Такой промпт сужает задачу и защищает проект от лишних изменений.

Пример 2. Промпт для добавления новой функции

Контекст проекта:
PHP-проект без фреймворков, собственный роутер, MariaDB, шаблоны в app/views, вся админка на русском языке.

Задача:
добавить возможность сохранять черновик статьи без публикации.

Ожидаемый результат:
в форме статьи должна быть возможность сохранить материал как черновик. Черновик не должен отображаться на публичной части сайта, но должен быть доступен в админке.

Файлы и зоны поиска:
- маршруты админки блога;
- контроллер блога;
- сервис сохранения статей;
- форма статьи;
- список статей в админке;
- миграции БД.

Требования:
- добавить статус draft, если его ещё нет;
- в админке показать статус статьи;
- на публичной части выводить только опубликованные статьи;
- все новые тексты интерфейса сделать на русском языке;
- сохранить существующую логику опубликованных статей.

Ограничения:
- не менять публичные URL опубликованных статей;
- не удалять существующие поля;
- не переписывать блог-модуль с нуля;
- не добавлять новые зависимости;
- не ломать старые статьи.

Миграции БД:
если статуса нет, создать отдельный SQL-файл миграции.

Проверки:
- создать черновик;
- убедиться, что он виден в админке;
- убедиться, что он не виден на публичном сайте;
- опубликовать черновик;
- проверить, что опубликованная статья появилась на сайте.

Формат ответа:
кратко указать, что сделано, какие файлы изменены, какую миграцию применить и что проверить.

Такой промпт задаёт не только функцию, но и правила её поведения.

Пример 3. Промпт для рефакторинга

Контекст проекта:
существующий PHP-проект без фреймворков. Код работает в продакшене, поэтому рефакторинг должен быть осторожным.

Задача:
провести точечный рефакторинг сервиса сохранения промптов.

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

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

Файлы для проверки:
- app/Services/PromptService.php
- app/Controllers/PromptController.php
- app/views/prompts/form.php

Требования:
- разделить крупный метод на небольшие приватные методы;
- сохранить текущие проверки;
- сохранить загрузку изображений;
- сохранить обработку ошибок;
- не менять внешний интерфейс сервиса без необходимости.

Ограничения:
- не переписывать весь модуль;
- не менять схему БД;
- не менять маршруты;
- не менять HTML формы без необходимости;
- не добавлять зависимости;
- не менять бизнес-логику.

Проверки:
- создать новый промпт;
- отредактировать существующий промпт;
- загрузить изображение;
- отправить форму с ошибками;
- проверить, что старые сценарии работают.

Формат ответа:
кратко указать, какие методы выделены, какие файлы изменены и что проверить.

Для рефакторинга особенно важно указать: поведение не должно измениться.

Пример 4. Промпт для code review

Контекст проекта:
PHP 8.4, MariaDB, собственная MVC-архитектура, много пользовательского контента. Важны безопасность, multi-user изоляция и экранирование вывода.

Задача:
провести code review файла app/Services/PromptService.php.

Проверь:
- SQL-инъекции;
- XSS;
- CSRF-сценарии, если применимо;
- проверку прав доступа;
- multi-user изоляцию;
- валидацию входных данных;
- обработку ошибок;
- дублирование логики;
- слишком большие методы;
- риск поломки существующего поведения.

Ограничения:
- не вноси изменения сразу;
- сначала дай список проблем;
- не предлагай полный переписанный модуль;
- не давай абстрактные советы без привязки к коду.

Формат ответа:
таблица:
1. Критичность.
2. Файл/место.
3. Проблема.
4. Почему это риск.
5. Как исправить.

После таблицы:
краткий список правок, которые стоит сделать в первую очередь.

Для code review лучше сначала просить анализ, а не автоматические правки.

Пример 5. Промпт для UI-задачи

Контекст проекта:
админка сайта уже имеет тёмный интерфейс, единые карточки, таблицы, кнопки и flash-уведомления. Нужно доработать одну страницу без изменения всей дизайн-системы.

Задача:
привести страницу управления пользователями к единому стилю админки.

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

Файлы для проверки:
- app/views/admin/users.php
- public/assets/css/admin.css
- app/routes.php, если нужны фильтры

Требования:
- сохранить существующие действия block/unblock;
- добавить понятное пустое состояние;
- привести кнопки к единому стилю;
- не ломать пагинацию;
- все тексты интерфейса оставить на русском языке;
- проверить адаптивность.

Ограничения:
- не менять общую админскую оболочку;
- не переписывать layout;
- не подключать Bootstrap;
- не добавлять новые JS-библиотеки;
- не менять логику ролей.

Проверки:
- открыть список пользователей;
- проверить фильтры;
- проверить блокировку и разблокировку;
- проверить пустое состояние;
- проверить мобильную ширину.

Формат ответа:
кратко указать, что изменено, какие файлы изменены и что проверить.

UI-задачи часто расползаются. Ограничения помогают удержать Codex в рамках одной страницы.

Пример 6. Промпт для миграции БД

Контекст проекта:
PHP 8.4, MariaDB, миграции хранятся в database/migrations. Изменения БД должны выполняться отдельными SQL-файлами.

Задача:
добавить таблицу избранных статей для пользователей.

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

Требования к БД:
- создать таблицу user_blog_favorites;
- поля: id, user_id, post_id, created_at;
- добавить уникальность пары user_id + post_id;
- добавить индексы для user_id и post_id;
- не менять существующую таблицу статей без необходимости.

Требования к коду:
- добавить методы добавления и удаления из избранного;
- проверять авторизацию;
- не позволять пользователю менять избранное другого пользователя;
- добавить CSRF-защиту для действий;
- все тексты интерфейса на русском языке.

Ограничения:
- не добавлять зависимости;
- не менять публичные URL статей;
- не ломать существующий блог;
- не выводить полный код в ответ.

Проверки:
- применить миграцию;
- добавить статью в избранное;
- повторно добавить ту же статью и проверить отсутствие дубля;
- убрать из избранного;
- проверить действия неавторизованного пользователя.

Формат ответа:
указать созданную миграцию, изменённые файлы и проверки.

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

Пример 7. Промпт для поиска причины ошибки

Контекст проекта:
PHP-проект без фреймворков. Ошибки пишутся в server error log и application log.

Задача:
найти причину ошибки 500 на странице /admin/prompts.

Симптомы:
страница открывалась раньше, но после последнего изменения стала возвращать 500. Белый экран появляется только в админке на списке промптов.

Что известно:
- авторизация работает;
- другие страницы админки открываются;
- ошибка возникает до вывода таблицы;
- недавно добавляли фильтр по статусу.

Файлы для проверки:
- app/routes.php
- app/views/admin/prompts.php
- app/Controllers/AdminPromptController.php
- app/Services/PromptService.php

Требования:
- найти точную причину;
- исправить минимально необходимым изменением;
- не переписывать список промптов;
- сохранить фильтр по статусу;
- если проблема в SQL, исправить запрос безопасно.

Ограничения:
- не отключать вывод ошибок глобально;
- не удалять фильтры;
- не менять структуру БД без необходимости;
- не добавлять зависимости.

Проверки:
- открыть /admin/prompts;
- проверить список без фильтра;
- проверить фильтр по каждому статусу;
- проверить пагинацию;
- проверить лог ошибок.

Формат ответа:
кратко указать причину ошибки, исправление, изменённые файлы и проверки.

Такой промпт не просит «чинить всё», а направляет Codex к диагностике.

Как писать промпт, если вы не знаете файлы

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

Задача:
найти, где реализована логика сохранения комментариев, и исправить проблему с отсутствием flash-сообщения после удаления.

Сначала:
- найди маршруты, связанные с комментариями;
- найди контроллер или обработчик удаления;
- найди view-файл списка комментариев;
- не вноси изменения, пока не определишь точку проблемы.

После этого:
- внеси минимальное исправление;
- сохрани текущую архитектуру;
- не меняй другие действия с комментариями.

Формат ответа:
укажи, где была найдена логика, что исправлено, какие файлы изменены и что проверить.

Если файлы неизвестны, важно ограничить область поиска и запретить широкие изменения.

Как писать промпт для большой задачи

Большую задачу лучше не отдавать одним куском. Её нужно разбить на этапы.

Плохо:

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

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

Лучше:

Сначала проведи аудит текущей страницы /admin/users.

Задача:
найти проблемы в структуре, UI, действиях, фильтрах и безопасности.

Ограничения:
- не меняй код на этом этапе;
- не предлагай полный редизайн;
- дай список проблем по приоритету.

Формат ответа:
таблица: проблема, риск, файл, рекомендация, приоритет.

После анализа можно дать второй промпт:

Теперь исправь только проблемы с высоким приоритетом на странице /admin/users.

Ограничения:
- не трогать другие страницы;
- не менять layout;
- не добавлять зависимости;
- сохранить существующие действия.

Формат ответа:
что исправлено, какие файлы изменены, что проверить.

Для больших задач этапность важнее скорости.

Что нельзя писать в промпте для Codex

Слабые формулировки:

Сделай нормально.

Переделай красиво.

Исправь всё.

Оптимизируй проект.

Наведи порядок.

Сделай как у больших сервисов.

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

Лучше заменять их конкретными требованиями.

Вместо:

Сделай красиво.

Пишите:

Приведи форму к единому стилю проекта: одинаковые input, select, textarea, label, кнопки, отступы и сообщения об ошибках.

Вместо:

Оптимизируй.

Пишите:

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

Вместо:

Исправь безопасность.

Пишите:

Проверь форму на CSRF, XSS, SQL-инъекции, проверку прав доступа и экранирование пользовательского контента.

Чеклист хорошего промпта для Codex

Перед отправкой задачи проверьте:

Если промпт проходит этот чеклист, задача для Codex становится намного безопаснее.

Готовый короткий шаблон для Codex

Контекст:
[кратко опиши проект, стек и важные правила]

Задача:
[что нужно сделать]

Проблема:
[что сейчас не работает или чего не хватает]

Ожидаемый результат:
[как должно работать после изменений]

Файлы:
[если известны — перечисли]

Требования:
- [требование 1]
- [требование 2]
- [требование 3]

Ограничения:
- не переписывать модуль с нуля;
- не менять архитектуру без необходимости;
- не добавлять зависимости без причины;
- не менять БД без миграции;
- не выводить полный код в ответ.

Проверки:
- [что проверить]

Формат ответа:
кратко: что сделано, какие файлы изменены, какие миграции применить, что проверить.

Этот шаблон подходит для большинства небольших задач.

Готовый шаблон для code review через Codex

Проведи code review.

Контекст проекта:
[стек, архитектура, важные правила]

Файлы для проверки:
- [файл 1]
- [файл 2]

Проверь:
- ошибки логики;
- безопасность;
- права доступа;
- валидацию;
- обработку ошибок;
- дублирование;
- слишком сложные методы;
- риск поломки существующего поведения.

Ограничения:
- не вноси изменения сразу;
- не переписывай код целиком;
- не давай абстрактные советы;
- каждую проблему привязывай к конкретному месту.

Формат ответа:
таблица:
1. Критичность.
2. Файл/место.
3. Проблема.
4. Риск.
5. Рекомендация.

В конце:
список правок по приоритету.

Code review лучше начинать с анализа. Автоматические правки стоит делать вторым этапом.

Готовый шаблон для безопасного рефакторинга

Проведи безопасный рефакторинг.

Контекст:
[описание проекта]

Файл или модуль:
[что нужно отрефакторить]

Проблема:
[почему нужен рефакторинг]

Цель:
сделать код проще для поддержки без изменения поведения.

Требования:
- сохранить публичное поведение;
- сохранить текущие маршруты;
- сохранить формат данных;
- не менять БД;
- разделить крупные методы, если это нужно;
- убрать дублирование, если оно есть.

Ограничения:
- не переписывать модуль с нуля;
- не менять бизнес-логику;
- не добавлять зависимости;
- не менять UI без необходимости.

Проверки:
- [сценарии, которые должны работать после рефакторинга]

Формат ответа:
что изменено, какие файлы затронуты, что проверить.

Главная фраза для рефакторинга: без изменения поведения.

Частые ошибки при постановке задач Codex

Ошибка 1. Слишком широкая задача

Плохо:

Переделай весь блог.

Лучше:

Исправь форму создания статьи: добавь сохранение SEO-заголовка и SEO-описания без изменения публичной части блога.

Ошибка 2. Нет ограничений

Плохо:

Сделай как считаешь нужным.

Лучше:

Работай в текущей архитектуре. Не добавляй зависимости, не меняй маршруты и не меняй БД без миграции.

Ошибка 3. Нет ожидаемого результата

Плохо:

Исправь сохранение.

Лучше:

После сохранения пользователь должен вернуться на страницу редактирования, увидеть flash-сообщение, а новые данные должны отображаться в форме.

Ошибка 4. Не указано, что делать с БД

Плохо:

Добавь новые поля.

Лучше:

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

Ошибка 5. Просить сразу менять код при code review

Плохо:

Проверь и исправь всё.

Лучше:

Сначала проведи code review и не меняй код. Дай список проблем по критичности. После этого я выберу, что исправлять.

Ошибка 6. Не просить проверки

Плохо:

Сделай задачу и всё.

Лучше:

После изменений укажи, какие сценарии нужно проверить вручную.

Ошибка 7. Разрешать полный переписанный модуль без необходимости

Плохо:

Перепиши модуль как лучше.

Лучше:

Внеси минимальные изменения для решения задачи. Не переписывай модуль с нуля.

FAQ

Можно ли дать Codex короткую задачу?

Можно, если задача простая и неопасная. Например: «переименуй текст кнопки в одном view-файле». Но для багов, миграций, авторизации, платежей, безопасности и рефакторинга нужен подробный промпт.

Нужно ли указывать файлы?

Желательно. Если вы знаете файлы, укажите их. Если не знаете, задайте область поиска: маршруты, контроллеры, сервисы, view-файлы, миграции. Это снижает риск лишних изменений.

Почему нельзя писать «исправь всё»?

Потому что это не задача, а неопределённое пожелание. Codex может затронуть слишком много кода и создать новые проблемы. Лучше разбивать работу на небольшие проверяемые задачи.

Нужно ли просить Codex выводить код в ответ?

Если Codex работает с файлами проекта напрямую, обычно не нужно. Лучше попросить краткий отчёт: что сделано, какие файлы изменены, какие миграции применить и что проверить.

Как безопасно ставить задачу на рефакторинг?

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

Что делать, если задача большая?

Разделить на этапы: сначала аудит или структура, потом точечные изменения, затем проверка. Большие промпты в стиле «сделай всё» почти всегда хуже по контролю.

Итог

Хороший промпт для Codex — это инженерная задача с понятными границами. В нём есть контекст проекта, конкретная проблема, ожидаемый результат, файлы, требования, ограничения, правила работы с БД, проверки и формат отчёта.

Codex полезен не тогда, когда ему дают команду «напиши код», а когда ему ставят задачу как разработчику: что изменить, зачем, где, по каким правилам и как проверить результат.

Чем точнее промпт, тем меньше риск случайных правок. Для разработки это критично: хороший результат — не просто работающий код, а изменение, которое не ломает архитектуру, безопасность, данные и уже существующие сценарии.