Спецификация DWP

Текущий стандарт: v7 (DWP 7.0.0). Это сохраненная база спецификации v5 с расширениями жизненного цикла v6 и поколением контракта v7. Пакет 7.x по умолчанию создает новые планы в формате v7; явный запрос v6 по-прежнему материализует план v6, а существующие планы сохраняют записанное поколение. Манифест и контракт v7 опубликованы по адресам plan-manifest/v7.json и plan-contract/v7.json; текущий snapshot остаётся по адресу plan-snapshot/v6.json.

Версия 5.0.0. Статус: стабильная. Этот документ является нормативной спецификацией методологии Deep Work Plan (DWP). Ключевые слова MUST, MUST NOT, SHOULD, SHOULD NOT и MAY следует трактовать так, как описано в RFC 2119.

Аддитивно в 2.4.0, без ломающих изменений. (1) Раздел Затронутая поверхность — контракт между тем, что задача меняет, и тем, что должно быть провалидировано, с выбором gate по классу риска (изолированный / шов / разделяемый-ядро / неизвестный); (2) полная валидация становится требованием к финальному состоянию, выполняемым в единственном обязательном Final Review плана, с явными правилами повторного использования свидетельств; (3) задачно-локальные решения по skills переезжают в задачу-владельца, а Executive Report становится опциональным, по запросу; (4) режимо-зависимый поток create — trust-режим материализует план сразу, сохраняя анализ и проверки качества; (5) материализация в формате Lite по умолчанию — управляемый create создаёт сразу исполняемый Lite-план вместо неисполняемого черновика, который в любой момент может быть повышен до Full-плана (см. Lite-планы); и (6) явная матрица совместимости: планы и репозитории прежних версий остаются соответствующими.

Стандарт 4.0.0. Скачок версии выравнивает номер стандарта с продуктовой линейкой — 2.x исторический, стандарта 3.x не существует — и не меняет ни одного требования относительно 2.4.0. Планы и репозитории более ранних версий остаются конформными.

Определение

Deep Work Plan — это структурированный артефакт на основе только Markdown, описывающий сложную инженерную задачу, разложенную на последовательные, пригодные для ревью единицы работы, и предназначенный для создания, выполнения и сопровождения ИИ-агентами разработки, работающими автономно.

DWP является spec-driven: план — это спецификация, и агенты MUST выполнять работу по её явным критериям приёмки и validation gates, а не импровизировать. Спецификация, а не чат-транскрипт, является долговечным источником истины, поэтому работа проверяема и возобновляема между сессиями и агентами. Это также harness-инженерия, ставшая переносимой: контекст, цикл управления, ограничители и возобновляемое состояние, которые делают агента надёжным, устанавливаются в сам репозиторий как обычный Markdown, так что любой соответствующий агент MAY пилотировать репозиторий без фреймворка, привязанного к инструменту.

Поток create — один шаг, с учётом режима

Поток create один раз собирает цель, контекст, ограничения и набросок задач, выполняет свой анализ требований (охват, порядок зависимостей между задачами, выбор валидации из Затронутой поверхности, уровень пропорциональной строгости), а затем материализуется согласно режиму, выбранному разработчиком:

• Управляемый режим (по умолчанию). Поток материализует Lite-план напрямую — компактное, уже исполняемое предложение с инлайн-записями задач {#task-N}, пригодное для ревью за один проход — и просит разработчика оставить его как Lite, повысить до Full-плана, запросить правки или остановиться. Промежуточный неисполняемый черновик не создаётся.
• Trust-режим (trust / auto). Поток материализует выбранное представление (Lite, либо Lite с немедленным повышением до Full) напрямую, без этапа ревью — разработчик отказался от него. Анализ требований, порядок зависимостей и проверка качества плана всё равно выполняются: trust отменяет ревью, а не анализ. План в trust-режиме фиксируется как предварительно одобренный для автономного выполнения.

Оба режима определяют формат плана (Lite или Full) в рамках того же анализа требований, а не задним числом. См. Lite-планы — полное описание представлений, создания-и-выбора и жизненного цикла повышения.

Структура плана

Новый план MUST использовать пронумерованный каталог в .dwp/plans/, например PLAN_001_<slug>/, в одном из двух представлений. Существующие каталоги без номера PLAN_<slug>/ остаются допустимыми и не переименовываются:

• Full. Каталог MUST содержать README.md (обзор плана, цель, таблица задач и статус), по одному файлу на задачу с именем <n>.task_<slug>.md, и PROGRESS.md (текущий журнал выполнения).
• Lite. Компактные, полностью исполняемые записи задач находятся инлайн в README.md за стабильными якорями {#task-N} вместо отдельных файлов задач — каждая запись всё равно несёт цель, Затронутую поверхность, критерии приёмки, валидацию и журнал завершения. PROGRESS.md всё равно REQUIRED. Lite-план MAY быть повышен до Full в любой момент. См. Lite-планы — полный жизненный цикл, не дублируемый здесь.

План MAY дополнительно нести машиночитаемый слой состояния: manifest.json (статическая идентичность, записывается один раз при материализации) и state.json (живое пер-задачное состояние выполнения). Слой состояния RECOMMENDED для планов v5 и REQUIRED для автономного выполнения и для рабочих пространств агента без git. См. Состояние плана.

Новые планы получают монотонно возрастающие числовые ID длиной не менее трёх цифр (например, PLAN_001_add_payment_webhooks/). Замороженные схемы v5 считают числовой ID одним словом, поэтому slug v5 содержит 2–4 слова, а slug v6 и v7 — 2–5. Существующие папки без номера PLAN_<slug>/ остаются доступными для чтения и никогда не переименовываются. Если есть нумерованные планы, latest указывает на план с наибольшим числовым ID.

Анатомия задачи

Файл задачи

1. 01 Заголовок
2. 02 Контекст
3. 03 Прочитать перед началом
4. 04 Цель
5. 05 Затронутая поверхность
6. 06 Инструкции
7. 07 Критерии приёмки
8. 08 Результаты
9. 09 Валидация
10. 10 Чек-лист выполнения и Журнал завершения

Каждый файл задачи MUST содержать эти десять разделов по порядку:

1. Goal — формулировка в один абзац того, чего достигает задача.
2. Context — предыстория, ссылки и почему эта задача существует.
3. Затронутая поверхность — контракт между тем, что задача меняет, и тем, что должно быть провалидировано.
4. Steps — упорядоченные, конкретные действия для выполнения.
5. Acceptance criteria — чек-лист условий, определяющих готовность.
6. Validation — команды или тесты, которые нужно запустить для проверки, выбранные из Затронутой поверхности.
7. Files — пути, которые предполагается создать или изменить.
8. Dependencies — другие задачи или внешние предпосылки.
9. Risks — что может пойти не так и меры по смягчению.
10. Completion & Log — маркер статуса плюс хронологические заметки.

Задача MAY дополнительно включать раздел Delta (RECOMMENDED для изменений поведения в brownfield-сценарии — см. ниже) и раздел Rollback (RECOMMENDED для миграций, изменений инфраструктуры или развёртываний).

В плане v7 контракт результата также может пометить задачу как parallel_safe: это утверждение, задаваемое при создании, что задачу можно выполнить у делегата без чередования с соседней работой. Маркер ничего не разрешает без гранта agent_delegation в контракте (Делегирование).

Затронутая поверхность

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

• Планируемую поверхность — пути, модули, пакеты или конфигурацию, которые задача намерена изменить, записанные до редактирования.
• Фактическую поверхность — сверенный список после редактирования, взятый из реального диффа. Агент MUST сверить планируемую и фактическую поверхности до выбора gate.
• Затронутых потребителей — модули, пакеты или сервисы, зависящие от фактической поверхности, насколько это позволяет установить документированное сопоставление репозитория. Там, где не позволяет, запись MUST это указывать.
• Класс риска — один из: изолированный (ограничен одним модулем и его тестами); шов (меняет контракт, хранение, маршрутизацию, сериализацию, аутентификацию или связывание фреймворка между взаимодействующими сторонами); разделяемый/ядро (широко импортируется либо это изменение зависимости, миграции, конфигурации сборки/тестов, схемы или инструментария); неизвестный (сопоставление отсутствует, устарело или не проверено).
• Использованное сопоставление тестов — какое документированное сопоставление или какой инструмент дал этот выбор.
• Выбранный gate и обоснование — точные команды и то, почему они покрывают фактическую поверхность.

Файлы конфигурации, схемы, манифесты зависимостей, шаблоны, фикстуры, миграции и файлы инструкций для агентов могут менять поведение и MUST классифицироваться по своему эффекту, а никогда по расширению файла. Задача, которая меняет только прозу, комментарии или исследовательские артефакты, MAY объявить поверхность неприменимой и всё равно запускает нерантаймовые проверки репозитория.

Раздел Delta (brownfield-изменения)

Большинство реальной работы модифицирует существующее поведение, а не создаёт новое. Задача, изменяющая работу существующей системы, SHOULD нести раздел Delta, описывающий изменение как явный контракт «до/после» с тремя заголовками списка:

• ADDED — поведение, которое существует после задачи и не существовало до.
• MODIFIED — поведение, которое существует в обоих состояниях, формулируется как was: … → now: ….
• REMOVED — поведение, которое существовало до и намеренно отсутствует после.

Каждая запись MUST описывать наблюдаемое поведение — ответ эндпойнта, CLI-флаг, состояние UI, значение по умолчанию, — а не детали реализации. Раздел Delta — это ревью-дифф на уровне поведения: критерии приёмки проверяют записи ADDED/MODIFIED, а записи REMOVED — явное разрешение удалять. Всё, что не перечислено в REMOVED, MUST продолжать работать.

Validation gates — выбираются по классу риска

Валидация — это барьер, превращающий заявление о завершении в доказательство завершения: задача MUST NOT помечаться как завершённая, пока каждая команда из её раздела Validation не была запущена и не прошла успешно. Gate задачи, изменяющей поведение, выбирается из её сверенной Затронутой поверхности, по классу риска:

Изменение поведения MUST давать непустой, релевантный набор выбранных тестов — некорректный селектор или раннер, выбравший ноль тестов, покрытием не является. Там, где карта тестов репозитория устарела, выводится корректный вызов и фиксируется обновление сопоставления; небольшая отсутствующая команда никогда не требует полного прогона онбординга. Там, где нет вызова с ограниченным охватом, применяется полный подходящий набор — устаревшее поведение, а не ошибка.

Когда задача добавляет новую базовую функциональность или существенно изменяет существующее поведение, её критерии приёмки MUST включать автоматизированное тестовое покрытие нового или изменённого поведения, а её валидация запускает тесты репозитория вместе с проверками линтинга, типов и форматирования — а не только сборку. Существующие тесты MUST оставаться зелёными.

Валидация финального состояния

Пер-задачные gates валидируют то, чего коснулась каждая задача; они не заменяют валидацию плана как целого. До завершения плана полная подходящая валидация репозитория MUST запуститься и пройти на финальном релевантном состоянии, после последнего содержательного изменения — в Final Review. Более широкие прогоны раньше происходят на границах интеграции или после изменений разделяемого/ядра, а не по расписанию, привязанному к числу задач. Успешный результат MAY использоваться повторно только при наличии свидетельства, что релевантные входные данные эквивалентны; иначе он запускается заново. Каждый прогон gate оставляет краткую запись: команда, охват, ревизия, результат и путь к свидетельствам.

Дисциплина безопасности

Безопасность полноправна так же, как тесты, и следует той же двухслойной модели: пер-задачная дисциплина во время выполнения работы плюс проверка безопасности в Final Review над всем набором изменений в конце. Всякий раз, когда задача затрагивает аутентификацию или авторизацию, обработку ввода, секреты или конфигурацию, сетевую, файловую или shell-поверхность либо зависимости:

• Её критерии приёмки MUST формулировать ожидания по безопасности изменения — ввод проверен и экранирован, никакого секретного материала в коде или фикстурах, проверки аутентификации сохранены или усилены — в соответствии с docs/SECURITY.md.
• Каждый коммит MUST быть подтверждён как свободный от секретов или учётных данных до того, как он попадёт в основную ветку, включая тестовые фикстуры и примеры в документации. Секрет в отправленном коммите MUST трактоваться как утёкший и ротироваться, а не просто удаляться.
• Там, где чувствительная к безопасности работа существенна, выделенная задача харденинга SHOULD размещаться сразу после задач реализации и перед задачей комплексных тестов, чтобы находки исправлялись до того, как тесты закодируют поведение, и каждая находка становилась случаем регрессии, а не переделкой.

Эта пер-задачная дисциплина не заменяет проверку безопасности в Final Review: пер-задачные проверки ловят проблемы в коммите, где они рождаются, тогда как финальный барьер проверяет весь план — включая сами задачи тестов и документации.

Планка качества — проверено, а не заявлено

Суть DWP — проверенное качество: корректность, ясность, простота, безопасность, производительность и масштабируемость, доказанные, а не заявленные. Эти правила применяются к каждому плану и каждому агенту, который его продолжает (§5.1.4 файла DWP_SPECIFICATION.md из пакета DWP):

1. Gates — это гипотезы. Новый или изменённый gate MUST показать сбой на внесённом дефекте (или на дереве до изменения), прежде чем ему доверяют, и этот неуспешный прогон записывается. Пустой проход — отсутствующий бинарник, пустой ввод, ноль совпавших файлов или тестов, пустой лог, || true на финальном gate — это сбой. Конвейеры выполняются с pipefail (или код выхода сохраняется иным способом). Gate, который лишь ищет текст, написанный самим агентом, — это структурная защита, а не наблюдаемое свидетельство поведения. Задача с контрактом ввода называет в своих критериях приёмки граничные входные данные (пустые, многострочные, с пробельными символами в начале или в конце) — прохождение каждого примера не доказывает правило. Тест точного вывода проверяет его с помощью сигнального значения ([ "$(f x; printf s)" = $'y\ns' ]): $(…) отбрасывает завершающие переводы строки, поэтому вывод, который теряет или удваивает свой последний перевод строки, иначе прошёл бы.
2. Сравнивайте с базой. Производительность, покрытие и размер сравниваются с базовой веткой (или начальной ревизией плана), а не только с порогом; регрессия относительно базы сообщается, даже если порог по-прежнему соблюдён.
3. Сначала измеряйте. Задача 1 исправления, аудита или оптимизации проверяет свою предпосылку и измерительный инструмент до каких-либо изменений.
4. Проектирование до сборки. Нетривиальное изменение записывает свои интерфейсы, режимы отказа, позицию безопасности и план тестирования до написания кода.
5. Честность окружения. Gate выполняется в объявленном окружении — класс команды-обёртки для контейнеров, явный рабочий каталог, фиксированная локаль там, где сравнивается вывод. Сбой окружения — это блокер, который нужно устранить или о котором нужно сообщить, — никогда не проход и никогда не вина изменения.
6. Ревью до необратимого шага. Локальный AI Diff Review из Final Review запускается до любого слияния, тега или публикации, которые выполняет план, относительно базовой линии плана. Завершение плана сохраняет контракт ревью «никогда не блокировать» (отсутствующий ревьюер — это записанная находка local reviewer not installed); сам шаг слияния, тега или публикации остаётся заблокированным этой находкой, пока ревьюер не запустится или разработчик явно от него не откажется, — никогда не тихий пропуск. Изменения методологии, протокола и изменения, значимые для безопасности, SHOULD также получать ревьюера другого поставщика или агента.
7. Скупые свидетельства. analysis_results/ хранит отчёты, логи, дайджесты и указатели — никогда продукты, деревья зависимостей или вендорные копии; продукт получает собственный репозиторий или объявленную затронутую поверхность.
8. Непрерывность никогда не снижает планку. Агент-преемник наследует те же gates; пакет передачи не закрывает ни одного критерия, не ослабляет ни одного gate и не пропускает ни одного ревью (Автономия роя).

Жизненный цикл плана — Final Review

Каждый соответствующий план, созданный под эту версию, заканчивается ровно одной обязательной задачей: Final Review (задача N). Две обязанности, которые прежние версии размещали в отдельных закрывающих задачах, перенесены: решения по skills переезжают в задачу, породившую паттерн, а Executive Report становится опциональным артефактом по запросу. Ничто в проверке безопасности не ослаблено.

Final Review MUST, по порядку:

(a) Проверка безопасности — просмотреть весь накопленный набор изменений плана на предмет захардкоженных секретов, рисков инъекций, новой поверхности атаки, ослабленной аутентификации и чувствительных данных в логах или документации; проверить внесённые зависимости; убедиться, что docs/SECURITY.md по-прежнему отражает реальность; написать отчёт о проверке безопасности, даже если всё чисто. Критическая находка исправляется — или явно принимается пользователем — до завершения плана. Проверка включает обязательный локальный обзор AI Diff Reviewer по всему диапазону изменений плана; отсутствующий ревьюер — это зафиксированная находка local reviewer not installed, а не молчаливый пропуск.

(b) Валидация финального состояния — полная подходящая валидация репозитория запускается и проходит на финальном релевантном состоянии.

(c) Сверка решений по skills — каждая задача несёт решение по skills, и у каждого зафиксированного кандидата есть решение; никакого второго отчёта об обнаружении.

(d) Сверка документации — затронутая поверхность каждой задачи, изменяющей поведение, сверяется с документами, которые её регистрируют (сначала реестр gate, затем документация архитектуры и модулей, затем индекс AGENTS.md); пропуски исправляются в рамках ревью, а затронутые валидации перезапускаются.

(e) Завершение — записи плана согласованы (список задач, журнал прогресса и, в планах v6 и v7, снимок, производный от журнала, и квитанция); сообщить о завершении с перечнем результатов, свидетельствами валидации и ограничениями; один раз предложить Executive Report. План завершён независимо от того, был ли ответ на предложение.

Final Review выполняется последовательно после всех остальных задач и никогда не помещается в параллельную группу.

Задачно-локальные решения по skills

Вопрос «породила ли эта работа переиспользуемый паттерн, достойный skill или агента?» получает ответ внутри задачи, породившей паттерн, пока её свидетельства в контексте. Раздел Completion & Log каждой задачи несёт решение по skills: нет, обновить существующий skill, создать именованный артефакт либо отсрочка с причиной. Обоснованное создание происходит внутри этой задачи, до её validation gate и коммита, после проверки существующего каталога на дубликаты.

Executive Report — опционален, по запросу

Executive Report больше не является обязательной задачей. При завершении агент предлагает его один раз; он генерируется только по явному запросу и на основе устойчивых свидетельств, без переигрывания плана. Отсутствие ответа или автономный прогон оставляет план завершённым без сгенерированного отчёта.

Протокол завершения задачи

После прохождения валидации и перед переходом к следующей задаче агент MUST, по порядку: (1) пометить задачу [x] в плане README; (2) увеличить счётчик статуса плана; (3) заполнить Completion & Log задачи без placeholder-значений; (4) добавить запись из 3–5 пунктов в PROGRESS.md; (5) зафиксировать коммит (где план делает коммиты) в формате {type}({scope}): {description} — Task {N} of PLAN_{name}; (6) где план несёт слой состояния, атомарно перезаписать state.json — задача completed, gate-записи, запись outcome, хеш коммита.

Шесть шагов образуют одну логическую транзакцию. Агент, прерванный в середине протокола, MUST NOT начинать следующую задачу — он должен завершить или откатить частичное завершение.

Протокол возобновления DWP

Возобновление MUST быть возможным только по файлам плана плюс git log, без внешнего состояния. В рабочем пространстве без git — см. Архетипы §3 — state.json плана REQUIRED и заменяет git log.

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

1. Переориентация. Прочитать план README: цель, глобальные руководящие принципы, список задач.
2. Определение контрольной точки. Найти первую непомеченную задачу в README; прочитать git log и git status (или checkpoint в state.json, где git отсутствует).
3. Согласование состояния. Там, где state.json существует, сравнить его с чекбоксами README; при рассинхронизации регенерировать его из markdown до продолжения.
4. Осмотр шва. Прочитать Completion & Log задачи в точке возобновления и последнюю запись PROGRESS.md — последняя верифицированная опора предыдущей сессии.
5. Smoke-тест. Запустить дешевейшую постоянную валидацию репозитория, чтобы убедиться, что мир всё ещё работает, прежде чем строить на нём. Failing smoke-тест исследуется в первую очередь, а не игнорируется.
6. Атомарное продолжение. Выполнить ровно следующую задачу; не объединять задачи.

Агент MUST доверять пометкам завершения ([x]) и MUST NOT перевалидировать завершённые задачи, если пользователь явно не запрашивает это или smoke-тест не завершается с ошибкой, имплицирующей завершённую задачу.

Цикл выполнения

DWP определяет шесть операций над планом:

• create — создаёт новый план из цели.
• execute — выполняет план задача за задачей.
• refine — изменяет существующий план.
• resume — возобновляет прерванный план.
• status — отчитывается о статусе плана без выполнения.
• verify — проверяет соответствие репозитория и плана, только для чтения.

Ещё три под-навыка дополняют установленный пакет: onboard (делает репозиторий AI-first), author (создаёт или обновляет собственные skills, агентов и команды репозитория) и upgrade (переводит установленный навык на более новый релиз с согласия разработчика, никогда не мигрируя существующие планы). Маршрутизатор и эти девять под-навыков поставляются как единый пакет навыков.

Выходное рабочее пространство

Рабочее пространство вывода

• .dwp/ игнорируется git · одноразовое
• config.json
• plans/
• PLAN_001_<slug>/
• README.md
• PROGRESS.md
• <n>.task_<slug>.md
• manifest.json
• contract.json
• journal.ndjson
• state.json
• analysis_results/ отчёты
• SECURITY_REVIEW.md обзор безопасности
• EXECUTIVE_REPORT.md итоговый отчёт

Все артефакты DWP MUST жить в игнорируемом git-ом каталоге .dwp/ в корне репозитория.

Машиночитаемое состояние плана

План MAY нести машиночитаемый слой состояния — manifest.json (статическая идентичность) и state.json (живое пер-задачное состояние, gate-записи, записи outcome, контрольная точка, заблокированное состояние). Markdown-план остаётся источником истины; слой JSON — производная проекция, регенерируемая в протокольных точках и согласуемая при возобновлении.

Слой состояния RECOMMENDED для планов v5, REQUIRED для автономного выполнения и REQUIRED для рабочих пространств агента без git. Полное нормативное определение см. в Состоянии плана.

Пропорциональная строгость

Строгость MUST быть пропорциональна работе. Церемония при тривиальных изменениях — это провал методологии, а не дополнительная безопасность. Каждая единица работы попадает ровно в один уровень:

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

Работа уровня micro сохраняет non-negotiables: явная цель, validation gate, который запускается и проходит, и тестовая дисциплина для изменений поведения. Уровень меняет упаковку, но никогда не меняет gates.

Когда охват растёт в ходе работы — задача micro раскрывает реальный охват, у стандартного плана появляются суб-репозитории — агент MUST остановиться и повысить работу до следующего уровня, а не растягивать текущий.

Совместимость

Планы и репозитории прежних версий остаются соответствующими, и проверяющий соответствие MUST отличать известный устаревший артефакт (принимается) от артефакта, который объявляет эту версию и объективно недействителен в её рамках (отклоняется):

Версионирование

Эта спецификация следует семантическому версионированию.