Skip to content
Deep Work Plan сегодня на Product Hunt Поддержать
← Все документы спецификации

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

Версия 5.0.0. Этот стандарт определяет, как Deep Work Plan документируют свою структуру, задачи и прогресс, а также как репозиторий документирует сам себя, чтобы агент мог безопасно действовать по нему. Он применяется к каждому плану, созданному по методологии DWP. Эта версия приводит собственную версию документа в соответствие со стандартом DWP, который она сопровождает, — ни одно существующее требование не меняется, — и добавляет описанные ниже обеспечение бюджета компактного индекса и уровень признаков (feature tier). Ключевые слова 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/, которого не существует.

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

README плана

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

  • Title — # Deep Work Plan: <name>.
  • Goal — прозаическая формулировка цели плана.
  • Source material — ссылки или пути к каноническим исходным данным (необязательно).
  • Tasks — таблица Markdown с номером задачи, именем и флажком статуса.
  • Status — строка в форме <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, обновление существующего навыка или агента, именованное создание либо отсрочку с причиной и владельцем. Обоснованное создание происходит внутри задачи-владельца, до её validation gate, после проверки на дубликаты по каталогу .agents/; обоснованные записи фиксируются как стабильные кандидаты (T{task}-{seq}) в журнале кандидатов на skills этого плана.
  • Executive Report опционален, по запросу. Предлагается один раз при завершении; генерируется только по явному запросу на основе устойчивых свидетельств. Отсутствие ответа или автономный прогон оставляет план завершённым без отчёта.
  • Устаревшие планы. Планы, созданные под более ранние версии, заканчиваются тремя обязательными финальными задачами и остаются соответствующими — проверяющий соответствие MUST принимать такую форму.