index.htm

Как организовать работу AI-агента над репозиторием

Собрано нейросетью по моей исходной мысли и правкам.

На этой странице

Работу AI-агента удобнее организовать вокруг результата, который можно показать и проверить. Например: исправить обработку пустого ввода, сохранить формат ответа и подтвердить поведение существующим сценарием. Такая задача даёт точку завершения и помогает выбрать достаточный объём изменений.

OSS Agent Playbook применяет этот подход к подготовке существующих репозиториев к открытой публикации и дальнейшему сопровождению. Это публичный набор Markdown-руководств, шаблонов и проверок документации. Ниже — общий рабочий порядок для агента с доступом к файлам; конкретные команды и разрешённые действия задаёт проект.

Сформулируйте задачу через наблюдаемое поведение

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

Короткое задание может выглядеть так:

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

Дайте проверенный контекст репозитория

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

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

Не требуется заранее читать каждую папку и все возможные технологические профили. Для выбранной задачи достаточно найти вход, затронутую границу и её потребителей. Подключение дополнительных инструментов — отдельная работа; для этого есть руководство по настройке MCP в Codex.

Выберите небольшой законченный этап

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

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

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

Проверяйте то, что действительно поменялось

Проверка должна соответствовать обещанию. Для парсера важны подходящие входные данные; для архива — его содержимое; для инструкции запуска — воспроизводимый первый успешный сценарий. Команда сборки и реально опубликованный работающий экземпляр подтверждают разные состояния.

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

Полезно отдельно посмотреть итоговый diff и новые файлы. Так обнаруживаются случайно затронутые настройки, забытые примеры и различия между заявленным объёмом и полученным patch. Для публичного проекта также важны секреты, лицензирование и точность описанных возможностей: красивое оформление не компенсирует ложное обещание.

Передайте конкретный кандидат

Хорошая передача помогает следующему человеку быстро оценить результат:

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

Частые вопросы

Нужен ли большой файл AGENTS.md?

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

Playbook автоматически проверяет весь проект?

Он предоставляет руководства и детерминированную проверку собственной документации. В корне Playbook для неё предусмотрена команда python3 scripts/check_docs.py. Тесты приложения, сборка, упаковка и проверки выбранного технологического контура выполняются отдельно. Markdown-правила не заменяют sandbox или систему управления правами.

Где полезна контрольная точка?

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

Зелёные тесты означают, что задачу можно закрыть?

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