OSS Agent Playbook

Подготовка разных репозиториев к open source раз за разом требует одной и той же работы: понять, что проект действительно делает, проверить, что можно безопасно публиковать, привести в порядок путь первого запуска и подтвердить публичные обещания. OSS Agent Playbook превращает эту повторяющуюся часть в переносимый рабочий процесс для агентов с доступом к файлам проекта.

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

Один проход через репозиторий

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

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

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

Общие правила без потери локального контекста

Технологически нейтральное ядро состоит из Markdown-руководств об аудите, публичном интерфейсе репозитория, README, безопасности, воспроизводимости, инженерных проверках, релизах и рабочем процессе агента. Чек-листы собирают критерии готовности к публикации и повторному сопровождению.

Шаблоны для AGENTS.md, CLAUDE.md и PROJECT_AGENT_CONTEXT.md связывают ядро с конкретным проектом. Контекст проекта хранит проверенные команды, риски, границы публикации и выбранную ревизию Playbook. Опциональные технологические профили уточняют правила для отдельных технических границ; сейчас доступен черновой профиль docker-container-images.

Сам OSS Agent Playbook устроен по этой модели: инструкции, проверенные факты, принятые уроки мейнтейнера и история архитектурных решений живут в разных документах под контролем Git. Встроенный Python-скрипт без сторонних зависимостей проверяет структуру, ссылки и внутреннюю согласованность документации.

Использовать один раз или подключить надолго

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

Для повторного использования выбранную ревизию фиксируют полным SHA и помещают в .agent/oss-playbook. Рекомендуемый для публичного репозитория способ — squashed Git subtree без полной upstream-истории; также поддерживаются submodule и проверенная копия файлов. Короткие корневые инструкции направляют агента к нужным документам, а обновление Playbook проходит как обычное изменение зависимости: новую ревизию импортируют, проверяют и принимают отдельно.

Проект развивается как pre-1.0 референсная реализация. Он даёт агенту рабочий процесс и проверяемые критерии, а решение о публикации и принятии результата оставляет мейнтейнеру. Материалы распространяются по CC0 1.0: их можно копировать, адаптировать и подключать к собственным репозиториям.