Skip to content
← เอกสารข้อกำหนดทั้งหมด

ข้อกำหนด DWP

เวอร์ชัน 1.2. สถานะ: เสถียร เอกสารนี้คือข้อกำหนดเชิงบรรทัดฐานสำหรับระเบียบวิธี Deep Work Plan (DWP) คำสำคัญ MUST, MUST NOT, SHOULD, SHOULD NOT และ MAY ให้ตีความตามที่อธิบายไว้ใน RFC 2119

เพิ่มเติมใน v1.2 ความสามารถเพิ่มเติมสี่อย่าง ไม่มีการเปลี่ยนแปลงที่ทำลายความเข้ากันได้: (1) ชั้นสถานะแผนที่เครื่องอ่านได้ (manifest.json + state.json ดู สถานะแผน); (2) ระดับความเข้มงวดตามสัดส่วน (micro / standard / deep ดู ความเข้มงวดตามสัดส่วน); (3) ส่วน Delta ที่เป็นทางเลือกในโครงสร้างงานสำหรับการเปลี่ยนแปลงพฤติกรรม brownfield; และ (4) DWP Resume Protocol ได้รับการยกระดับเป็นพิธีกรรมหกขั้นตอนที่มีชื่อและอ้างอิงได้ แผน v1.1 ที่มีอยู่ยังคงสอดคล้อง

นิยาม

Deep Work Plan คือสิ่งประดิษฐ์แบบ markdown ล้วนที่มีโครงสร้าง ซึ่งอธิบายงานวิศวกรรมที่ซับซ้อนโดยแยกย่อยเป็นหน่วยงานตามลำดับและทบทวนได้ ออกแบบมาเพื่อให้เอเจนต์เขียนโค้ด AI ที่ทำงานอย่างอิสระสร้าง ดำเนินการ และดูแลรักษา

DWP ขับเคลื่อนด้วยข้อกำหนด แผนคือข้อกำหนด และเอเจนต์ MUST ดำเนินการเทียบกับเกณฑ์การยอมรับและ validation gate ที่ชัดเจนของมันแทนที่จะด้นสด ข้อกำหนด — ไม่ใช่บทสนทนาแชต — คือแหล่งความจริงที่ยั่งยืน งานจึงตรวจสอบได้และดำเนินต่อได้ข้ามเซสชันและข้ามเอเจนต์ มันยังเป็น harness engineering ที่ทำให้พกพาได้ บริบท control loop guardrail และสถานะที่ดำเนินต่อได้ซึ่งทำให้เอเจนต์เชื่อถือได้ถูกติดตั้งลงใน repository เองในรูปของ markdown ธรรมดา เอเจนต์ที่สอดคล้องตัวใดก็ MAY ขับเคลื่อน repository ได้โดยไม่ต้องมีเฟรมเวิร์กเฉพาะเครื่องมือ

โครงสร้างแผน

แผน MUST เป็นไดเรกทอรีภายใต้ .dwp/plans/ ที่ตั้งชื่อว่า PLAN_<slug>/ ไดเรกทอรีนั้น MUST ประกอบด้วย

  • README.md — ภาพรวมแผน เป้าหมาย ตารางงาน และสถานะ
  • หนึ่งไฟล์ต่อหนึ่งงาน ตั้งชื่อว่า <n>.task_<slug>.md
  • PROGRESS.md — log การทำงานที่บันทึกต่อเนื่อง

แผน MAY พกชั้นสถานะที่เครื่องอ่านได้เพิ่มเติม: manifest.json (เอกลักษณ์คงที่ เขียนหนึ่งครั้งตอน materialization) และ state.json (สถานะการดำเนินงานต่อหนึ่งงานแบบสด) ชั้นสถานะ RECOMMENDED สำหรับแผนใหม่และ REQUIRED สำหรับการดำเนินงานแบบไม่มีผู้ดูแลและสำหรับ agent workspace ที่ไม่มี git ดู สถานะแผน

โครงสร้างงาน

ไฟล์งานแต่ละไฟล์ MUST มีเก้าส่วนนี้ตามลำดับ

  1. เป้าหมาย — คำบอกกล่าวหนึ่งย่อหน้าว่างานนี้บรรลุอะไร
  2. บริบท — ภูมิหลัง ลิงก์ และเหตุผลที่งานนี้มีอยู่
  3. ขั้นตอน — การกระทำที่เป็นรูปธรรมและเรียงลำดับซึ่งต้องทำ
  4. เกณฑ์การยอมรับ — เช็กลิสต์ของเงื่อนไขที่นิยามว่าเสร็จ
  5. การตรวจสอบ — คำสั่งหรือการทดสอบที่ต้องรันเพื่อยืนยัน
  6. ไฟล์ — พาธที่คาดว่าจะถูกสร้างหรือแก้ไข
  7. ส่วนพึ่งพิง — งานอื่นหรือเงื่อนไขเบื้องต้นภายนอก
  8. ความเสี่ยง — สิ่งที่อาจผิดพลาดและการบรรเทา
  9. การเสร็จสิ้นและ Log — เครื่องหมายสถานะพร้อมบันทึกตามลำดับเวลา

งาน MAY รวมส่วน Delta เพิ่มเติม (RECOMMENDED สำหรับการเปลี่ยนแปลงพฤติกรรม brownfield — ดูด้านล่าง) และส่วน Rollback (RECOMMENDED สำหรับการย้ายข้อมูล การเปลี่ยนแปลงโครงสร้างพื้นฐาน หรือการ deploy)

ส่วน Delta (การเปลี่ยนแปลง brownfield)

งานจริงส่วนใหญ่แก้ไขพฤติกรรมที่มีอยู่แทนที่จะสร้างพฤติกรรมใหม่ งานที่เปลี่ยนวิธีทำงานของระบบที่มีอยู่ SHOULD พกส่วน Delta ที่อธิบายการเปลี่ยนแปลงเป็นสัญญาก่อน/หลังที่ชัดเจน โดยใช้หัวข้อรายการสาม:

  • ADDED — พฤติกรรมที่มีหลังงานและไม่มีก่อนหน้านี้
  • MODIFIED — พฤติกรรมที่มีทั้งสอง ระบุเป็น was: … → now: …
  • REMOVED — พฤติกรรมที่มีก่อนหน้าและหายไปอย่างตั้งใจหลังจากนั้น

แต่ละรายการ MUST เป็นพฤติกรรมที่สังเกตได้ — การตอบสนองของ endpoint flag ของ CLI สถานะ UI ค่าเริ่มต้น — ไม่ใช่รายละเอียดการ implement ส่วน Delta คือ diff ของผู้ตรวจสอบในระดับพฤติกรรม: เกณฑ์การยอมรับยืนยันรายการ ADDED/MODIFIED และรายการ REMOVED คือใบอนุญาตชัดเจนในการลบ สิ่งใดที่ไม่ได้ระบุว่า REMOVED MUST ยังคงทำงาน และ validation gate ของงาน (การทดสอบที่มีอยู่ยังคงเป็นสีเขียว) คือสิ่งที่บังคับใช้

Validation gate และการทดสอบ

การตรวจสอบคือ gate ที่เปลี่ยนการกล่าวอ้างว่าเสร็จให้กลายเป็นหลักฐานว่าเสร็จ งาน MUST NOT ถูกทำเครื่องหมายว่าเสร็จจนกว่าทุกคำสั่งในส่วนการตรวจสอบของมันจะรันและผ่านแล้ว การทดสอบเป็นส่วนสำคัญลำดับแรกของ gate นี้ ไม่ใช่ส่วนเสริมที่จะมีหรือไม่ก็ได้ — มันคือสิ่งที่ทำให้โค้ดที่แผนส่งมอบเชื่อถือได้และตรวจสอบได้

เมื่องานเพิ่มฟังก์ชันหลักใหม่หรือเปลี่ยนพฤติกรรมที่มีอยู่อย่างมีนัยสำคัญ

  • เกณฑ์การยอมรับ ของมัน MUST รวมความครอบคลุมของการทดสอบอัตโนมัติสำหรับพฤติกรรมที่ใหม่หรือเปลี่ยนไป (เส้นทางปกติพร้อมกรณีขอบและกรณีข้อผิดพลาดที่มีนัยสำคัญ) ตามข้อตกลงการทดสอบและความคาดหวังด้านความครอบคลุมของ repository
  • การตรวจสอบ ของมัน MUST รันการทดสอบของ repository ร่วมกับการตรวจ lint, type-check และ format ของมัน — การตรวจคุณภาพโค้ดทั้งหมดที่ repository นิยามไว้ — ไม่ใช่เพียง build เท่านั้น “มัน build ได้” ไม่ใช่ gate ที่เพียงพอสำหรับการเปลี่ยนพฤติกรรม
  • การทดสอบที่มีอยู่ MUST ยังคงผ่าน การเปลี่ยนแปลงที่ทำให้การทดสอบซึ่งครอบคลุมโค้ดที่ได้รับผลกระทบล้มเหลว MUST อัปเดตการทดสอบนั้นให้เป็นพฤติกรรมใหม่ที่ตั้งใจไว้ มัน MUST NOT ลบ ข้าม หรือทำให้การทดสอบอ่อนแอลงเพียงเพื่อบังคับให้ gate ผ่าน

งานที่เป็นเอกสารล้วน การกำหนดค่า หรือการวิจัยได้รับการยกเว้นจากการสร้างการทดสอบ แต่ยังคง MUST รัน validation gate ใด ๆ ที่ repository นิยามไว้ ความลึกของการทดสอบเป็นสัดส่วนกับขนาดของการเปลี่ยนแปลงและความสมบูรณ์ของ repository ในกรณีที่ repository ไม่มี toolchain การทดสอบหรือ lint เลย เอเจนต์ MUST NOT ข้ามวินัยนี้อย่างเงียบ ๆ — มันอาศัย toolchain ที่ถูกเสนอระหว่างการออนบอร์ด (ดู ความสอดคล้อง)

วินัยด้านความปลอดภัย

ความปลอดภัยเป็นเรื่องสำคัญลำดับแรกเช่นเดียวกับการทดสอบ และเป็นไปตามโมเดลสองชั้นเดียวกัน: วินัยต่อหนึ่งงานขณะที่งานกำลังดำเนินอยู่ บวกกับ gate Security Review ที่บังคับครอบคลุมชุดการเปลี่ยนแปลงทั้งหมดในตอนท้าย เมื่อใดก็ตามที่งานแตะต้องการพิสูจน์ตัวตนหรือการให้สิทธิ์ การจัดการ input, secrets หรือการกำหนดค่า, พื้นผิวเครือข่าย ไฟล์ หรือ shell, หรือ dependencies:

  • เกณฑ์การยอมรับ ของมัน MUST ระบุความคาดหวังด้านความปลอดภัยของการเปลี่ยนแปลงนั้น — input ถูก validate และ escape, ไม่มีสาระความลับในโค้ดหรือ fixtures, การตรวจสอบ auth ถูกรักษาไว้หรือเสริมให้แข็งแกร่งขึ้น — สอดคล้องกับ docs/SECURITY.md
  • ทุก commit MUST ได้รับการยืนยันว่าปราศจาก secrets หรือ credentials ก่อนที่มันจะ land รวมถึง test fixtures และตัวอย่างในเอกสารด้วย secret ใน commit ที่ push ไปแล้ว MUST ถูกถือว่ารั่วไหลและต้อง rotate ไม่ใช่เพียงลบออก
  • ในกรณีที่งานที่อ่อนไหวด้านความปลอดภัยมีสาระสำคัญ งาน hardening เฉพาะ SHOULD ถูกวางไว้ทันทีหลังงาน implementation และก่อนงาน comprehensive-tests เพื่อให้ข้อค้นพบถูกแก้ไขก่อนที่การทดสอบจะเข้ารหัสพฤติกรรมนั้น และข้อค้นพบแต่ละอย่างกลายเป็นกรณี regression แทนที่จะเป็นการทำงานซ้ำ

วินัยต่อหนึ่งงานนี้ไม่ได้แทนที่งานสุดท้าย Security Review: การตรวจต่อหนึ่งงานจับปัญหาใน commit ที่ปัญหาเกิดขึ้น ขณะที่ gate สุดท้ายตรวจสอบทั้งแผน — รวมถึงงานทดสอบและงานเอกสารเองด้วย ดังนั้นทุกแผนจึงจบลงด้วยงานสุดท้ายบังคับสามงาน — Security Review จากนั้น Skills & Agents Discovery จากนั้น Executive Report — และข้อค้นพบด้านความปลอดภัยที่วิกฤติจะบล็อกการเสร็จสิ้นจนกว่าจะได้รับการแก้ไขหรือได้รับการยอมรับอย่างชัดเจน

โปรโตคอลการเสร็จสิ้นงาน

หลังผ่านการตรวจสอบและก่อนก้าวไปงานถัดไป เอเจนต์ MUST ตามลำดับ: (1) ทำเครื่องหมายงานเป็น [x] ใน README ของแผน; (2) เพิ่มจำนวนสถานะแผน; (3) กรอกส่วนการเสร็จสิ้นและ Log ของงานโดยไม่มีค่า placeholder; (4) เพิ่มรายการ 3–5 bullet เข้า PROGRESS.md; (5) commit (ในกรณีที่แผน commit) ในรูปแบบ {type}({scope}): {description} — Task {N} of PLAN_{name}; (6) ในกรณีที่แผนพกชั้นสถานะ เขียน state.json ใหม่แบบ atomic — งาน completed บันทึก gate บันทึกผลลัพธ์ commit hash

หกขั้นตอนรวมเป็น transaction ตรรกะหนึ่งรายการ เอเจนต์ที่ถูกขัดจังหวะกลางโปรโตคอล MUST NOT เริ่มงานถัดไป — มันต้องเสร็จสิ้นหรือยกเลิกการเสร็จสิ้นบางส่วนก่อน

DWP Resume Protocol

Resume MUST เป็นไปได้จากไฟล์ของแผนบวก git log เท่านั้น โดยไม่มีสถานะภายนอก ใน workspace ที่ไม่มี git — ดู Archetype §3 — state.json ของแผน REQUIRED และทำหน้าที่แทน git log

เอเจนต์ที่กำลัง resume — เซสชันใหม่ เอเจนต์อื่น รอบ daemon ที่กำหนดเวลา หรือ cloud session ที่ตื่น — MUST ทำพิธีกรรมนี้ตามลำดับ:

  1. Re-anchor อ่าน README ของแผน: เป้าหมาย แนวทางทั่วไป รายการงาน
  2. ระบุ checkpoint หางานที่ยังไม่ได้ทำเครื่องหมายงานแรกใน README อ่าน git log และ git status (หรือ checkpoint ของ state.json ในกรณีที่ไม่มี git)
  3. ปรับประสานสถานะ ในกรณีที่ state.json มีอยู่ เปรียบเทียบกับ checkbox ของ README เมื่อเบี่ยงเบน สร้าง state.json ใหม่จาก markdown ก่อนดำเนินการต่อ
  4. ตรวจสอบรอยต่อ อ่านส่วนการเสร็จสิ้นและ Log ของงานจุด resume และรายการ PROGRESS.md ล่าสุด — พื้นฐานที่ยืนยันล่าสุดของเซสชันก่อนหน้า
  5. Smoke-test รัน validation ราคาถูกที่สุดที่คงอยู่ของ repository เพื่อยืนยันว่าโลกยังทำงานอยู่ก่อนสร้างต่อจากมัน smoke test ที่ล้มเหลวถูกตรวจสอบก่อน ไม่ใช่สร้างต่อจากมัน
  6. ดำเนินการแบบ atomic ดำเนินงานถัดไปเพียงงานเดียว อย่ารวมข้างหน้า

เอเจนต์ MUST เชื่อถือเครื่องหมาย [x] ที่เสร็จแล้ว และ MUST NOT ตรวจสอบงานที่เสร็จแล้วซ้ำ เว้นแต่ผู้ใช้ร้องขออย่างชัดเจน หรือ smoke test ล้มเหลวในลักษณะที่เกี่ยวข้องกับงานที่เสร็จแล้ว

ลูปดำเนินงาน

DWP นิยามห้าปฏิบัติการ

  • create — สร้างแผนใหม่จากเป้าหมาย
  • execute — ดำเนินแผนทีละงาน
  • refine — แก้ไขแผนที่มีอยู่
  • resume — ดำเนินแผนที่ถูกขัดจังหวะต่อ
  • status — รายงานสถานะแผนโดยไม่ดำเนินการ

พื้นที่ทำงานผลลัพธ์

สิ่งประดิษฐ์ทั้งหมดของ DWP MUST อยู่ภายใต้ไดเรกทอรี .dwp/ ที่ถูก gitignore ที่รากของ repository

สถานะแผนที่เครื่องอ่านได้

แผน MAY พกชั้นสถานะที่เครื่องอ่านได้ — manifest.json (เอกลักษณ์คงที่) และ state.json (สถานะต่อหนึ่งงานแบบสด บันทึก validation gate บันทึกผลลัพธ์ checkpoint สถานะ blocked) แผน markdown ยังคงเป็นแหล่งความจริง ชั้น JSON เป็นการฉายภาพที่ได้รับมา สร้างใหม่ที่จุดโปรโตคอลและปรับประสานตอน resume

ชั้นสถานะ RECOMMENDED สำหรับแผนใหม่ REQUIRED สำหรับการดำเนินงานแบบไม่มีผู้ดูแล และ REQUIRED สำหรับ agent workspace ที่ไม่มี git ดูนิยามเชิงบรรทัดฐานเต็มรูปแบบใน สถานะแผน

ความเข้มงวดตามสัดส่วน

ความเข้มงวด MUST เป็นสัดส่วนกับงาน พิธีกรรมบนการเปลี่ยนแปลงเล็กน้อยคือความล้มเหลวของระเบียบวิธี ไม่ใช่ความปลอดภัยเพิ่มเติม งานทุกชิ้นอยู่ในระดับเดียวกันพอดี:

ระดับ เมื่อใด รูปแบบ
micro การเปลี่ยนแปลง atomic เดียว: หนึ่งความกังวล ประมาณหนึ่งรอบ ไม่มีการประสานงาน การแก้บั๊ก การเปลี่ยนข้อความ การปรับการกำหนดค่า ไม่มีโฟลเดอร์แผน เอเจนต์ระบุเป้าหมาย เกณฑ์การยอมรับ และ validation gate แบบ inline ในการสนทนา ดำเนินการ ตรวจสอบ commit
standard งานหลายขั้นตอนที่มีขอบเขตจริง: ฟีเจอร์ การ refactor การย้ายข้อมูลภายใน repo หนึ่ง ระดับเริ่มต้น แผนเต็มรูปแบบ: โฟลเดอร์แผน งานเก้าส่วน งานสุดท้ายบังคับสองงาน
deep งานระยะยาวที่ครอบคลุมกลุ่มแบบขนาน child repository หรือหลาย session ไม่มีผู้ดูแล แผน standard บวกความสามารถ orchestrator และ/หรือ team-agents และชั้นสถานะ

เอเจนต์ที่ถูกขอให้สร้างแผนสำหรับงานระดับ micro MUST บอกว่าแผนไม่สมดุลและเสนอรูปแบบ inline แทน โฟลเดอร์แผน MUST NOT ถูกสร้างสำหรับการเปลี่ยนแปลงไฟล์เดียวเล็กน้อย

งานระดับ micro ยังคงรักษาสิ่งที่ต้องทำเสมอ: เป้าหมายชัดเจน validation gate ที่รันและผ่าน และวินัยการทดสอบสำหรับการเปลี่ยนแปลงพฤติกรรม ระดับเปลี่ยนการบรรจุ ไม่ใช่ gate

เมื่อขอบเขตขยายระหว่างดำเนินการ — งาน micro เปิดเผยขอบเขตจริง แผน standard แตกออกเป็น sub-repository — เอเจนต์ MUST หยุดและยกระดับงานไปยังระดับถัดไปแทนที่จะยืดระดับปัจจุบัน

การกำหนดเวอร์ชัน

ข้อกำหนดนี้ใช้การกำหนดเวอร์ชันเชิงความหมาย