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

Версія 4.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 за замовчуванням — guided create одразу створює виконуваний Lite-план замість невиконуваної чернетки, який можна підвищити до Full-плану в будь-який момент (див. Lite-плани); та (6) явна матриця сумісності: плани й репозиторії з ранішніх версій залишаються відповідними.

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

Визначення

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

DWP є spec-driven: план є специфікацією, і агенти MUST виконувати за його явними критеріями приймання та валідаційними gate, а не імпровізувати. Специфікація — а не транскрипт чату — є стійким джерелом істини, тож робота є перевірюваною та відновлюваною між сесіями й агентами. Це також harness-інженерія, зроблена портативною: контекст, керувальний цикл, запобіжники та відновлюваний стан, що роблять агента надійним, встановлюються в сам репозиторій як звичайний markdown, тож будь-який відповідний агент MAY пілотувати репозиторій без фреймворку під конкретний інструмент.

Потік create — один крок, залежний від режиму

Потік create збирає мету, контекст, обмеження та контур завдань один раз, виконує свій аналіз вимог (scope, порядок залежностей між завданнями, вибір валідації з Торкнутої поверхні, рівень пропорційної строгості), а потім матеріалізує відповідно до режиму, який обрав розробник:

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

Обидва режими визначають формат плану (Lite чи Full) у межах того самого аналізу вимог, а не заднім числом. Див. Lite-плани — повний опис представлень, створення-і-вибору та життєвого циклу підвищення.

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

План MUST бути каталогом під .dwp/plans/ з назвою 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 для нових планів і REQUIRED для автономного виконання та для робочих просторів агентів без git. Див. Стан плану.

Анатомія завдання

Файл завдання

1. 01 Title
2. 02 Context
3. 03 Read Before Starting
4. 04 Goal
5. 05 Touched Surface
6. 06 Instructions
7. 07 Acceptance Criteria
8. 08 Outputs
9. 09 Validation
10. 10 Execution Checklist + Completion & Log

Кожен файл завдання 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 для міграцій, змін інфраструктури або розгортань).

Торкнута поверхня

Торкнута поверхня — це контракт між тим, що завдання змінює, і тим, що мусить бути валідованим. Вона існує, щоб валідація обиралася за ефектом, а не за звичкою, і щоб пізніший читач бачив, чому обрано той чи інший gate. Завдання, що змінює поведінку, MUST записати:

• Запланована поверхня — шляхи, модулі, пакети чи конфігурація, які завдання має намір змінити, записані до редагування.
• Фактична поверхня — узгоджений після редагування список, узятий із реального diff. Агент MUST узгодити заплановану та фактичну поверхні перед вибором gate.
• Зачеплені споживачі — модулі, пакети чи сервіси, що залежать від фактичної поверхні, настільки, наскільки може встановити задокументоване відображення репозиторію. Де воно не може, запис MUST це сказати.
• Клас ризику — один із: ізольована (обмежена одним модулем і його тестами); шов (змінює контракт, персистентність, маршрутизацію, серіалізацію, auth чи фреймворкове зʼєднання між колаборантами); спільна/ядро (широко імпортується, або зміна залежності, міграції, конфігурації збірки/тестів, схеми чи інструментарію); невідома (відображення відсутнє, застаріле або неперевірене).
• Використане тестове відображення — яке задокументоване відображення чи інструмент породив вибір.
• Обраний gate і причина — точні команди й те, чому вони покривають фактичну поверхню.

Конфігураційні файли, схеми, манифести залежностей, шаблони, фікстури, міграції та файли інструкцій агентів можуть змінювати поведінку і MUST класифікуватися за своїм ефектом, а ніколи не за розширенням файла. Завдання, що змінює лише прозу, коментарі чи артефакти дослідження, MAY оголосити поверхню непридатною та все одно запускає нон-рантайм перевірки репозиторію.

Секція Delta (зміни brownfield)

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

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

Кожен запис MUST бути спостережуваною поведінкою — відповідь ендпоінта, прапорець CLI, стан UI, значення за замовчуванням, — а не деталлю реалізації. Секція Delta є дифом рецензента на рівні поведінки: критерії приймання перевіряють записи ADDED/MODIFIED, а записи REMOVED є явним дозволом на видалення. Все, що не перелічено як REMOVED, MUST продовжувати працювати.

Валідаційні gate — вибір за класом ризику

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

Зміна поведінки MUST породжувати непорожній, релевантний вибір тестів — недійсний селектор чи раннер, що обрав нуль тестів, не є покриттям. Де тестове відображення репозиторію застаріле, правильний виклик виводиться, а оновлення відображення фіксується; невелика відсутня команда ніколи не потребує повного онбордингового прогону. Де не існує обмеженого виклику, застосовується повний придатний набір — застаріла поведінка, а ніколи не помилка.

Коли завдання додає нову основну функціональність або суттєво змінює наявну поведінку, його критерії приймання MUST включати автоматизоване тестове покриття нової чи зміненої поведінки, а його валідація запускає тести репозиторію разом із перевірками lint, типів і форматування — а не лише збірку. Наявні тести MUST залишатися зеленими.

Валідація кінцевого стану

Gate окремих завдань валідують те, що кожне завдання торкнулося; вони не замінюють валідацію плану як цілого. Перед завершенням плану повний придатний набір валідації репозиторію MUST бути запущений і пройти на кінцевому релевантному стані, після останньої суттєвої зміни — у Final Review. Ширші запуски раніше відбуваються на межах інтеграції або після спільних/ядрових змін, а не за розкладом на кількість завдань. Пройдений результат MAY бути повторно використаний лише з доказом, що релевантні входи еквівалентні; інакше він перезапускається. Кожен запуск gate лишає стислий запис: команда, scope, ревізія, результат та шлях до доказів.

Дисципліна безпеки

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

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

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

Життєвий цикл плану — Final Review

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

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

(a) Перевірка безпеки — ревʼю повного накопиченого набору змін плану на захаровані секрети, ризики інʼєкцій, нову поверхню атаки, послаблений auth і чутливі дані в журналах чи документації; аудит уведених залежностей; перевірка, що docs/SECURITY.md досі відображає реальність; написання звіту перевірки безпеки навіть коли все чисто. Критична знахідка виправляється — або явно приймається користувачем — перш ніж план завершується.

(b) Валідація кінцевого стану — повний придатний набір валідації репозиторію запускається й проходить на кінцевому релевантному стані.

(c) Узгодження skills — кожне завдання несе диспозицію skills, і кожен зафіксований кандидат має диспозицію; без другого звіту про виявлення.

(d) Завершення — відзвітувати про завершення з результатами, доказами валідації та обмеженнями; запропонувати Executive Report один раз. План є завершеним незалежно від того, чи отримано відповідь на пропозицію.

Final Review виконується послідовно після всіх інших завдань і ніколи не розміщується в паралельній групі.

Рішення щодо skills у межах завдань

На запитання «чи породила ця робота патерн, придатний для повторного використання, вартий скіла чи агента?» відповідається всередині завдання, що породило патерн, поки його докази в контексті. Completion & Log кожного завдання несе диспозицію skills: жодної, оновлення наявного скіла, створення іменованого артефакта або відкладення з причиною. Виправдане авторство відбувається всередині цього завдання, перед його валідаційним gate і комітом, після перевірки наявного каталогу на дублікати.

Executive report — опційний, на запит

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

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

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

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

Протокол відновлення DWP

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

Агент, що відновлює роботу, — нова сесія, інший агент, запланований поворот демона або хмарна сесія, що прокидається, — MUST виконати цей ритуал по порядку:

1. Переорієнтація. Прочитати README плану: мета, глобальні настанови, список завдань.
2. Знайти checkpoint. Знайти перше непозначене завдання в README; прочитати журнал git і git status (або checkpoint у state.json, де git відсутній).
3. Узгодити стан. Де state.json існує, порівняти його з прапорцями README; у разі десинхронізації перегенерувати його з markdown перед продовженням.
4. Оглянути шов. Прочитати Completion & Log завдання точки відновлення та останній запис PROGRESS.md — остання перевірена основа попередньої сесії.
5. Запустити дим-тест. Запустити найдешевшу наявну валідацію репозиторію, щоб підтвердити, що світ досі працює, перш ніж будувати на ньому. Дим-тест, що не проходить, досліджується спочатку, а не ігнорується.
6. Продовжити атомарно. Виконати рівно наступне завдання; не батчити наперед.

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

Цикл виконання

DWP визначає пʼять операцій:

• create — Згенерувати новий план із мети.
• execute — Виконати план завдання за завданням.
• refine — Змінити наявний план.
• resume — Відновити перерваний план.
• status — Відзвітувати про статус плану без виконання.

Робочий простір виводу

Робочий простір виводу

• .dwp/ ігнорується git · одноразове
• plans/
• PLAN_<name>/
• README.md
• PROGRESS.md
• <n>.task_<slug>.md
• analysis_results/ звіти
• SECURITY_REVIEW.md огляд безпеки
• EXECUTIVE_REPORT.md підсумковий звіт

Усі артефакти DWP MUST жити під каталогом .dwp/ у gitignore в корені репозиторію.

Машиночитаний стан плану

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

Рівень стану RECOMMENDED для нових планів, REQUIRED для автономного виконання та REQUIRED для робочих просторів агентів без git. Повне нормативне визначення — у Стані плану.

Пропорційна строгість

Строгість MUST бути пропорційною роботі. Церемонія над тривіальними змінами є невдачею методології, а не додатковою безпекою. Кожен обсяг роботи належить рівно до одного рівня:

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

Робота рівня micro все одно зберігає обовʼязкові елементи: явну мету, валідаційний gate, що запускається й проходить, та дисципліну тестування для змін поведінки. Рівень змінює пакування, але ніколи не gate.

Коли scope зростає в середині виконання — micro-завдання виявляє реальний scope, стандартний план породжує суб-репозиторії, — агент MUST зупинитися та підвищити роботу до наступного рівня, а не розтягувати поточний.

Сумісність

Плани й репозиторії з ранішніх версій залишаються відповідними, і перевірник відповідності MUST розрізняти відомий застарілий артефакт (приймається) та артефакт, що заявляє цю версію й обʼєктивно недійсний за нею (відхиляється):

Версіонування

Ця специфікація дотримується семантичного версіонування.