Skip to content
← Tất cả tài liệu đặc tả

Đặc tả DWP

Phiên bản 1.2. Trạng thái: Ổn định. Tài liệu này là đặc tả quy phạm cho phương pháp luận Deep Work Plan (DWP). Các từ khóa MUST, MUST NOT, SHOULD, SHOULD NOT và MAY được diễn giải như mô tả trong RFC 2119.

Bổ sung trong v1.2. Bốn năng lực bổ sung, không có thay đổi phá vỡ: (1) lớp trạng thái kế hoạch có thể đọc bằng máy (manifest.json + state.json, xem Trạng thái kế hoạch); (2) các bậc rigor tỷ lệ (micro / standard / deep, xem Rigor tỷ lệ); (3) phần Delta tùy chọn trong cấu trúc tác vụ cho các thay đổi hành vi trong codebase hiện có; và (4) Giao thức Tiếp tục DWP được nâng cấp thành một nghi lễ sáu bước có thể đặt tên và trích dẫn. Các kế hoạch v1.1 hiện có vẫn tuân thủ.

Định nghĩa

Một Deep Work Plan là một thành phần có cấu trúc, chỉ dùng markdown, mô tả một tác vụ kỹ thuật phức tạp được phân rã thành các đơn vị công việc tuần tự, rà soát được, thiết kế để được tạo ra, thực thi và duy trì bởi các agent lập trình AI làm việc tự chủ.

DWP dựa trên đặc tả: kế hoạch là đặc tả, và các agent PHẢI (MUST) thực thi dựa trên tiêu chí chấp nhận rõ ràng và các cổng kiểm chứng của nó thay vì tùy hứng. Đặc tả — chứ không phải một bản chép cuộc chat — là nguồn chân lý bền vững, nên công việc kiểm chứng được và tiếp tục được qua các phiên và các agent. Đó cũng là kỹ thuật harness được làm cho dễ mang theo: ngữ cảnh, vòng điều khiển, hàng rào bảo vệ và trạng thái có thể tiếp tục giúp một agent đáng tin cậy được cài vào chính repository dưới dạng markdown thuần, nên mọi agent tuân thủ ĐỀU CÓ THỂ (MAY) điều khiển repository mà không cần một framework gắn với công cụ cụ thể.

Cấu trúc kế hoạch

Một kế hoạch PHẢI là một thư mục dưới .dwp/plans/ được đặt tên PLAN_<slug>/. Thư mục PHẢI chứa:

  • README.md — tổng quan kế hoạch, mục tiêu, bảng tác vụ và trạng thái.
  • Một tệp cho mỗi tác vụ, đặt tên <n>.task_<slug>.md.
  • PROGRESS.md — một nhật ký chạy của quá trình thực thi.

Một kế hoạch CÓ THỂ (MAY) bổ sung mang lớp trạng thái có thể đọc bằng máy: manifest.json (danh tính tĩnh, được ghi một lần khi vật liệu hóa) và state.json (trạng thái thực thi trực tiếp theo tác vụ). Lớp trạng thái ĐƯỢC KHUYẾN NGHỊ (RECOMMENDED) cho các kế hoạch mới và BẮT BUỘC (REQUIRED) cho thực thi không có giám sát và cho các không gian làm việc agent không có git. Xem Trạng thái kế hoạch.

Cấu trúc tác vụ

Mỗi tệp tác vụ PHẢI chứa chín phần này, theo thứ tự:

  1. Goal — một câu phát biểu một đoạn về điều tác vụ đạt được.
  2. Context — bối cảnh, liên kết và lý do tác vụ này tồn tại.
  3. Steps — các hành động cụ thể, có thứ tự cần thực hiện.
  4. Acceptance criteria — một danh sách kiểm các điều kiện định nghĩa thế nào là xong.
  5. Validation — các lệnh hoặc test cần chạy để kiểm chứng.
  6. Files — các đường dẫn dự kiến được tạo hoặc sửa đổi.
  7. Dependencies — các tác vụ khác hoặc điều kiện tiên quyết bên ngoài.
  8. Risks — điều gì có thể sai, và các biện pháp giảm thiểu.
  9. Completion & Log — một dấu trạng thái cùng các ghi chú theo trình tự thời gian.

Một tác vụ CÓ THỂ bổ sung bao gồm một phần Delta (ĐƯỢC KHUYẾN NGHỊ cho các thay đổi hành vi trong codebase hiện có — xem bên dưới) và một phần Rollback (ĐƯỢC KHUYẾN NGHỊ cho các lần di chuyển, thay đổi hạ tầng hay triển khai).

Phần Delta (thay đổi trong codebase hiện có)

Hầu hết công việc thực tế sửa đổi hành vi hiện có thay vì tạo ra hành vi mới. Một tác vụ thay đổi cách một hệ thống hiện có hoạt động NÊN mang một phần Delta mô tả sự thay đổi dưới dạng hợp đồng trước/sau rõ ràng, sử dụng ba tiêu đề danh sách:

  • ADDED — hành vi tồn tại sau tác vụ mà không có trước.
  • MODIFIED — hành vi tồn tại trong cả hai, được nêu là was: … → now: ….
  • REMOVED — hành vi tồn tại trước và được loại bỏ có chủ ý sau.

Mỗi mục PHẢI là hành vi có thể quan sát — phản hồi của một endpoint, một cờ CLI, một trạng thái UI, một giá trị mặc định — không phải một chi tiết triển khai. Phần Delta là diff của người rà soát ở mức hành vi: tiêu chí chấp nhận kiểm chứng các mục ADDED/MODIFIED, và các mục REMOVED là giấy phép rõ ràng để xóa. Bất cứ thứ gì không được liệt kê là REMOVED PHẢI tiếp tục hoạt động, và cổng kiểm chứng của tác vụ (các test hiện có tiếp tục xanh) là thứ thực thi điều đó.

Cổng kiểm chứng và test

Kiểm chứng là cổng biến một tuyên bố hoàn tất thành bằng chứng của nó: một tác vụ KHÔNG ĐƯỢC (MUST NOT) bị đánh dấu hoàn tất cho đến khi mọi lệnh trong phần Validation của nó đã chạy và đạt. Test là một phần hạng nhất của cổng này, không phải một thứ tùy chọn đính kèm — chúng là điều làm cho mã mà một kế hoạch xuất ra trở nên đáng tin cậy và kiểm chứng được.

Khi một tác vụ thêm chức năng lõi mới hoặc thay đổi đáng kể hành vi hiện có:

  • Tiêu chí chấp nhận của nó PHẢI bao gồm độ phủ test tự động cho hành vi mới hoặc đã thay đổi (đường đi thuận lợi cùng các trường hợp biên và lỗi có ý nghĩa), tuân theo quy ước test và kỳ vọng độ phủ của repository.
  • Kiểm chứng của nó PHẢI chạy các test của repository cùng với các bước kiểm tra lint, kiểm tra kiểu và định dạng của nó — kiểm tra chất lượng mã đầy đủ mà repository định nghĩa — chứ không phải chỉ riêng bước build. “Nó build được” không phải là một cổng đủ cho một thay đổi hành vi.
  • Các test hiện có PHẢI tiếp tục xanh. Một thay đổi làm hỏng một test bao phủ phần mã bị ảnh hưởng PHẢI cập nhật test đó theo hành vi mới dự kiến; nó KHÔNG ĐƯỢC xóa, bỏ qua hay làm suy yếu một test chỉ để ép cổng đạt.

Các tác vụ thuần tài liệu, cấu hình hay nghiên cứu được miễn việc tạo test nhưng vẫn PHẢI chạy bất kỳ cổng kiểm chứng nào mà repository định nghĩa. Độ sâu của việc test tỷ lệ với kích thước của thay đổi và độ trưởng thành của repository. Nơi một repository hoàn toàn không có bộ công cụ test hay lint, agent KHÔNG ĐƯỢC âm thầm bỏ qua kỷ luật này — nó dựa vào bộ công cụ được đề xuất trong quá trình khởi tạo (xem Tuân thủ).

Kỷ luật bảo mật

Bảo mật là hạng nhất giống như cách test là hạng nhất, và nó tuân theo cùng một mô hình hai lớp: kỷ luật theo từng tác vụ trong khi công việc diễn ra, cộng với một cổng Security Review bắt buộc trên toàn bộ tập thay đổi ở cuối. Bất cứ khi nào một tác vụ chạm đến xác thực hoặc phân quyền, xử lý đầu vào, bí mật hoặc cấu hình, bề mặt mạng, tệp, hoặc shell, hay các phụ thuộc:

  • Tiêu chí chấp nhận của nó PHẢI nêu các kỳ vọng bảo mật của thay đổi — đầu vào được kiểm tra và escape, không có chất liệu bí mật trong mã hoặc fixture, các kiểm tra xác thực được giữ nguyên hoặc tăng cường — nhất quán với docs/SECURITY.md.
  • Mọi commit PHẢI được xác nhận là không chứa bí mật hoặc thông tin xác thực trước khi nó được đưa vào, bao gồm cả fixture test và ví dụ tài liệu. Một bí mật trong một commit đã push PHẢI được coi là đã rò rỉ và phải xoay vòng, chứ không chỉ đơn thuần bị xóa.
  • Nơi công việc nhạy cảm về bảo mật là đáng kể, một tác vụ gia cố chuyên biệt NÊN được đặt ngay sau các tác vụ triển khai và trước tác vụ test toàn diện, để các phát hiện được sửa trước khi test mã hóa hành vi và mỗi phát hiện trở thành một ca hồi quy thay vì làm lại.

Kỷ luật theo từng tác vụ này không thay thế tác vụ cuối Security Review: các kiểm tra theo từng tác vụ bắt vấn đề ngay tại commit nơi chúng sinh ra, trong khi cổng cuối kiểm toán toàn bộ kế hoạch — bao gồm chính các tác vụ test và tài liệu. Do đó mọi kế hoạch kết thúc với ba tác vụ cuối bắt buộc — Security Review, rồi Skills & Agents Discovery, rồi Executive Report — và một phát hiện bảo mật nghiêm trọng chặn việc hoàn tất cho đến khi nó được sửa hoặc được chấp nhận một cách rõ ràng.

Giao thức hoàn tất tác vụ

Sau khi vượt qua kiểm chứng và trước khi chuyển sang tác vụ tiếp theo, agent PHẢI, theo thứ tự: (1) đánh dấu tác vụ [x] trong README kế hoạch; (2) tăng số đếm trạng thái kế hoạch; (3) điền vào phần Completion & Log của tác vụ mà không có giá trị placeholder; (4) thêm một mục 3–5 gạch đầu dòng vào PROGRESS.md; (5) commit (nơi kế hoạch commit) với định dạng {type}({scope}): {description} — Task {N} of PLAN_{name}; (6) nơi kế hoạch mang lớp trạng thái, ghi lại state.json nguyên tử — tác vụ completed, bản ghi cổng, bản ghi kết quả, băm commit.

Sáu bước tạo thành một giao dịch logic duy nhất. Một agent bị gián đoạn giữa chừng giao thức KHÔNG ĐƯỢC bắt đầu tác vụ tiếp theo — nó phải hoàn tất hoặc hoàn tác việc hoàn tất một phần trước.

Giao thức tiếp tục DWP

Tiếp tục PHẢI có thể thực hiện được chỉ từ các tệp của kế hoạch cộng với git log, không có trạng thái bên ngoài. Trong một không gian làm việc không có git — xem Các kiểu hình §3 — state.json của kế hoạch là BẮT BUỘC (REQUIRED) và thay thế cho git log.

Một agent tiếp tục — một phiên mới, một agent khác, một lượt daemon theo lịch, hay một cloud session thức dậy — PHẢI thực hiện nghi lễ này, theo thứ tự:

  1. Tái neo. Đọc README kế hoạch: mục tiêu, hướng dẫn chung, danh sách tác vụ.
  2. Định vị điểm kiểm tra. Tìm tác vụ chưa chọn đầu tiên trong README; đọc git log và git status (hoặc checkpoint của state.json nơi git vắng mặt).
  3. Điều hòa trạng thái. Nơi state.json tồn tại, so sánh nó với các ô chọn README; khi desync, tái tạo nó từ markdown trước khi tiếp tục.
  4. Kiểm tra đường nối. Đọc Completion & Log của tác vụ điểm tiếp tục và mục PROGRESS.md cuối cùng — nền tảng đã xác minh cuối cùng của phiên trước.
  5. Smoke-test. Chạy kiểm chứng thường trực rẻ nhất của repository để xác nhận thế giới vẫn hoạt động trước khi xây dựng trên nó. Một smoke test thất bại được điều tra trước, không được xây dựng tiếp.
  6. Tiếp tục nguyên tử. Thực thi đúng tác vụ tiếp theo; không gộp nhiều tác vụ.

Agent PHẢI tin vào các dấu đã hoàn tất ([x]) và KHÔNG ĐƯỢC tái kiểm chứng các tác vụ đã hoàn tất trừ khi người dùng yêu cầu rõ ràng, hoặc smoke test thất bại theo cách liên quan đến một tác vụ đã hoàn tất.

Vòng lặp thực thi

DWP định nghĩa năm thao tác:

  • create — Sinh ra một kế hoạch mới từ một mục tiêu.
  • execute — Thực thi kế hoạch từng tác vụ một.
  • refine — Sửa đổi một kế hoạch hiện có.
  • resume — Tiếp tục một kế hoạch bị gián đoạn.
  • status — Báo cáo trạng thái kế hoạch mà không thực thi.

Không gian làm việc đầu ra

Tất cả thành phần DWP PHẢI sống dưới một thư mục .dwp/ được gitignore tại gốc repository.

Trạng thái kế hoạch có thể đọc bằng máy

Một kế hoạch CÓ THỂ mang lớp trạng thái có thể đọc bằng máy — manifest.json (danh tính tĩnh) và state.json (trạng thái trực tiếp theo tác vụ, bản ghi cổng kiểm chứng, bản ghi kết quả, điểm kiểm tra, trạng thái bị chặn). Kế hoạch markdown vẫn là nguồn chân lý; lớp JSON là một phép chiếu dẫn xuất, được tái tạo tại các điểm giao thức và được điều hòa khi tiếp tục.

Lớp trạng thái ĐƯỢC KHUYẾN NGHỊ cho các kế hoạch mới, BẮT BUỘC cho thực thi không có giám sát, và BẮT BUỘC cho các không gian làm việc agent không có git. Xem định nghĩa quy phạm đầy đủ trong Trạng thái kế hoạch.

Rigor tỷ lệ

Rigor PHẢI tỷ lệ với công việc. Nghi lễ trên các thay đổi tầm thường là một lỗi phương pháp luận, không phải sự an toàn thêm. Mọi công việc đều thuộc chính xác một bậc:

Bậc Khi nào Hình thức
micro Một thay đổi nguyên tử duy nhất: một mối quan tâm, khoảng một buổi làm việc, không cần điều phối. Sửa lỗi, thay đổi nội dung, chỉnh cấu hình. Không có thư mục kế hoạch. Agent nêu mục tiêu, tiêu chí chấp nhận và cổng kiểm chứng nội tuyến trong cuộc trò chuyện, thực thi, kiểm chứng, commit.
standard Công việc nhiều bước với phạm vi thực sự: một tính năng, một tái cấu trúc, một di chuyển trong một repo. Bậc mặc định. Một kế hoạch đầy đủ: thư mục kế hoạch, các tác vụ chín phần, các tác vụ cuối bắt buộc.
deep Công việc dài hạn trải dài các nhóm song song, repository con, hoặc nhiều phiên không có giám sát. Một kế hoạch standard cộng với các năng lực điều phối và/hoặc team-agents, và lớp trạng thái.

Một agent được yêu cầu tạo kế hoạch cho công việc bậc micro PHẢI nói rằng một kế hoạch là không tương xứng và đề xuất hình thức nội tuyến thay thế. Một thư mục kế hoạch KHÔNG ĐƯỢC tạo cho một thay đổi đơn tệp tầm thường.

Công việc bậc micro vẫn giữ các yếu tố không thể thương lượng: một mục tiêu rõ ràng, một cổng kiểm chứng chạy và đạt, và kỷ luật test cho các thay đổi hành vi. Bậc thay đổi bao bì, không bao giờ thay đổi các cổng.

Khi phạm vi tăng lên giữa chừng — một tác vụ micro khám phá phạm vi thực sự, một kế hoạch standard nảy sinh các sub-repository — agent PHẢI dừng lại và nâng cấp công việc lên bậc tiếp theo thay vì kéo dài bậc hiện tại.

Phiên bản hóa

Đặc tả này tuân theo phiên bản hóa ngữ nghĩa (semantic versioning).