Протокол агента

Область версии: это сохраненный базовый документ v5.0.0. Текущий стандарт, DWP 7.0.0, также требует применимые расширения V6_*.md и V7_*.md, перечисленные в указателе спецификации. Существующие планы v5 и v6 сохраняют записанные правила.

Версия 1.3. Этот протокол определяет, как ИИ-агент разработки MUST вести себя при работе с Deep Work Plan. Ключевые слова MUST, SHOULD и MAY следуют RFC 2119.

Аддитивно в v1.2. Два дополнения, без ломающих изменений: (1) автономные агентные платформы (OpenClaw, Hermes) вошли в таблицу поддерживаемых агентов; (2) раздел Профили выполнения определяет автономное выполнение — ограниченные полномочия, обязательный слой состояния, условия остановки и запланированное продолжение.

Коммуникация

1. Онбординг →
2. Планирование →
3. Выполнение →
4. Доработка →
5. Возобновление

↩ возобновляет выполнение

Безопасность управляет каждой фазой

Поддерживаемые агенты

Эта методология MUST поддерживать следующих ИИ-агентов разработки. Любой будущий агент, читающий markdown и умеющий выполнять вызовы инструментов, MAY быть добавлен без ломающих изменений.

Первые шесть — интерактивные агенты разработки с присутствием человека в сессии. OpenClaw и Hermes — автономные агентные платформы — долгоживущие демоны с запланированными поворотами — и, как правило, выполняют планы под профилем автономного выполнения (см. Профили выполнения) в рабочем пространстве агента (см. Архетипы §3).

Каждый поддерживаемый агент MUST рассматривать AGENTS.md как единственный источник истины для соглашений репозитория. Пер-агентный файл конфигурации MUST ссылаться на него и MUST NOT дублировать его содержимое.

Онбординг

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

Агент SHOULD определить:

• Архетип репозитория (отдельный репозиторий, хаб-оркестратор или рабочее пространство агента).
• Команды сборки, тестирования и линтинга.
• Существующие соглашения по стилю, структуре и именованию.
• Доступные навыки и агентов.

Инструментарий тестирования и валидации — существенный, а не необязательный контекст: validation gates составляют основу надёжных планов. Там, где репозиторий уже валидирует код, агент MUST зафиксировать его реальные команды для тестов, линтинга и проверки типов и соответствующее соглашение. Там, где у репозитория нет инструментария для тестов или линтинга, агент MUST NOT просто отметить его отсутствие — он MUST предложить инструментарий, подходящий стеку (фреймворк и раннер, соглашение об именовании тестовых файлов, разумную начальную цель по покрытию, а также инструменты линтинга, проверки типов и форматирования), задокументировать его как целевой в руководстве по тестированию и довести до сведения разработчика. Репозиторий без определённого способа валидировать своё поведение ещё не является AI-first.

Планирование

При создании плана агент MUST:

• Разложить цель на последовательные, пригодные для ревью задачи.
• Написать каждую задачу по анатомии из десяти разделов — Затронутая поверхность фиксирует, что задача меняет, и выбирает её validation gate по классу риска.
• Завершить единственным обязательным Final Review (проверка безопасности, валидация финального состояния, сверка решений по skills).
• Задать уточняющие вопросы, когда цель неоднозначна.

Выполнение

Во время выполнения агент MUST:

• Прочитать весь план перед началом.
• Выполнять задачи по порядку, если зависимости не позволяют иначе.
• Обновлять PROGRESS.md после каждой задачи.
• Точно отмечать статус задачи.
• Для любой задачи, добавляющей новую функциональность или изменяющей поведение, добавить или обновить автоматизированные тесты этого поведения и запустить тесты репозитория и проверки линтинга/типов перед тем, как пометить задачу завершённой; никогда не удалять и не пропускать тест, чтобы заставить барьер пройти.
• Для любой задачи, затрагивающей аутентификацию, обработку входных данных, секреты или конфигурацию, сетевую поверхность или зависимости, выполнить ожидания по безопасности, объявленные в её критериях приёмки, и перед коммитом убедиться, что дифф не содержит секретных данных.
• Переходить от пройденного gate к следующей задаче, не спрашивая подтверждения; при непройденном gate предпринимать исправления в рамках авторизованной области задачи — с конкретной гипотезой, прекращая слепые повторы после двух попыток без новых свидетельств.
• Останавливаться и спрашивать только на настоящей границе одобрения или при неразрешённом блокере, а не догадываться.

Доработка

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

Возобновление

При возобновлении агент MUST следовать Протоколу возобновления DWP, определённому в Спецификации DWP: переориентироваться по плану README, определить контрольную точку, сверить state.json с markdown, осмотреть шов, запустить smoke-тест, затем продолжить ровно со следующей задачи.

Коммуникация

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

Безопасность

Агенты MUST NOT фиксировать секреты в коммитах, MUST держать .dwp/ игнорируемым git-ом и SHOULD спрашивать перед разрушительными операциями. Онбординг MUST быть недеструктивным: агент MUST обнаруживать существующие файлы и согласовывать их, а не перезаписывать, и MUST получать явное одобрение перед заменой или удалением чего-либо, что уже есть у пользователя.

Методология построена на принципе Markdown-first: она не выполняет сетевых вызовов и не передаёт никакой телеметрии, а агент MUST NOT выгружать исходный код или секреты. Перед установкой навыка агент SHOULD обращаться с полученным содержимым онбординга как с ненадёжными входными данными, подтверждать его происхождение из официальных источников и проверять выпуск по опубликованным контрольным суммам.

Профили выполнения

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

Интерактивный (по умолчанию)

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

Автономный (Unattended)

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

• Предварительно одобренный план. План был одобрен до любого автономного поворота — в управляемом режиме человек одобрил напрямую материализованный план; в trust-режиме явная инструкция trust от разработчика и есть зафиксированное одобрение. Агент MUST NOT создавать и выполнять план автономно в одном повороте без любого из них; одобрение плана — контрольная точка для человека.
• Слой состояния REQUIRED. План MUST нести manifest.json и state.json, чтобы любая последующая сессия — агента или человека — могла прочитать точный прогресс без воспроизведения транскрипта. См. Состояние плана.
• Ограниченные полномочия. Полномочия агента — это план: он MUST NOT расширять область, MUST NOT выполнять деструктивные или направленные вовне действия, явно не авторизованные планом, и MUST NOT растягивать инструкции задачи, чтобы охватить обнаруженную, но незапланированную работу — обнаруженная работа записывается для следующего refine, а не импровизируется.
• Одна атомарная задача за поворот, gates всегда. Каждый поворот выполняет Протокол возобновления DWP, выполняет не более следующей задачи, проходит её validation gate, завершает задачу по протоколу завершения задачи и завершается. Failing gate — это условие остановки, но никогда не «продолжить в любом случае».

Условия остановки и эскалация

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

1. Validation gate завершается с ошибкой, и исправление выходит за рамки области задачи.
2. Задача требует одобрения, учётных данных или решения, которые план не предавторизовал.
3. Реальность расходится с допущениями плана (отсутствующий файл, изменённый API, конфликтующая параллельная работа или рассинхронизация, которую согласование не может разрешить).
4. Два последовательных поворота не дают никакого верифицируемого прогресса по одной и той же задаче.

Остановка — это успех, а не провал: запись blocked — это сообщение об эскалации. Канал уведомлений платформы SHOULD доставить его; человек (или сессия refine) разблокирует, и следующий запланированный поворот возобновится в штатном режиме.

Запланированное продолжение

На платформах с планированием — heartbeat или cron OpenClaw, cron Hermes, пробуждение облачного агента — продолжение MUST выражаться как: пробудиться → выполнить Протокол возобновления DWP → если blocked, сообщить и завершиться → иначе выполнить следующую атомарную задачу → обновить слой состояния → завершиться. Единицей непрерывности является план, а не сессия; план MUST пережить перезапуск платформы, смену модели или подхват следующего поворота другим агентом.

Таксономия эскалации

Всё, что ниже не перечислено как критическое, решает агент: он исследует, выбирает рекомендуемый вариант, записывает решение — в разделе «Decisions» файла PROGRESS.md или в decisions[] пакета передачи: варианты, выбор, причину и способ его отменить — и продолжает. Проверка механическая: эскалация MUST называть свой класс; вопрос, не называющий никакого класса, — это решение, которое агент должен принять сам. Это §7.5 файла AGENT_PROTOCOL.md из пакета DWP.

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

Три ограничения сохраняют автономию честной:

1. Автономия никогда не закрывает человеческий gate. Критерий или контрольная точка, требующие подписи человека, выполняются только этим человеком и никогда — постоянной инструкцией «будь автономен» или trust.
2. Буквальные слова разработчика побеждают. Когда рекомендуемый вариант противоречит тому, о чём разработчик буквально попросил, выпустите обратимый вариант, который соблюдает запрос, и запишите рекомендацию (C3, если обратимого варианта нет).
3. Полномочия не транзитивны. Пересланное одобрение не добавляет полномочий; агент сам читает авторизацию плана. Полномочия человека хранятся дословно в папке плана; агент, который их пересылает, записывает «переслано агентом <agent>».

Объединяйте вопросы. Критические вопросы, которые могут подождать, собираются и задаются вместе в одной запланированной точке, каждый со своим рекомендуемым вариантом по умолчанию, чтобы разработчик ответил один раз. В запуске с несколькими агентами критический вопрос блокирует свою цепочку зависимостей, а не весь запуск: ведущий агент паркует заблокированную задачу — её запись blocked в state.json, заполненная как в условиях остановки выше, и есть эскалация, отправленная один раз через канал отчётности, — продолжает работу каждого независимого агента и возобновляет цепочку, когда разработчик отвечает. Условия остановки остаются правилом для одного плана; ведущий агент применяет их к каждой цепочке. Как это применяет рой агентов, описано в главе Автономия роя.