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 залишаються відповідними.

Визначення

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

DWP є spec-driven: план є специфікацією, і агенти MUST виконувати за його явними критеріями приймання та валідаційними gate, а не імпровізувати. Специфікація — а не транскрипт чату — є стійким джерелом істини, тож робота є перевірюваною та відновлюваною між сесіями й агентами. Це також 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 продовжувати працювати, і саме валідаційний gate завдання (наявні тести залишаються зеленими) це забезпечує.

Валідаційні gate та тести

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

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

  • Його критерії приймання MUST включати автоматизоване тестове покриття нової чи зміненої поведінки (щасливий шлях плюс значущі граничні й помилкові випадки), згідно з тестовою конвенцією репозиторію та очікуванням щодо покриття.
  • Його валідація MUST запускати тести репозиторію разом із його перевірками lint, типів і форматування — повну перевірку якості коду, яку визначає репозиторій, — а не лише збірку. «Воно збирається» не є достатнім gate для зміни поведінки.
  • Наявні тести MUST залишатися зеленими. Зміна, що ламає тест, який покриває порушений код, MUST оновити цей тест до наміреної нової поведінки; вона MUST NOT видаляти, пропускати чи послаблювати тест лише задля того, щоб змусити gate пройти.

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

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

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

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

Ця подисциплінна робота над кожним завданням не замінює фінального завдання Security Review: подисциплінні перевірки ловлять проблеми в тому коміті, де вони народжуються, тоді як фінальний gate проводить аудит усього плану — включно із самими завданнями тестів і документації. Тому кожен план завершується трьома обовʼязковими фінальними завданнями — Security Review, потім Skills & Agents Discovery, потім 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 MUST жити під каталогом .dwp/ у gitignore в корені репозиторію.

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

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

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

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

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

Рівень Коли Форма
micro Одна атомарна зміна: одна проблема, приблизно один сеанс, без координації. Виправлення помилки, зміна тексту, налаштування конфігурації. Без папки плану. Агент формулює мету, критерії приймання та валідаційний gate в рамках розмови, виконує, валідує, комітить.
standard Багатокрокова робота з реальним scope: фіча, рефакторинг, міграція в одному репозиторії. Рівень за замовчуванням. Повний план: папка плану, дев’ятисекційні завдання, обов’язкові фінальні завдання.
deep Довгострокова робота, що охоплює паралельні групи, дочірні репозиторії або кілька автономних сесій. Стандартний план плюс можливості оркестратора та/або командних агентів, а також рівень стану.

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

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

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

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

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