DWP spesifikasyonu

Sürüm 4.0.0. Durum: Kararlı. Bu belge, Deep Work Plan (DWP) metodolojisinin normatif spesifikasyonudur. MUST, MUST NOT, SHOULD, SHOULD NOT ve MAY anahtar kelimeleri, RFC 2119’da açıklandığı şekilde yorumlanacaktır.

2.4.0’da eklemeli, kırıcı değişiklik yok. (1) Dokunulan Yüzey bölümü — görevin neyi değiştirdiği ile neyin doğrulanması gerektiği arasındaki sözleşme, risk sınıfına göre kapı seçimiyle (izole / seam / paylaşılan-çekirdek / bilinmeyen); (2) eksiksiz doğrulama, planın tek zorunlu Final Review’inde, açık kanıt-yeniden-kullanım kurallarıyla çalıştırılan bir son-durum gereksinimi hâline gelir; (3) görev-yerel skill kararları sahipli göreve taşınır ve Executive Report isteğe bağlı, talep üzerine hâline gelir; (4) mod-farkındalıklı bir create akışı — trust modu, analiz ve kalite denetimlerini korurken planı doğrudan somutlaştırır; (5) bir Lite-first plan somutlaştırması — yönlendirilmiş create, yürütülemeyen bir taslak yerine doğrudan yürütülebilir bir Lite plan üretir; bu plan istenildiği an bir Full plana yükseltilebilir (bkz. Lite planlar); ve (6) açık bir uyumluluk matrisi: önceki sürümlerden planlar ve depolar uyumlu kalır.

Standart 4.0.0. Sürüm sıçraması, standardın numarasını ürün hattıyla hizalar — 2.x tarihtir ve 3.x standardı yoktur — ve 2.4.0’a göre hiçbir gerekliliği değiştirmez. Önceki sürümlerin planları ve depoları uyumlu kalır.

Tanım

Bir Deep Work Plan, karmaşık bir mühendislik görevini ardışık, gözden geçirilebilir iş birimlerine ayrılmış biçimde tanımlayan, yapılandırılmış, yalnızca Markdown’dan oluşan bir yapıdır; otonom çalışan yapay zeka kodlama ajanları tarafından oluşturulmak, yürütülmek ve sürdürülmek üzere tasarlanmıştır.

DWP spec odaklıdır: plan spesifikasyondur ve ajanlar, doğaçlama yapmak yerine onun açık kabul kriterlerine ve doğrulama kapılarına karşı çalışMAK ZORUNDADIR. Bir sohbet dökümü değil, spesifikasyon kalıcı doğruluk kaynağıdır; böylece iş, oturumlar ve ajanlar arasında doğrulanabilir ve sürdürülebilirdir. Bu aynı zamanda taşınabilir hale getirilmiş harness mühendisliğidir: bir ajanı güvenilir kılan bağlam, kontrol döngüsü, güvenlik bariyerleri ve sürdürülebilir durum, deponun kendisine düz Markdown olarak kurulur; böylece uyumlu herhangi bir ajan, araca özgü bir çerçeve olmadan depoyu pilotlayABİLİR.

Create akışı — tek adım, mod-farkındalıklı

create akışı hedefi, bağlamı, kısıtları ve görev taslağını bir kez toplar, gereksinim analizini gerçekleştirir (kapsam, görevler arası bağımlılık sıralaması, Dokunulan Yüzey’den doğrulama seçimi, orantılı-titizlik kademesi) ve ardından geliştiricinin seçtiği moda göre somutlaştırır:

• Yönlendirilmiş mod (varsayılan). Akış, doğrudan bir Lite plan somutlaştırır — inline {#task-N} görev kayıtlarına sahip, tek geçişte gözden geçirilebilir, kompakt ve zaten yürütülebilir bir öneri — ve geliştiriciden onu Lite olarak koruma, bir Full plana yükseltme, değişiklik isteme veya durdurma arasında seçim yapmasını ister. Ara, yürütülemeyen bir taslak üretilmez.
• Trust modu (trust / auto). Akış, seçilen temsili doğrudan somutlaştırır (Lite, ya da hemen ardından Full’a yükseltilen Lite), gözden geçirme adımı olmadan — geliştirici bundan feragat etmiştir. Gereksinim analizi, bağımlılık sıralaması ve bir plan-kalite denetimi yine de çalışır: trust, gözden geçirmeden feragat eder, analizden değil. Trust modundaki bir plan, gözetimsiz yürütme için önceden onaylanmış olarak kaydedilir.

Her iki mod da planın biçimini (Lite veya Full) aynı gereksinim analizinin bir parçası olarak belirler, asla sonradan akla gelen bir düşünce olarak değil. Tam temsil, oluşturma-ve-seçim ile yükseltme yaşam döngüsü için bkz. Lite planlar.

Plan yapısı

Bir plan, .dwp/plans/ altında PLAN_<slug>/ olarak adlandırılmış bir dizin OLMALIDIR; iki temsilden biri biçiminde:

• Full. Dizin, README.md (plan genel görünümü, hedef, görev tablosu ve durum), görev başına bir dosya (<n>.task_<slug>.md olarak adlandırılır) ve PROGRESS.md (yürütmenin çalışan bir günlüğü) İÇERMELİDİR.
• Lite. Kompakt, tam olarak yürütülebilir görev kayıtları, ayrı görev dosyaları yerine, kararlı {#task-N} çapaları arkasında README.md içinde satır içi yaşar — her kayıt yine de bir hedef, bir Dokunulan Yüzey, kabul kriterleri, doğrulama ve tamamlanma günlüğü taşır. PROGRESS.md hâlâ ZORUNLUDUR. Bir Lite plan herhangi bir anda Full’a YÜKSELTİLEBİLİR. Tam yaşam döngüsü için burada yinelemek yerine bkz. Lite planlar.

Bir plan ek olarak makine tarafından okunabilir durum katmanını TASIYABİLİR: manifest.json (somutlaştırma sırasında bir kez yazılan statik kimlik) ve state.json (görev bazında canlı yürütme durumu). Durum katmanı yeni planlar için ÖNERİLİR ve gözetimsiz yürütme ile git içermeyen ajan çalışma alanları için ZORUNLUDUR. Bkz. Plan durumu.

Görev anatomisi

Görev dosyası

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

Her görev dosyası, sırasıyla bu on bölümü İÇERMELİDİR:

1. Hedef — görevin neyi başardığına dair tek paragraflık bir bildirim.
2. Bağlam — arka plan, bağlantılar ve bu görevin neden var olduğu.
3. Dokunulan Yüzey — görevin neyi değiştirdiği ile neyin doğrulanması gerektiği arasındaki sözleşme.
4. Adımlar — gerçekleştirilecek sıralı, somut eylemler.
5. Kabul kriterleri — “bitti”yi tanımlayan koşulların bir kontrol listesi.
6. Doğrulama — doğrulamak için çalıştırılacak komutlar veya testler, Dokunulan Yüzey’den seçilir.
7. Dosyalar — oluşturulması veya değiştirilmesi beklenen yollar.
8. Bağımlılıklar — diğer görevler veya harici ön koşullar.
9. Riskler — neyin ters gidebileceği ve azaltıcı önlemler.
10. Tamamlama ve Günlük — bir durum işareti ile kronolojik notlar.

Bir görev ek olarak bir Delta bölümü (kahverengi alan davranış değişiklikleri için ÖNERİLİR — aşağıya bakın) ve bir Geri alma bölümü (geçişler, altyapı değişiklikleri veya dağıtımlar için ÖNERİLİR) İÇEREBİLİR.

Dokunulan Yüzey

Dokunulan Yüzey, görevin neyi değiştirdiği ile neyin doğrulanması gerektiği arasındaki sözleşmedir. Doğrulamanın alışkanlığa göre değil etkiye göre seçilmesini ve sonradan gelen bir okuyucunun bir kapının neden seçildiğini görebilmesini sağlamak için var olur. Davranış değiştiren bir görev şunları kaydetMEK ZORUNDADIR:

• Planlanan yüzey — görevin değiştirmeyi amaçladığı yollar, modüller, paketler veya yapılandırma; düzenlemeden önce yazılır.
• Gerçekleşen yüzey — düzenlemeden sonra, gerçek diff’ten alınan uzlaştırılmış liste. Ajan, kapıyı seçmeden önce planlanan ve gerçekleşen yüzeyleri uzlaştırMAK ZORUNDADIR.
• Etkilenen tüketiciler — gerçekleşen yüzeye bağımlı olan modüller, paketler veya servisler; deponun belgelenmiş eşlemesinin belirleyebildiği ölçüde. Belirleyemediği yerde girdi bunu BELİRTMEK ZORUNDADIR.
• Risk sınıfı — şunlardan biri: izole (tek bir modülle ve onun testleriyle sınırlı); seam (iş birlikçiler arasındaki bir sözleşmeyi, kalıcılığı, yönlendirmeyi, serileştirmeyi, kimlik doğrulamayı veya çerçeve bağlantısını değiştirir); paylaşılan/çekirdek (geniş biçimde içe aktarılır ya da bir bağımlılık, geçiş, derleme/test yapılandırması, şema veya araç zinciri değişikliğidir); bilinmeyen (eşleme eksik, bayat veya doğrulanmamış).
• Kullanılan test eşlemesi — seçimi hangi belgelenmiş eşlemenin veya aracın ürettiği.
• Seçilmiş kapı ve gerekçesi — kesin komutlar ve bunların gerçekleşen yüzeyi neden kapsadığı.

Yapılandırma dosyaları, şemalar, bağımlılık manifestoları, şablonlar, fikstürler, geçişler ve ajan yönerge dosyaları davranışı değiştirebilir ve dosya uzantısına göre değil, etkilerine göre sınıflandırılMAK ZORUNDADIR. Yalnızca düz metin, yorum veya araştırma yapıtlarını değiştiren bir görev, yüzeyin uygulanamaz olduğunu beyan edEBİLİR ve yine de deponun çalışma zamanı dışı denetimlerini çalıştırır.

Delta bölümü (kahverengi alan değişiklikleri)

Gerçek çalışmanın büyük çoğunluğu, yeni davranış oluşturmak yerine mevcut davranışı değiştirir. Mevcut bir sistemin nasıl davrandığını değiştiren bir görev, değişikliği açık bir önce/sonra sözleşmesi olarak tanımlayan bir Delta bölümü TAŞIMALIDIR; üç liste başlığı kullanarak:

• ADDED — görevden sonra var olan ve önceden olmayan davranış.
• MODIFIED — her ikisinde de var olan davranış, was: … → now: … biçiminde belirtilir.
• REMOVED — önceden var olan ve kasıtlı olarak sonradan kaldırılan davranış.

Her girdi, bir uç noktanın yanıtı, CLI bayrağı, UI durumu, varsayılan değer gibi gözlemlenebilir bir davranış OLMALIDIR — bir uygulama ayrıntısı değil. Delta bölümü, davranış düzeyindeki gözden geçirenin farkıdır: kabul kriterleri ADDED/MODIFIED girdilerini doğrular ve REMOVED girdileri açık silme lisansıdır. REMOVED olarak listelenmeyen hiçbir şey çalışmaya devam ETMEK ZORUNDADIR.

Doğrulama kapıları — risk sınıfına göre seçilir

Doğrulama, bir tamamlanma iddiasını onun kanıtına dönüştüren kapıdır: bir görev, Doğrulama bölümündeki her komut çalışıp geçene kadar tamamlandı olarak işaretlenMEMELİDİR. Davranış değiştiren bir görevin kapısı, uzlaştırılmış Dokunulan Yüzey’den, risk sınıfına göre seçilir:

Bir davranış değişikliği, boş olmayan ve ilgili bir test seçimi ÜRETMEK ZORUNDADIR — geçersiz bir seçici veya sıfır test seçen bir koşturucu kapsam değildir. Deponun test eşlemesi bayatsa, doğru çağrı türetilir ve eşleme güncellemesi kaydedilir; küçük bir eksik komut asla eksiksiz bir kuruluma alma çalışması gerektirmez. Kapsamlı bir çağrı yoksa, geçerli eksiksiz paket uygulanır — eski davranıştır, asla bir hata değil.

Bir görev yeni çekirdek işlevsellik eklediğinde veya mevcut davranışı önemli ölçüde değiştirdiğinde, kabul kriterleri yeni veya değişen davranış için otomatik test kapsamını İÇERMELİ ve doğrulaması deponun testlerini lint, tür denetimi ve biçim denetimleriyle birlikte çalıştırMALIDIR — yalnızca derlemeyi değil. Mevcut testler yeşil kalMALIDIR.

Son-durum doğrulaması

Görev bazındaki kapılar her görevin dokunduğunu doğrular; planın bir bütün olarak doğrulamasının yerini almazlar. Bir plan tamamlanmadan önce, deponun eksiksiz geçerli doğrulaması, son önemli değişiklikten sonra, son ilgili durum üzerinde — Final Review’de — çalışMAK ve geçMEK ZORUNDADIR. Daha önceki daha geniş çalıştırmalar entegrasyon sınırlarında veya paylaşılan/çekirdek değişikliklerinden sonra olur, görev-sayısı takvimine göre değil. Geçen bir sonuç, yalnızca ilgili girdilerin eşdeğer olduğuna dair kanıtla yeniden KULLANILABİLİR; aksi hâlde yeniden çalıştırılır. Her kapı çalıştırması özlü bir kayıt bırakır: komut, kapsam, revizyon, sonuç ve bir kanıt yolu.

Güvenlik disiplini

Güvenlik, testlerle tam olarak aynı şekilde birinci sınıftır ve aynı iki katmanlı modeli izler: iş sürerken görev bazında disiplin, artı sonunda tüm değişiklik kümesi üzerinde Final Review’in güvenlik incelemesi. Bir görev kimlik doğrulama veya yetkilendirmeye, girdi işlemeye, sırlara veya yapılandırmaya, ağ, dosya veya shell yüzeyine ya da bağımlılıklara dokunduğunda:

• Kabul kriterleri, değişikliğin güvenlik beklentilerini — girdi doğrulanmış ve kaçışlanmış, kodda veya fikstürlerde gizli materyal yok, kimlik doğrulama denetimleri korunmuş veya güçlendirilmiş — docs/SECURITY.md ile tutarlı biçimde BELİRTMELİDİR.
• Her commit, yerleşmeden önce sırlardan veya kimlik bilgilerinden arındırılmış olarak teyit edilMELİDİR; test fikstürleri ve dokümantasyon örnekleri dahil. Gönderilmiş bir commit’teki bir sır, yalnızca kaldırılmış değil, sızmış olarak kabul edilMELİ ve döndürülMELİDİR.
• Güvenliğe duyarlı işin önemli olduğu yerlerde, ayrılmış bir sağlamlaştırma görevi, uygulama görevlerinden hemen sonra ve kapsamlı testler görevinden önce yerleştirilMELİDİR; böylece bulgular, testler davranışı kodlamadan önce düzeltilir ve her bulgu, yeniden çalışma yerine bir regresyon vakası hâline gelir.

Bu görev bazında disiplin, Final Review’in güvenlik incelemesinin yerini almaz: görev bazında denetimler sorunları doğdukları commit’te yakalar, son kapı ise tüm planı — test ve dokümantasyon görevlerinin kendileri dahil — denetler.

Plan yaşam döngüsü — Final Review

Bu sürüm altında yazılmış uyumlu her plan, tam olarak bir zorunlu görevle biter: Final Review (görev N). Önceki sürümlerin ayrı kapanış görevlerine yerleştirdiği iki sorumluluk yeniden konumlandırılır: skill kararları, örüntüyü üreten göreve taşınır ve Executive Report isteğe bağlı, talep üzerine bir yapıt hâline gelir. Güvenlik incelemesinde hiçbir şey gevşetilmez.

Final Review, sırasıyla ŞUNLARI YAPMAK ZORUNDADIR:

(a) Güvenlik incelemesi — planın birikmiş tüm değişiklik kümesini gömme sırlar, enjeksiyon riskleri, yeni saldırı yüzeyi, zayıflatılmış kimlik doğrulama ve günlüklerde ya da dokümantasyonda hassas veriler açısından inceler; tanıtılan bağımlılıkları denetler; docs/SECURITY.md’nin hâlâ gerçeği yansıttığını doğrular; temiz olsa bile güvenlik incelemesi raporunu yazar. Kritik bir bulgu, plan tamamlanmadan önce düzeltilir — ya da kullanıcı tarafından açıkça kabul edilir.

(b) Son-durum doğrulaması — deponun eksiksiz geçerli doğrulaması, son ilgili durum üzerinde çalışır ve geçer.

(c) Skill uzlaştırması — her görev bir skill kararı taşır ve kayıtlı her aday karara bağlanmıştır; ikinci bir keşif raporu yoktur.

(d) Tamamlanma — tamamlanmayı, teslim edilenlerle, doğrulama kanıtıyla ve sınırlamalarla raporla; Executive Report’u bir kez sun. Plan, teklif yanıtlanıp yanıtlanmadan tamamlanmıştır.

Final Review, diğer tüm görevlerden sonra ardışık olarak çalışır ve asla paralel bir gruba yerleştirilmez.

Görev-yerel skill kararları

“Bu iş, bir skill’e veya ajana değer yeniden kullanılabilir bir örüntü mü üretti?” sorusu, örüntüyü üreten görevin içinde, kanıtı bağlamdayken yanıtlanır. Her görevin Tamamlama ve Günlük bölümü bir skill kararı taşır: none, mevcut bir skill’i güncelleme, adlandırılmış bir yapıt oluşturma ya da gerekçeli bir erteleme. Gerekçeli yazma, mevcut katalogda yinelenenler denetlendikten sonra, o görevin içinde, onun doğrulama kapısından ve commit’inden önce gerçekleşir.

Executive report — isteğe bağlı, talep üzerine

Executive Report artık zorunlu bir görev değildir. Tamamlanmada ajan onu bir kez sunar; yalnızca açık bir istek üzerine, planı yeniden oynamadan kalıcı kanıtlardan üretilir. Yanıt gelmemesi veya gözetimsiz bir çalışma, planı rapor üretilmeden tamamlanmış bırakır.

Görev tamamlama protokolü

Doğrulamayı geçtikten ve bir sonraki göreve geçmeden önce, ajan sırasıyla ŞUNLARI YAPMAK ZORUNDADIR: (1) görevin plan README’sindeki kutusunu [x] olarak işaretle; (2) plan durum sayısını artır; (3) görevin Tamamlama ve Günlük bölümünü yer tutucu değer bırakmadan doldur; (4) PROGRESS.md’ye 3–5 maddelik bir girdi ekle; (5) planın commit attığı yerlerde {type}({scope}): {description} — Task {N} of PLAN_{name} biçiminde commit at; (6) plan durum katmanını taşıyorsa, state.json’u atomik olarak yeniden yaz — görev completed, kapı kayıtları, sonuç kaydı, commit karması.

Altı adım tek bir mantıksal işlem oluşturur. Protokol ortasında kesintiye uğrayan bir ajan, bir sonraki görevi BAŞLATMAMALIdır — önce kısmi tamamlamayı bitirmeli ya da geri almalıdır.

DWP devam protokolü

Devam, yalnızca planın dosyaları ve git günlüğü ile herhangi bir harici durum olmadan mümkün OLMAK ZORUNDADIR. Git içermeyen bir çalışma alanında — bkz. Arketipler §3 — planın state.json’u ZORUNLUDUR ve git günlüğünün yerini alır.

Devam eden bir ajan — yeni bir oturum, farklı bir ajan, zamanlanmış daemon dönüşü veya uyanıklık bulut oturumu — bu ritüeli sırasıyla GERÇEKLEŞTIRMEK ZORUNDADIR:

1. Yeniden sabitle. Plan README’sini oku: hedef, genel yönergeler, görev listesi.
2. Kontrol noktasını bul. README’deki ilk işaretsiz görevi bul; git günlüğünü ve git durumunu (veya git yoksa state.json’un checkpoint’ini) oku.
3. Durumu uzlaştır. state.json varsa, README onay kutularıyla karşılaştır; desenkronizasyonda, devam etmeden önce Markdown’dan yeniden oluştur.
4. Ek yeri incele. Devam noktası görevinin Tamamlama ve Günlük bölümünü ve son PROGRESS.md girdisini oku — önceki oturumun son doğrulanmış zemini.
5. Duman testi. Üzerine inşa etmeden önce dünyanın hâlâ çalıştığını doğrulamak için deponun en ucuz yerleşik doğrulamasını çalıştır. Başarısız bir duman testi önce araştırılır, üzerine inşa edilmez.
6. Atomik olarak devam et. Tam olarak sonraki görevi yürüt; ilerisini toplu işleme alma.

Ajan, tamamlandı ([x]) işaretlerine GÜVENMEK ZORUNDADIR ve tamamlanmış görevleri kullanıcı açıkça istemediği ya da duman testi tamamlanmış bir görevi ima eden şekilde başarısız olmadığı sürece YENİDEN DOĞRULAMAMALIdır.

Yürütme döngüsü

DWP beş işlem tanımlar:

• create — Bir hedeften yeni bir plan üretir.
• execute — Planı görev görev yürütür.
• refine — Mevcut bir planı değiştirir.
• resume — Kesintiye uğramış bir planı sürdürür.
• status — Yürütmeden plan durumunu raporlar.

Çıktı çalışma alanı

Çıktı çalışma alanı

• .dwp/ git tarafından yok sayılır · atılabilir
• plans/
• PLAN_<name>/
• README.md
• PROGRESS.md
• <n>.task_<slug>.md
• analysis_results/ raporlar
• SECURITY_REVIEW.md güvenlik incelemesi
• EXECUTIVE_REPORT.md yönetici raporu

Tüm DWP yapıları, depo kökündeki gitignore’lanmış bir .dwp/ dizini altında YAŞAMALIDIR.

Makine tarafından okunabilir plan durumu

Bir plan, makine tarafından okunabilir durum katmanını TASIYABİLİR — manifest.json (statik kimlik) ve state.json (görev bazında canlı durum, doğrulama kapısı kayıtları, sonuç kayıtları, kontrol noktası, engellenmiş durum). Markdown planı doğruluk kaynağı olmaya devam eder; JSON katmanı, protokol noktalarında yeniden oluşturulan ve devamda uzlaştırılan türetilmiş bir projeksiyondur.

Durum katmanı yeni planlar için ÖNERİLİR, gözetimsiz yürütme için ZORUNLUDUR ve git içermeyen ajan çalışma alanları için ZORUNLUDUR. Tam normatif tanım için bkz. Plan durumu.

Orantılı titizlik

Titizlik, çalışmayla orantılı OLMAK ZORUNDADIR. Önemsiz değişiklikler için tören, metodoloji başarısızlığıdır, ekstra güvenlik değil. Her çalışma parçası tam olarak bir kademeye girer:

Micro-kademe çalışması için plan oluşturması istenen bir ajan, bir planın orantısız olduğunu SÖYLEMELİ ve bunun yerine satır içi formu ÖNERMELİDİR. Önemsiz tek dosya değişikliği için plan klasörü OLUŞTURULMAMALIDIR.

Micro-kademe çalışması hâlâ değiştirilemezleri korur: açık bir hedef, çalışan ve geçen bir doğrulama kapısı ve davranış değişiklikleri için test disiplini. Kademe paketi değiştirir, kapıları asla değiştirmez.

Kapsam uçuşta büyüdüğünde — bir micro görev gerçek kapsam ortaya çıkardığında, standart bir plan alt depolar filizlendirdiğinde — ajan DURMAK ve çalışmayı bir sonraki kademeye yükseltmek ZORUNDADIR; mevcut kademeyi esnetmek yerine.

Uyumluluk

Önceki sürümlerden planlar ve depolar uyumlu kalır; bir uyumluluk denetleyicisi, bilinen eski bir yapıt (kabul edilir) ile bu sürümü beyan eden ve ona göre nesnel olarak geçersiz olan bir yapıt (reddedilir) arasında AYRIM YAPMAK ZORUNDADIR:

Sürümleme

Bu spesifikasyon, anlamsal sürümlemeyi izler.