Первое изменение: от задачи до диффа

После исследования — первая правка. Задача должна быть маленькой и проверяемой: так вы увидите весь путь от постановки до коммита, не утонув в деталях. В этом уроке — что происходит на каждом шаге и где ваше участие обязательно.

Выбор задачи

Хорошая первая задача:

• занимает у человека 15–60 минут;
• затрагивает один-три файла;
• проверяется тестом, командой или открытием страницы.

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

Шаг 1. Ветка

Перед любой работой агента — чистое рабочее дерево и отдельная ветка:

git status                       # должно быть чисто
git switch -c task-1234-phone-validation

Ветка — ваша страховка: что бы ни сделал агент, вернуться к исходному состоянию — одна команда. Подробно — в уроке «Git как страховка».

Шаг 2. Постановка

Запустите codex в корне проекта без флагов — для git-репозитория это режим Auto: правки внутри проекта без вопросов, всё остальное — с одобрения. Опишите задачу так, чтобы у агента были цель, контекст, ограничения и критерий готовности:

Цель: в форме заявки на странице контактов поле «Телефон» должно принимать
только российские номера в формате +7XXXXXXXXXX; при ошибке — сообщение
«Укажите телефон в формате +7XXXXXXXXXX».

Контекст: обработчик формы — @plugins/acme/forms/components/ContactForm.php,
шаблон — @plugins/acme/forms/components/contactform/default.htm.

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

Готово, когда: есть тест на валидный и невалидный номер, и
`php artisan test --filter=ContactForm` проходит.

Подробно о такой структуре — в уроке «Как ставить задачу агенту». Сейчас главное: агент знает, что сделать, где, чего не трогать и как проверить.

Шаг 3. Агент работает

Дальше вы увидите цикл из урока «Как работает Codex»: агент читает файлы, иногда составляет план из нескольких шагов, вносит правки, запускает тесты, смотрит на ошибки, исправляет.

Ваша роль на этом шаге — наблюдать и вмешиваться при необходимости:

• Агент пошёл не туда — нажмите Enter и допишите указание прямо в текущий ход: «правило валидации уже есть в app/Rules/Phone.php, используй его».
• Агент просит одобрение — прочитайте, что именно он хочет сделать. Типичные запросы на этом шаге: доступ в сеть для установки пакета, запись вне каталога проекта. Если в задаче этого не должно быть — откажите и объясните почему.
• Хотите добавить что-то после — нажмите Tab: сообщение встанет в очередь и уйдёт, когда агент закончит текущий ход.

Шаг 4. Смотрим дифф

Когда агент сообщит, что закончил, не верьте отчёту — смотрите изменения. Внутри сессии:

/diff

Команда показывает git diff, включая новые файлы, которые git ещё не отслеживает. Читайте его так же, как читали бы MR коллеги:

• Изменено только то, что нужно? Нет ли «попутных» правок в несвязанных файлах?
• Понятно ли каждое изменение? Если нет — спросите: «зачем ты изменил X?»
• Тест действительно проверяет поведение, а не просто вызывает функцию? Есть ли случай с невалидным номером?
• Прошли ли тесты на самом деле? Найдите в выводе агента команду и результат.

Отчёт агента — краткое резюме, а не доказательство. Иногда агент пишет «все тесты прошли», запустив только часть, или не замечает упавшую проверку линтера.

Шаг 5. Доработка

Редко всё получается с первого раза идеально. Просите доработать в той же сессии — агент помнит контекст задачи:

Тест на невалидный номер проверяет только пустую строку. Добавь случаи
«89991234567» и «+7999123456» (на цифру короче). Сообщение об ошибке вынеси
в файл переводов плагина, как сделано для остальных полей.

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

Для второго мнения перед коммитом есть команда /review: отдельный ревьюер проверит изменения и выдаст приоритизированные замечания, ничего не меняя в рабочем дереве. Подробно — в уроке «Ревью кода командой /review».

Шаг 6. Коммит

Когда дифф прочитан и проверки прошли, закоммитьте. На первых порах делайте это сами — так вы точно знаете, что именно уходит в историю:

git add -p                       # по кускам, ещё раз глядя на изменения
git commit -m "task-1234 | Валидация телефона в форме заявки"

Можно поручить коммит и агенту. По умолчанию каталог .git защищён от записи даже в режиме Auto, поэтому git commit от агента потребует вашего одобрения — это нормально и полезно.