Skip to content
← Все документы спецификации

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

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

Аддитивно в v1.2. Четыре аддитивных возможности, без ломающих изменений: (1) машиночитаемый слой состояния плана (manifest.json + state.json, см. Состояние плана); (2) уровни пропорциональной строгости (micro / standard / deep, см. Пропорциональная строгость); (3) необязательный раздел Delta в анатомии задачи для изменений поведения в brownfield-сценарии; (4) Протокол возобновления DWP повышен до именованного, цитируемого ритуала из шести шагов. Существующие планы v1.1 остаются conformant.

Определение

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

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

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

План MUST быть каталогом в .dwp/plans/ с именем PLAN_<slug>/. Каталог MUST содержать:

  • README.md — обзор плана, цель, таблица задач и статус.
  • По одному файлу на задачу с именем <n>.task_<slug>.md.
  • PROGRESS.md — текущий журнал выполнения.

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

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

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

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

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

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

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

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

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

Validation gates и тесты

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

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

  • Её критерии приёмки MUST включать автоматизированное тестовое покрытие нового или изменённого поведения (счастливый путь плюс значимые граничные и ошибочные случаи), в соответствии с тестовым соглашением репозитория и ожиданиями по покрытию.
  • Её валидация MUST запускать тесты репозитория вместе с его проверками линтинга, типов и форматирования — полную проверку качества кода, которую определяет репозиторий, — а не только сборку. «Оно собирается» не является достаточным барьером для изменения поведения.
  • Существующие тесты MUST оставаться зелёными. Изменение, ломающее тест, покрывающий затронутый код, MUST обновить этот тест до предполагаемого нового поведения; оно MUST NOT удалять, пропускать или ослаблять тест лишь для того, чтобы заставить барьер пройти.

Задачи, связанные исключительно с документацией, конфигурацией или исследованиями, освобождены от создания тестов, но всё же MUST запускать тот validation gate, который определяет репозиторий. Глубина тестирования пропорциональна размеру изменения и зрелости репозитория. Там, где у репозитория вообще нет инструментария для тестов или линтинга, агент MUST NOT молча пропускать эту дисциплину — он опирается на инструментарий, предложенный во время онбординга (см. Conformance).

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

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

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

Эта пер-задачная дисциплина не заменяет финальную задачу Security Review: пер-задачные проверки ловят проблемы в коммите, где они рождаются, тогда как финальный барьер проверяет весь план — включая сами задачи тестов и документации. Поэтому каждый план заканчивается тремя обязательными финальными задачами — Security Review, затем Skills & Agents Discovery, затем 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 — отчитывается о статусе плана без выполнения.

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

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

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

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

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

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

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

Уровень Когда Форма
micro Одно атомарное изменение: одна задача, примерно один сеанс, без координации. Исправление бага, правка текста, настройка конфигурации. Без папки плана. Агент формулирует цель, критерии приёмки и validation gate прямо в разговоре, выполняет, валидирует, фиксирует коммит.
standard Многошаговая работа с реальным охватом: фича, рефакторинг, миграция в одном репозитории. Уровень по умолчанию. Полный план: папка плана, задачи из девяти разделов, обязательные финальные задачи.
deep Долгосрочная работа, охватывающая параллельные группы, дочерние репозитории или множество автономных сессий. Стандартный план плюс возможности оркестратора и/или команды агентов, а также слой состояния.

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

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

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

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

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