Skip to content
Deep Work Plan сьогодні на Product Hunt Підтримати
← Усі документи специфікації

Стандарт документації

Версія 5.0.0. Цей стандарт визначає, як Deep Work Plan документують свою структуру, завдання та прогрес, а також як репозиторій документує сам себе, щоб агент міг діяти на його основі безпечно. Він застосовується до кожного плану, створеного за методологією DWP. Ця версія узгоджує власну версію документа зі стандартом DWP, який він супроводжує — жодна наявна вимога не змінюється — і додає примусове виконання бюджету компактного індексу та рівень функцій, описані нижче. Ключові слова MUST, SHOULD та MAY вживаються згідно з RFC 2119.

AGENTS.md як компактна точка входу

Кореневий файл AGENTS.md SHOULD залишатися в межах бюджету 150–500 рядків. Коли згенерований або підтримуваний harness-ом вміст перевищує цей бюджет, агент MUST перенести деталі в посібник docs/ (або документ модуля/функції), який ними володіє, і послатися на нього з індексу — нічого не втрачається, лише переноситься, і індекс MUST посилатися на кожен документ, що отримав перенесений вміст. Наявний рукописний AGENTS.md, що перевищує бюджет, ніколи не переписується мовчки: агент пропонує конкретну міграцію (що куди переноситься, які посилання додаються) і застосовує її лише за згодою розробника. Перевірник відповідності трактує бюджет як дорадчий, оскільки кількість рядків обʼєктивна, а авторство — ні: MUST стосується harness, що генерує чи оновлює файл, а не здогадки перевірника про те, хто його написав. AGENTS.md MUST NOT посилатися на файл docs/, якого не існує.

Над рівнем документації для окремих модулів (нижче) стоїть рівень функцій: масштабна область можливостей — більша за один модуль — отримує власну теку docs/ поряд зі своїм кодом, з входом через власний README.md. Область кваліфікується, коли вона охоплює два чи більше основних модулі, володіє самодостатньою підтекою під-застосунку чи підсистеми, або несе власні контракти (поверхню API, контракти подій чи схем), від яких залежать кілька споживачів. Щойно область зафіксовано як масштабну, її функціональна docs/ SHOULD існувати, а її найзначущіші записи SHOULD бути звʼязані з модулями, які вона охоплює, і з кореневим індексом AGENTS.md, точно як документи окремих модулів. Область, свідомо залишена недокументованою, несе зафіксовану причину — рішення, а не недогляд.

README плану

Кожен план MUST мати README.md, що містить:

  • Заголовок — # Deep Work Plan: <name>.
  • Мета — прозовий виклад завдання плану.
  • Вихідний матеріал — посилання чи шляхи до канонічних вхідних даних (необовʼязково).
  • Завдання — markdown-таблиця з номером завдання, назвою та чекбоксом статусу.
  • Статус — рядок у формі <n>/<total> tasks complete.

Файли завдань

Кожен файл завдання MUST мати назву <n>.task_<slug>.md і містити десятисекційну анатомію — девʼять класичних секцій плюс Торкнута поверхня: контракт між тим, що завдання змінює, і тим, що мусить бути валідованим (запланована проти фактичної поверхні, зачеплені споживачі, клас ризику ізольована, шов, спільна/ядро чи невідомий, використане тестове відображення та обраний gate з його причиною).

PROGRESS.md

PROGRESS.md — це журнал виконання лише для додавання. Кожен запис MUST фіксувати:

  • Позначку часу ISO 8601.
  • Номер і назву завдання.
  • Що було зроблено.
  • Будь-які відхилення чи причини пропуску.

Маркери статусу

  • [ ] — не розпочато.
  • [~] — у процесі.
  • [x] — завершено.
  • [!] — заблоковано.

Заголовки

Усі заголовки MUST використовувати регістр речення. Документи SHOULD уникати маркетингової мови та знаків оклику.

Final Review, skills-рішення в межах завдань та опційний звіт

Кожен план, створений за цією версією, MUST завершуватися рівно одним обовʼязковим завданням: Final Review — перевіркою безпеки над повним набором змін плану, валідацією кінцевого стану на останньому релевантному стані та узгодженням рішень щодо skills. Критична безпекова знахідка блокує завершення.

  • Skills-рішення в межах завдань. Completion & Log кожного завдання несе диспозицію skills — none, оновлення наявного скіла чи агента, іменоване створення або відкладення з причиною та власником. Виправдане авторство відбувається всередині володіючого завдання, перед його валідаційним gate, після перевірки на дублікати за каталогом .agents/; виправдані записи фіксуються як стабільні кандидати (T{task}-{seq}) у журналі кандидатів skills плану.
  • Executive Report є опційним, на запит. Пропонується один раз при завершенні; генерується лише за явним запитом із довговічних доказів. Відсутня відповідь або автономний прогін лишає план завершеним без нього.
  • Застарілі плани. Плани, створені за ранішими версіями, завершуються трьома обовʼязковими фінальними завданнями та залишаються відповідними — перевірник відповідності MUST приймати цю форму.