Как заставить Codex работать правильно. Постановка задач, контроль и проверка результата
- -
- 100%
- +
В официальной документации файл AGENTS.md описывается как файл описания в открытом формате, ориентированный на агентов, подходящий для записи структуры репозитория, команд выполнения, инженерных соглашений, запретов, а также определения того, «что считается завершением». Более конкретные правила, относящиеся непосредственно к текущему каталогу, могут переопределять правила верхнего уровня. [1]
Постоянные правила должны быть краткими и точными. Если при каждой ошибке вставлять весь отрывок чата, он превратится в накопленную историю, в которой никто не сможет определить приоритеты.
Четвёртый уровень: исполняемые ограничения
Если важные правила можно проверить автоматически, не ограничивайтесь их текстовым описанием. Например:
•
архитектурная проверка запрещает зависимости одного уровня от другого;
•
проверка доступа к релизам контролирует конфиденциальные поля и содержимое пакетов;
•
задачи должны выполняться в точной установке кеша, а не в репозитории разработки;
•
перед внешней публикацией должна существовать запись о ручном утверждении.
Документация указывает Codex, как следует поступать, а контроль доступа затрудняет незаметное прохождение отклонений.
Пятый уровень: независимая проверка и ретроспектива
Сложные поставки требуют проверки, способной опровергнуть вывод о «завершении». Рецензент должен исходить из требований и доказательств, а не просто повторять выводы исполнителя.
При обнаружении повторяющихся проблем анализ должен дать ответ: чего не хватало — однократного напоминания, постоянного правила или автоматического контроля доступа? Только при применении исправлений на правильном уровне проект станет по-настоящему более надежным.
Где следует разместить тот или иной опыт
Не все требования нужно записывать в файл AGENTS.md, и не все привычки должны превращаться в автоматические проверки.
Информация
Подходящее место
Причина
В данном случае изменяется только страница входа
Подсказки/задания данного раунда
Объем одноразовых изменений
Выполнение определённого набора тестов перед каждой отправкой
AGENTS.md
Долгосрочные соглашения репозитория
Запрещено записывать производственные ключи в репозиторий
AGENTS.md + автоматическое сканирование
Долгосрочные правила, подходящие для автоматического выполнения
Бюджет на данный раунд не должен превышать определенную сумму
Договор на выполнение задания
Связано с текущим разрешением
Еженедельное формирование отчёта
Возможность повторного использования рабочих процессов или автоматизации
Повторяется и выполняется в фиксированные сроки
Добавление регрессионных тестов после обнаружения аналогичных ошибок
Анализ + контроль доступа
Превращение опыта в системные возможности
Практическое правило:
если это действует только в данном случае — поместите в подсказку; если это постоянно актуально для данной задачи — поместите в соглашение; если это долгосрочно актуально для репозитория — запишите в правила проекта; если это необходимо выполнять каждый раз — превратите в контроль доступа; если это повторяется периодически — только тогда рассматривайте возможность автоматизации.
Различие между «общими подсказками» и «системой задач»
Измерение
Зависит только от общих указаний
Использование системы задач
Цель
Описание в начале один раз
Возможность вернуться к целевому результату на каждом этапе
Контекст
Однократная загрузка большого объема данных
Чтение актуальных данных в порядке приоритета
Изменения
Легко рассматривается как отклонение от первоначального плана
Новые факты вызывают явное обновление плана
Долгосрочные правила
Зависимость от истории чата
Добавляются в файл AGENTS.md или в соглашения по проекту
Проверка
Самопроверка исполнителя и подведение итогов
Многоуровневая система контроля доступа, фактического выполнения и независимой проверки
Неудача
Продолжить: добавить подсказки, переформулировать объяснение
Анализ того, к какому уровню относится ошибка, и закрепление исправлений
Система задач — это не просто набор дополнительных документов. Её цель, напротив, заключается в том, чтобы каждая информация появлялась только в нужном месте и имела чёткий приоритет.
Как запустить долгосрочную задачу
Приведенные ниже рекомендации подходят для многоэтапных проектов. Они не напишут за вас правила проекта, но помогут сначала создать правильную основу для совместной работы.
Это многоэтапная задача. Пока не приступайте к реализации, сначала создайте систему задач.
1. Считать файлы README, AGENTS.md, правила продукта и входные данные для проверки из текущего репозитория; 2. Составить список конфликтов данных и порядка авторитетности; 3. Разграничить текущие факты, историческое состояние, предположения и неизвестные данные; 4. Разбейте цель на этапы, которые можно выполнять и восстанавливать независимо друг от друга; 5. Описать для каждого этапа входные данные, результаты, доказательства проверки и условия остановки; 6. Отметить, какие правила относятся только к данной задаче, а какие должны стать постоянными правилами репозитория; 7. Указать, какие выводы требуют независимой проверки и не могут быть подтверждены самим исполнителем.
Сначала предоставьте договор о выполнении задачи и план первого этапа. Только после того, как первый этап будет успешно выполнен и проверен вручную, можно переходить к следующему этапу.
Если новые данные опровергают первоначальный план, сначала обновите факты, сферу воздействия и план; не продолжайте работу только для того, чтобы завершить старый список.
Три вопроса, которые нужно задать после каждого исправления отклонения
Когда вы обнаружите, что Codex снова допустил ошибку, не ограничивайтесь фразой «в будущем будем внимательнее». Задайте три вопроса:
Является ли это случайным недоразумением в рамках данного задания или оно будет повторяться в будущем?
Требуется ли для этого текстовое правило, или это можно проверить автоматически?
Где следует разместить новое правило: в подсказках текущего раунда, в договоре о задании, в файле AGENTS.md, в тестовом доступе или в процессе утверждения?
Например, в одном приложении для Windows когда-то возникала ситуация: «компиляция прошла успешно, но при запуске происходил сбой». Если просто сказать в чате «в следующий раз не забудь запустить», этот опыт быстро забудется. Только включив проверку точного пути запуска, проверку журнала событий и проверку процессов очистки в постоянную процедуру проверки, можно превратить урок, извлечённый из ошибки, в актив проекта.
Самопроверка системы задач
•
[ ] Подсказки данного раунда содержат только необходимую на данный момент информацию;
•
[ ] для сложных задач уже подготовлены обновлённые соглашения о задачах и планы этапов;
•
[ ] долгосрочные правила уже включены в постоянную документацию на уровне репозитория;
•
[ ] В ключевых правилах для частей, поддающихся автоматической проверке, уже установлены ограничения доступа;
•
[ ] Отчеты о реализации, фактическом выполнении и внешнем состоянии подаются отдельно;
•
[ ] Существует по крайней мере один механизм проверки, способный опровергнуть вывод исполнителя о завершении;
•
[ ] Правила, обсужденные в ходе ретроспективы, размещены на соответствующем уровне, а не остаются только в чате.
Хорошие подсказки позволяют улучшить качество ответа за один раз. Система задач же позволяет постоянно меняющемуся проекту, даже после нескольких раундов совместной работы, по-прежнему понимать, с чего он начался, чего нельзя делать и какие доказательства считаются достижением цели.
Основания и границы данной главы
•
Примеры платформ взяты из реального проекта хостинговой платформы, разработанного автором, и соответствующих файлов доказательств (C05), а также из матрицы взаимодействия с примерами; в данной главе обобщены только части, относящиеся к системе задач, полные инженерные доказательства приведены в главе 25.
•
[1] Официальные материалы OpenAI Codex:
«Codex Best Practices»
и
«Prompting
».
•
AGENTS.md, планирование и проверка — это инструменты разных уровней; конкретные доступные возможности и интерфейс могут меняться в зависимости от версии Codex и используемого интерфейса, поэтому в рукописи приведены только относительно стабильные методы.
Часть 2: Превращение идей в выполнимые задачи
В этой части рассмотрено преобразование расплывчатых пожеланий в целевые результаты, реалистичные базовые условия, авторитетный контекст, границы, полномочия и полное задание.
Глава 5. Не начинайте со списка функций
Суть этой главы: функции — это варианты реализации, а не требования. Сначала определите, что должен сделать пользователь, из какого состояния он должен перейти в какое, а затем позвольте Codex выбрать способ реализации.
Список, выглядящий очень профессионально
Предположим, вы хотите создать небольшую логическую игру и предоставляете Codex список:
•
область возможных ответов;
•
шаги рассуждения;
•
узлы доказательства;
•
Пошаговые подсказки;
•
Обратная связь при неудаче;
•
Система звезд;
•
полный анализ.
Этот список не содержит двусмысленностей. Codex может реализовать каждый пункт по отдельности, а тестирование — проверить каждый из них. Отчет о завершении будет выглядеть очень красиво.
Однако в списке не указано, что именно должен в конечном итоге сделать игрок. Должен ли он заполнить отчет о расследовании или, наблюдая за тремя уликами, самостоятельно вывести ответ в уме?
Обе эти цели могут использовать «подсказки, обратную связь при неудаче и разбор», но приведут к совершенно разным результатам.
Именно таким образом отклонился первый уровень ранней версии игры «Игра ума». Старая версия имела 12 вариантов ответа, семишаговый анализ и доказательство процесса, а внутренний набор доказательств давал результат 12/12 PASS. Руководитель проекта, увидев экран, указал: дедуктивные выводы игрока должны происходить в его голове, а система должна принимать только окончательный ответ.
Как только результат пользователя становится ясным, многие «функциональные требования» сразу превращаются в препятствия, которые следует устранить.
Почему список функций так привлекателен
У функциональных требований есть три преимущества: их можно сосчитать, по ним можно распределить обязанности и их можно проверить.
«Добавить три страницы» — это более чётко, чем «упростить пользователю поиск контента»; «добавить процесс подтверждения » — легче реализовать, чем «сделать головоломку более глубокой»; «создать отдельную страницу поиска» больше похоже на инженерную задачу, чем «улучшить опыт просмотра скриншотов для опытных пользователей».
Поэтому, когда результат не определён, команде легко заменить прогресс количеством функций.
Проблема в том, что функции отвечают только на вопрос «что есть в системе», но не на вопрос «что благодаря этому может сделать пользователь».
Продукт может иметь больше страниц, более длинные процессы и более обширные настройки, но при этом отдалять пользователя от цели. Codex снижает механические затраты на добавление функций, что, в свою очередь, требует от людей более строгого обоснования необходимости каждой функции.
Формулируйте требования в виде изменений состояния
Выполнимый результат для пользователя должен включать как минимум пять элементов:
Пользователь: кто использует;
Ситуация: в какой момент, с какой проблемой;
Отправная точка: что в настоящее время невозможно выполнить на сайте или какую цену приходится за это платить;
Конечная цель: что можно сделать после завершения задачи;
Доказательства: как можно убедиться, что изменения действительно произошли.
Можно выразить одной фразой:
Когда [пользователь] сталкивается с [текущим препятствием] в [сценарии], он может [выполнить целевое действие], что подтверждается [доказательством результата], при этом соблюдая [ключевые границы].
Уровень с паролем можно описать так:
Когда игрок впервые запускает первый уровень, он должен без изучения дополнительных инструкций понять три подсказки, ввести полный пароль и получить общую обратную связь; проверка осуществляется с помощью скриншота одного экрана, полного взаимодействия и повторения игроком при первом прохождении, при этом не раскрывая частично правильные ответы.
В этом предложении не указаны узлы Godot, названия элементов управления или структура кода, но его достаточно, чтобы отсеять кандидатов и подтвердить рабочую версию.
Целевое состояние должно также включать состояние неудачи
Описание только «что происходит в случае успеха» по-прежнему является неполным. Большая часть сложности реального продукта связана с: неполным вводом, сбоями в сети, конфликтами данных, недостаточными правами доступа, отменой действий пользователем и отсутствием ответа от внешних систем.
Целевое состояние уровня с вводом пароля включает не только «прохождение с правильным ответом», но и:
•
отсутствие ошибочного определения результата при незаполненных трех цифрах;
•
при полном неправильном ответе должен возвращаться только общий статус «неудача»;
•
после перезапуска все введенные данные должны возвращаться в исходное состояние;
•
отсутствие штрафов за пробы методом проб и ошибок в виде израсходования энергии, периода ожидания или обратного отсчёта.
То же самое касается поиска в ClipDock. «Возможность поиска» — это не полное состояние; необходимо, как минимум, указать: скрытые элементы не должны выделяться рамкой; как обрезается исходное выделенное множество; что отображается при нулевом результате; сохраняется ли порядок рабочих областей после завершения поиска.
Состояние неудачи — это не обрывки, добавленные тестировщиком в последнюю минуту, а часть результата, получаемого пользователем.
Сначала спросите: «Можно ли повторно использовать?», а потом: «Что нужно добавить?»
ClipDock когда-то реализовал поиск в виде отдельной страницы результатов. Постепенно он обзавелся шестью видами сортировки, собственной синхронизацией выбора, контекстным меню и пакетными операциями в нижней части экрана — и выглядел всё более полноценным.
Но на самом деле пользователю нужно лишь одно: быстро найти нужный контент на текущей рабочей области скриншота и продолжить использовать привычные функции выделения, контекстного меню, просмотра деталей и пакетных команд.
После того как руководитель проекта отклонил второй вариант продукта, в Codex удалили отдельную страницу поиска и перенесли поиск в виде фильтрации прямо на главном холсте. В связи с этими изменениями было добавлено 992 строки и удалено 2337 строк.
Настоящий прогресс заключается не в том, что «уменьшилось количество кода на 1345 строк», а в том, что система вновь построена вокруг одного и того же основного цикла пользователя.
Конец ознакомительного фрагмента.
Текст предоставлен ООО «Литрес».
Прочитайте эту книгу целиком, купив полную легальную версию на Литрес.
Безопасно оплатить книгу можно банковской картой Visa, MasterCard, Maestro, со счета мобильного телефона, с платежного терминала, в салоне МТС или Связной, через PayPal, WebMoney, Яндекс.Деньги, QIWI Кошелек, бонусными картами или другим удобным Вам способом.