Skip to content
← Wszystkie rozdziały

Rozdział 03

Szablony planu i zadań

Deep Work Plan to katalog plików Markdown. Kształt tego katalogu — i każdego pliku w nim — to właśnie to, co czyni plan podatnym na przegląd zarówno przez ludzi, jak i agentów.

Struktura planu

Plan to katalog w .dwp/plans/ o nazwie PLAN_001_<slug>/. Zawiera:

  • manifest.json — tożsamość planu i wskaźnik do jego aktywnego kontraktu, zapisywany jako pierwszy podczas materializacji.
  • contract.json — formalny kontrakt wykonawczy.
  • journal.ndjson — niezmienny dziennik zdarzeń.
  • state.json — migawka rzutowana z dziennika (journal), nigdy nieedytowana ręcznie.
  • README.md — przegląd planu: cel, materiały źródłowe, tabelę zadań i status.
  • Pliki zadań, nazwane <n>.task_<slug>.md.
  • PROGRESS.md — bieżący dziennik realizacji dopisywany wyłącznie na bieżąco.
  • analysis_results/ — wyniki analiz, raporty audytowe i dowody.

Aktualny pakiet 7.x domyślnie tworzy plany v7, ze slugami 2–5 słów, tak jak plany v6. Istniejące plany zachowują zapisaną generację; migracja wymaga wyraźnego polecenia. Nowe plany otrzymują monotonicznie rosnące identyfikatory liczbowe o długości co najmniej trzech cyfr (na przykład PLAN_001_add_payment_webhooks/). Zamrożone schematy v5 liczą identyfikator liczbowy jako jedno słowo, dlatego slug v5 ma 2–4 słowa, a slugi v6 i v7 mają 2–5. Istniejące nienumerowane foldery PLAN_<slug>/ pozostają czytelne i nigdy nie są przemianowywane. Jeśli istnieją plany numerowane, latest wskazuje plan o najwyższym identyfikatorze liczbowym.

Struktura pliku zadania

Każdy plik zadania nosi nazwę <n>.task_<slug>.md i podąża za dziesięciosekcyjną anatomią szczegółowo opisaną w Podstawowej pętli. Sekcje zawsze pojawiają się w tej samej kolejności, dzięki czemu czytelnik natychmiast wie, gdzie szukać. Każde zadanie ponownie zakotwicza się w celu planu, zanim zacznie działać, co chroni agenta przed dryfem na długim dystansie.

Final Review

Każdy plan musi kończyć się dokładnie jednym obowiązkowym zadaniem: Final Review. Zamyka on plan w pięciu uporządkowanych etapach — nic w przeglądzie bezpieczeństwa nie zostaje złagodzone:

  1. Przejście bezpieczeństwa z wymaganym przeglądem lokalnym — audyt wszystkiego, co plan zmienił, pod kątem sekretów, ryzyk iniekcji i nowej powierzchni ataku, utrzymywanie docs/SECURITY.md w aktualności oraz uruchomienie wymaganego lokalnego przeglądu AI Diff Reviewer w pełnym zakresie planu (brakujący recenzent jest rejestrowany jako ustalenie local reviewer not installed, nigdy niepomijany po cichu). Krytyczne ustalenie blokuje ukończenie.
  2. Walidacja stanu końcowego — pełne pakiety testów, linterów i sprawdzania typów uruchamiają się i przechodzą na ostatecznym stanie po ostatniej poprawce.
  3. Uzgodnienie decyzji dotyczących skilli — weryfikacja, że każde zadanie zapisało lokalną decyzję o skillach, z uzgodnieniem kandydatów w analysis_results/SKILLS_CANDIDATES.md.
  4. Uzgodnienie dokumentacji — powiązanie dotkniętej powierzchni każdego zadania zmieniającego zachowanie z dokumentacją (docs/TESTING_GUIDE.md, architektura, AGENTS.md).
  5. Ukończenie — rejestry planu są zgodne (lista zadań, dziennik postępu oraz w planach v6 i v7 migawka i pokwitowanie pochodzące z journal); zaraportowanie wyników, dowodów i ograniczeń oraz jednorazowe zaoferowanie Executive Report.

Konwencje README i PROGRESS

Plik README.md planu musi zawierać tytuł (# Deep Work Plan: <name>), prozą zapisane sformułowanie celu, opcjonalną sekcję materiałów źródłowych, tabelę zadań (numer, nazwa zadania, pole statusu) oraz linię statusu planu w postaci <n>/<total> tasks complete.

PROGRESS.md to dziennik realizacji wyłącznie dopisywany. Każdy wpis zapisuje znacznik czasu ISO 8601, numer i nazwę zadania, co zostało zrobione oraz wszelkie odstępstwa lub powody pominięcia. Ponieważ wyłącznie rośnie, jest wiarygodną historią tego, jak plan faktycznie się rozwijał.

Nagłówki i odsyłacze

Wszystkie nagłówki używają zapisu zdaniowego, a dokumenty unikają języka marketingowego i wykrzykników. Konwencje te utrzymują spójność planów między agentami i w czasie.