Specyfikacja DWP

Wersja 4.0.0. Status: stabilna. Ten dokument jest normatywną specyfikacją metodyki Deep Work Plan (DWP). Słowa kluczowe MUST (MUSI), MUST NOT (NIE MOŻE), SHOULD (POWINIEN), SHOULD NOT (NIE POWINIEN) i MAY (MOŻE) interpretuje się zgodnie z opisem w RFC 2119.

Addytywne w 2.4.0, bez zmian niekompatybilnych wstecz. (1) Sekcja Powierzchnia dotknięta — kontrakt między tym, co zadanie zmienia, i tym, co musi zostać zwalidowane, z doborem bramki według klasy ryzyka (izolowana / szew / współdzielony-rdzeń / nieznana); (2) pełna walidacja staje się wymogiem stanu końcowego uruchamianym w jedynym obowiązkowym Final Review planu, z jawnymi regułami ponownego użycia dowodów; (3) lokalne decyzje dotyczące skilli przenoszą się do zadania będącego właścicielem, a raport wykonawczy staje się opcjonalny, na życzenie; (4) przepływ create świadomy trybu — tryb trust materializuje się bezpośrednio, zachowując analizę i kontrole jakości; (5) materializacja Lite-first — guided create tworzy bezpośrednio wykonywalny plan Lite zamiast niewykonywalnego szkicu, który można w każdej chwili podnieść do planu Full (zob. Plany Lite); oraz (6) jawna macierz kompatybilności: plany i repozytoria z wcześniejszych wersji pozostają zgodne.

Standard 4.0.0. Skok wersji dopasowuje numer standardu do linii produktu — 2.x jest historyczny i nie istnieje standard 3.x — i nie zmienia żadnego wymagania względem 2.4.0. Plany i repozytoria z wcześniejszych wersji pozostają zgodne.

Definicja

Deep Work Plan to uporządkowany artefakt oparty wyłącznie na Markdown, opisujący złożone zadanie inżynierskie rozłożone na sekwencyjne, podatne na przegląd jednostki pracy, zaprojektowany tak, by tworzyły go, realizowały i utrzymywały agenci kodujący AI pracujący autonomicznie.

DWP jest spec-driven: plan jest specyfikacją, a agenci MUSZĄ pracować w odniesieniu do jej jawnych kryteriów akceptacji i bramek walidacyjnych, zamiast improwizować. Specyfikacja — a nie transkrypcja czatu — jest trwałym źródłem prawdy, dzięki czemu praca jest weryfikowalna i wznawialna między sesjami i agentami. To także harness engineering w przenośnej formie: kontekst, pętla sterująca, zabezpieczenia i wznawialny stan, które czynią agenta niezawodnym, instalowane są w samym repozytorium jako zwykły Markdown, więc każdy zgodny agent MOŻE pilotować repozytorium bez frameworka właściwego dla narzędzia.

Przepływ create — jeden krok, świadomy trybu

Przepływ create zbiera cel, kontekst, ograniczenia i zarys zadań raz, wykonuje swoją analizę wymagań (zakres, kolejność zależności między zadaniami, dobór walidacji z Powierzchni dotkniętej, poziom proporcjonalnej rygorystyczności), a następnie materializuje się zgodnie z trybem wybranym przez programistę:

• Tryb guided (domyślny). Przepływ materializuje plan Lite bezpośrednio — kompaktową, już wykonywalną propozycję z inline’owymi rekordami zadań {#task-N}, możliwą do przejrzenia w jednym przebiegu — i prosi programistę o zachowanie go jako Lite, podniesienie do planu Full, zgłoszenie poprawek lub zatrzymanie. Nie powstaje żaden pośredni niewykonywalny szkic.
• Tryb trust (trust / auto). Przepływ materializuje wybraną reprezentację (Lite, albo Lite z natychmiastowym podniesieniem do Full) bezpośrednio, bez etapu przeglądu — programista się go zrzekł. Analiza wymagań, kolejność zależności oraz kontrola jakości planu wciąż się wykonują: trust zrzeka się przeglądu, nie analizy. Plan w trybie trust jest zapisywany jako wstępnie zatwierdzony do wykonania nieobsługiwanego.

Oba tryby decydują o formacie planu (Lite lub Full) w ramach tej samej analizy wymagań, nigdy jako refleksja po fakcie. Zob. Plany Lite — pełny opis reprezentacji, tworzenia-i-wyboru oraz cyklu życia podniesienia.

Struktura planu

Plan MUSI być katalogiem w .dwp/plans/ o nazwie PLAN_<slug>/, w jednej z dwóch reprezentacji:

• Full. Katalog MUSI zawierać README.md (przegląd planu, cel, tabelę zadań i status), jeden plik na zadanie o nazwie <n>.task_<slug>.md, oraz PROGRESS.md (bieżący dziennik realizacji).
• Lite. Kompaktowe, w pełni wykonywalne rekordy zadań żyją inline w README.md za stabilnymi kotwicami {#task-N} zamiast osobnych plików zadań — każdy rekord nadal niesie cel, Powierzchnię dotkniętą, kryteria akceptacji, walidację i dziennik ukończenia. PROGRESS.md nadal jest WYMAGANY. Plan Lite MOŻE zostać podniesiony do Full w dowolnym momencie. Zob. Plany Lite — pełny cykl życia, zamiast go tu powielać.

Plan MOŻE dodatkowo zawierać warstwę stanu odczytywalnego maszynowo: manifest.json (statyczna tożsamość, zapisywana raz podczas materializacji) i state.json (aktywny stan realizacji poszczególnych zadań). Warstwa stanu jest ZALECANA dla nowych planów i WYMAGANA przy wykonaniu nieobsługiwanym oraz w przestrzeniach roboczych agenta bez gita. Zob. Stan planu.

Anatomia zadania

Plik zadania

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

Każdy plik zadania MUSI zawierać te dziesięć sekcji, w kolejności:

1. Cel — jednoakapitowe sformułowanie tego, co zadanie osiąga.
2. Kontekst — tło, odnośniki i powód istnienia tego zadania.
3. Powierzchnia dotknięta — kontrakt między tym, co zadanie zmienia, i tym, co musi zostać zwalidowane.
4. Kroki — uporządkowane, konkretne działania do wykonania.
5. Kryteria akceptacji — lista warunków definiujących ukończenie.
6. Walidacja — polecenia lub testy do uruchomienia w celu weryfikacji, dobrane z Powierzchni dotkniętej.
7. Pliki — ścieżki, które mają zostać utworzone lub zmodyfikowane.
8. Zależności — inne zadania lub zewnętrzne wymagania wstępne.
9. Ryzyka — co może pójść nie tak oraz środki zaradcze.
10. Ukończenie i dziennik — znacznik statusu plus chronologiczne notatki.

Zadanie MOŻE dodatkowo zawierać sekcję Delta (ZALECANA dla zmian zachowania w systemach istniejących — zob. poniżej) oraz sekcję Rollback (ZALECANA dla migracji, zmian infrastruktury lub wdrożeń).

Powierzchnia dotknięta

Powierzchnia dotknięta to kontrakt między tym, co zadanie zmienia, i tym, co musi zostać zwalidowane. Istnieje po to, by walidacja była dobierana według efektu, a nie z przyzwyczajenia, i by późniejszy czytelnik widział, dlaczego wybrano daną bramkę. Zadanie zmieniające zachowanie MUSI zapisać:

• Powierzchnię planowaną — ścieżki, moduły, pakiety lub konfigurację, które zadanie zamierza zmienić, zapisane przed edycją.
• Powierzchnię rzeczywistą — uzgodnioną listę po edycji, wziętą z rzeczywistego diffu. Agent MUSI uzgodnić powierzchnię planowaną z rzeczywistą przed wyborem bramki.
• Dotkniętych konsumentów — moduły, pakiety lub usługi zależne od powierzchni rzeczywistej, na tyle, na ile pozwala udokumentowane mapowanie repozytorium. Tam, gdzie nie pozwala, wpis MUSI to stwierdzać.
• Klasę ryzyka — jedną z: izolowana (ograniczona do jednego modułu i jego testów); szew (zmienia kontrakt, warstwę utrwalania, routing, serializację, uwierzytelnianie lub powiązania frameworka między współpracownikami); współdzielona/rdzeń (szeroko importowana albo zmiana zależności, migracji, konfiguracji budowania/testów, schematu lub łańcucha narzędzi); nieznana (mapowanie jest nieobecne, nieaktualne lub niezweryfikowane).
• Użyte mapowanie testów — które udokumentowane mapowanie lub narzędzie wygenerowało wybór.
• Wybraną bramkę i uzasadnienie — dokładne polecenia oraz to, dlaczego pokrywają powierzchnię rzeczywistą.

Pliki konfiguracyjne, schematy, manifesty zależności, szablony, fikstury, migracje i pliki instrukcji dla agentów mogą zmieniać zachowanie i MUSZĄ być klasyfikowane według swojego efektu, nigdy według rozszerzenia pliku. Zadanie, które zmienia wyłącznie prozę, komentarze lub artefakty badawcze, MOŻE zadeklarować powierzchnię jako nie dotyczy i wciąż uruchamia kontrole nieuruchomieniowe repozytorium.

Sekcja Delta (zmiany w systemach istniejących)

Większość prawdziwej pracy modyfikuje istniejące zachowanie, a nie tworzy nowe. Zadanie, które zmienia sposób działania istniejącego systemu, POWINNO zawierać sekcję Delta opisującą zmianę jako jawny kontrakt przed/po, używając trzech nagłówków list:

• ADDED — zachowanie, które istnieje po zadaniu, a nie istniało wcześniej.
• MODIFIED — zachowanie, które istnieje w obu stanach, podane jako was: … → now: ….
• REMOVED — zachowanie, które istniało wcześniej i jest celowo usunięte po zadaniu.

Każdy wpis MUSI być obserwowalnym zachowaniem — odpowiedzią endpointu, flagą CLI, stanem UI, wartością domyślną — a nie szczegółem implementacji. Sekcja Delta to diff recenzenta na poziomie zachowania: kryteria akceptacji weryfikują wpisy ADDED/MODIFIED, a wpisy REMOVED są jawnym zezwoleniem na usunięcie. Wszystko, co nie jest wymienione jako REMOVED, MUSI nadal działać.

Bramki walidacyjne — dobierane według klasy ryzyka

Walidacja jest bramką, która zamienia deklarację ukończenia w jego dowód: zadanie NIE MOŻE zostać oznaczone jako ukończone, dopóki każde polecenie z jego sekcji Walidacja nie zostanie uruchomione i nie przejdzie pomyślnie. Bramka zadania zmieniającego zachowanie jest dobierana z jego uzgodnionej Powierzchni dotkniętej, według klasy ryzyka:

Zmiana zachowania MUSI dawać niepusty, adekwatny wybór testów — nieprawidłowy selektor lub runner, który wybrał zero testów, nie jest pokryciem. Tam, gdzie mapa testów repozytorium jest nieaktualna, wyprowadza się prawidłowe wywołanie i zapisuje aktualizację mapowania; drobne brakujące polecenie nigdy nie wymaga pełnego przebiegu onboardingu. Tam, gdzie nie istnieje wywołanie o zawężonym zakresie, obowiązuje pełny stosowny zestaw — zachowanie zgodne ze starszą wersją, nigdy błąd.

Gdy zadanie dodaje nową kluczową funkcjonalność lub istotnie zmienia istniejące zachowanie, jego kryteria akceptacji MUSZĄ obejmować automatyczne pokrycie testami nowego lub zmienionego zachowania, a jego walidacja uruchamia testy repozytorium razem z kontrolami lintu, sprawdzania typów i formatowania — a nie samym budowaniem. Istniejące testy MUSZĄ pozostać zielone.

Walidacja stanu końcowego

Bramki na poziomie zadania walidują to, czego dotknęło każde zadanie; nie zastępują walidacji planu jako całości. Zanim plan zostanie ukończony, pełna stosowna walidacja repozytorium MUSI zostać uruchomiona i zaliczona na końcowym istotnym stanie, po ostatniej merytorycznej zmianie — w ramach Final Review. Szersze przebiegi wcześniej odbywają się na granicach integracji lub po zmianach współdzielonych/rdzenia, a nie według harmonogramu opartego na liczbie zadań. Zaliczony wynik MOŻE być użyty ponownie wyłącznie z dowodem, że istotne dane wejściowe są równoważne; w przeciwnym razie jest uruchamiany ponownie. Każdy przebieg bramki zostawia zwięzły zapis: polecenie, zakres, rewizję, wynik i ścieżkę do dowodów.

Dyscyplina bezpieczeństwa

Bezpieczeństwo jest pełnoprawne tak samo jak testy i podąża za tym samym dwuwarstwowym modelem: dyscyplina na poziomie zadania w trakcie pracy plus przegląd bezpieczeństwa Final Review nad całym zestawem zmian na końcu. Ilekroć zadanie dotyka uwierzytelniania lub autoryzacji, obsługi wejścia, sekretów lub konfiguracji, powierzchni sieci, plików lub shell, albo zależności:

• Jego kryteria akceptacji MUSZĄ określać oczekiwania bezpieczeństwa dotyczące zmiany — wejście zwalidowane i poddane escapowaniu, brak materiału sekretnego w kodzie lub fiksturach, kontrole uwierzytelniania zachowane lub wzmocnione — zgodnie z docs/SECURITY.md.
• Każdy commit MUSI zostać potwierdzony jako wolny od sekretów lub poświadczeń, zanim trafi do gałęzi, wliczając fikstury testów i przykłady w dokumentacji. Sekret w wypchniętym commicie MUSI być traktowany jako ujawniony i poddany rotacji, a nie jedynie usunięty.
• Tam, gdzie praca wrażliwa na bezpieczeństwo jest znacząca, dedykowane zadanie hardeningu POWINNO być umieszczone bezpośrednio po zadaniach implementacyjnych, a przed zadaniem kompleksowych testów, tak aby ustalenia były naprawione, zanim testy zakodują zachowanie, i aby każde ustalenie stawało się przypadkiem regresji, a nie ponowną pracą.

Ta dyscyplina na poziomie zadania nie zastępuje przeglądu bezpieczeństwa w Final Review: kontrole na poziomie zadania wychwytują problemy w commicie, w którym się rodzą, podczas gdy bramka końcowa audytuje cały plan — w tym same zadania testów i dokumentacji.

Cykl życia planu — Final Review

Każdy zgodny plan utworzony pod tę wersję kończy się dokładnie jednym obowiązkowym zadaniem: Final Review (zadanie N). Dwie odpowiedzialności, które wcześniejsze wersje umieszczały w osobnych zadaniach zamykających, zostają przeniesione: decyzje dotyczące skilli trafiają do zadania, które wytworzyło wzorzec, a raport wykonawczy staje się artefaktem opcjonalnym, na życzenie. Nic w przeglądzie bezpieczeństwa nie zostaje złagodzone.

Final Review MUSI, w tej kolejności:

(a) Przegląd bezpieczeństwa — przejrzeć pełny, skumulowany zestaw zmian planu pod kątem zakodowanych na sztywno sekretów, ryzyk iniekcji, nowej powierzchni ataku, osłabionego uwierzytelniania oraz danych wrażliwych w logach lub dokumentacji; zaudytować wprowadzone zależności; zweryfikować, że docs/SECURITY.md nadal odzwierciedla rzeczywistość; napisać raport z przeglądu bezpieczeństwa nawet wtedy, gdy jest czysto. Krytyczne ustalenie jest naprawiane — albo jawnie akceptowane przez użytkownika — zanim plan zostanie ukończony.

(b) Walidacja stanu końcowego — pełna stosowna walidacja repozytorium uruchamia się i przechodzi na końcowym istotnym stanie.

(c) Uzgodnienie decyzji dotyczących skilli — każde zadanie niesie rozstrzygnięcie dotyczące skilli, a każdy zapisany kandydat ma rozstrzygnięcie; bez drugiego raportu z odkrywania.

(d) Ukończenie — zgłoszenie ukończenia wraz z produktami pracy, dowodami walidacji i ograniczeniami; jednorazowa oferta raportu wykonawczego. Plan jest ukończony niezależnie od tego, czy oferta zostanie przyjęta.

Final Review wykonuje się sekwencyjnie po wszystkich pozostałych zadaniach i nigdy nie jest umieszczany w grupie równoległej.

Lokalne decyzje dotyczące skilli

Pytanie „czy ta praca wytworzyła wzorzec wielokrotnego użytku wart skilla lub agenta?” znajduje odpowiedź wewnątrz zadania, które wytworzyło ten wzorzec, dopóki jego dowody są w kontekście. Sekcja Ukończenie i dziennik każdego zadania niesie rozstrzygnięcie dotyczące skilli: brak, aktualizacja istniejącego skilla, utworzenie nazwanego artefaktu albo odroczenie z powodem. Uzasadnione tworzenie odbywa się wewnątrz tego zadania, przed jego bramką walidacyjną i commitem, po sprawdzeniu istniejącego katalogu pod kątem duplikatów.

Raport wykonawczy — opcjonalny, na życzenie

Raport wykonawczy nie jest już obowiązkowym zadaniem. Przy ukończeniu agent proponuje go raz; jest generowany wyłącznie na jawną prośbę, na podstawie trwałych dowodów, bez odtwarzania planu. Brak odpowiedzi lub przebieg nieobsługiwany pozostawia plan ukończony bez wygenerowanego raportu.

Protokół ukończenia zadania

Po zaliczeniu walidacji i przed przejściem do następnego zadania agent MUSI, w tej kolejności: (1) oznaczyć zadanie jako [x] w README planu; (2) zwiększyć licznik statusu planu; (3) wypełnić sekcję Ukończenie i dziennik zadania bez żadnych wartości zastępczych; (4) dodać wpis składający się z 3–5 punktów do PROGRESS.md; (5) wykonać commit (gdy plan dokonuje commitów) w formacie {type}({scope}): {description} — Task {N} of PLAN_{name}; (6) gdy plan zawiera warstwę stanu, atomowo nadpisać state.json — zadanie completed, rekordy bramek, rekord wyników, hash commita.

Sześć kroków tworzy jedną logiczną transakcję. Agent przerwany w środku protokołu NIE MOŻE rozpocząć następnego zadania — musi najpierw dokończyć lub cofnąć częściowe ukończenie.

Protokół wznowienia DWP

Wznowienie MUSI być możliwe wyłącznie na podstawie plików planu i dziennika git, bez zewnętrznego stanu. W przestrzeni roboczej bez gita — zob. Archetypy §3 — state.json planu jest WYMAGANY i zastępuje dziennik git.

Wznawiający agent — nowa sesja, inny agent, zaplanowana tura demona lub budząca się sesja chmurowa — MUSI wykonać ten rytuał, w tej kolejności:

1. Ponowne zakotwiczenie. Odczytanie README planu: cel, globalne wytyczne, lista zadań.
2. Zlokalizowanie punktu kontrolnego. Znalezienie pierwszego niezaznaczonego zadania w README; odczytanie dziennika git i statusu git (lub checkpoint z state.json tam, gdzie git jest nieobecny).
3. Uzgodnienie stanu. Tam gdzie istnieje state.json, porównanie go z polami wyboru README; przy desynchronizacji regeneracja z Markdown przed kontynuacją.
4. Zbadanie szwu. Odczytanie sekcji Ukończenie i dziennik zadania stanowiącego punkt wznowienia oraz ostatniego wpisu PROGRESS.md — ostatniego zweryfikowanego gruntu poprzedniej sesji.
5. Test dymny. Uruchomienie najtańszej stałej walidacji repozytorium w celu potwierdzenia, że świat nadal działa, zanim się na nim zbuduje. Nieudany test dymny jest najpierw badany, a nie budowany.
6. Kontynuacja atomowa. Wykonanie dokładnie następnego zadania; bez grupowania do przodu.

Agent MUSI ufać oznaczeniom ukończonym ([x]) i NIE MOŻE ponownie walidować ukończonych zadań, chyba że użytkownik jawnie o to poprosi lub test dymny zakończy się niepowodzeniem w sposób implikujący ukończone zadanie.

Pętla realizacji

DWP definiuje pięć operacji:

• create — Wygeneruj nowy plan na podstawie celu.
• execute — Realizuj plan zadanie po zadaniu.
• refine — Zmodyfikuj istniejący plan.
• resume — Wznów przerwany plan.
• status — Raportuj status planu bez realizacji.

Przestrzeń robocza wyników

Przestrzeń robocza wyjścia

• .dwp/ ignorowane przez git · jednorazowe
• plans/
• PLAN_<name>/
• README.md
• PROGRESS.md
• <n>.task_<slug>.md
• analysis_results/ raporty
• SECURITY_REVIEW.md przegląd bezpieczeństwa
• EXECUTIVE_REPORT.md raport wykonawczy

Wszystkie artefakty DWP MUSZĄ żyć w ignorowanym przez git katalogu .dwp/ w głównym katalogu repozytorium.

Stan planu odczytywalny maszynowo

Plan MOŻE zawierać warstwę stanu odczytywalną maszynowo — manifest.json (statyczna tożsamość) i state.json (aktywny stan poszczególnych zadań, rekordy bramek walidacyjnych, rekordy wyników, punkt kontrolny, stan zablokowania). Plan Markdown pozostaje źródłem prawdy; warstwa JSON jest pochodną projekcją, regenerowaną w punktach protokołu i uzgadnianą przy wznowieniu.

Warstwa stanu jest ZALECANA dla nowych planów, WYMAGANA przy wykonaniu nieobsługiwanym i WYMAGANA w przestrzeniach roboczych agenta bez gita. Pełna definicja normatywna znajduje się w Stan planu.

Proporcjonalna rygorystyczność

Rygorystyczność MUSI być proporcjonalna do pracy. Ceremonia przy trywialnych zmianach to błąd metodyczny, a nie dodatkowe bezpieczeństwo. Każda praca należy dokładnie do jednego poziomu:

Agent poproszony o stworzenie planu dla pracy na poziomie micro MUSI powiedzieć, że plan jest nieproporcjonalny, i zaproponować formę wbudowaną. Folder planu NIE MOŻE być tworzony dla trywialnej zmiany w jednym pliku.

Praca na poziomie micro wciąż zachowuje to, co niezbywalne: jawny cel, bramkę walidacyjną, która działa i przechodzi, oraz dyscyplinę testową dla zmian zachowania. Poziom zmienia opakowanie, nigdy bramki.

Gdy zakres rośnie w locie — zadanie micro odkrywa prawdziwy zakres, standardowy plan kiełkuje podrepozytoriami — agent MUSI się zatrzymać i awansować pracę do następnego poziomu, zamiast rozciągać bieżący.

Kompatybilność

Plany i repozytoria z wcześniejszych wersji pozostają zgodne, a mechanizm sprawdzania zgodności MUSI odróżniać znany artefakt starszej wersji (akceptowany) od artefaktu, który deklaruje tę wersję i jest w jej ramach obiektywnie nieprawidłowy (odrzucany):

Wersjonowanie

Ta specyfikacja podąża za wersjonowaniem semantycznym.