Tuân thủ

Phiên bản 1.3. Trạng thái: Ổn định. Tài liệu này định nghĩa thế nào là một repository tuân thủ Deep Work Plan — tức là AI-first và điều khiển được bằng agent. Các từ khóa MUST, MUST NOT, SHOULD, SHOULD NOT và MAY được diễn giải như mô tả trong RFC 2119.

Sự tuân thủ tồn tại để “AI-first” là một đặc tính khách quan, kiểm tra được thay vì một ấn tượng. Một repository hoặc đạt các tiêu chí dưới đây hoặc không. Sub-skill verify (/dwp-verify) kiểm tra chúng một cách máy móc.

Một repository tuân thủ

Một repository tuân thủ DWP PHẢI thỏa mãn tất cả những điều sau. Mọi thành phần PHẢI được suy luận cho repository — thích ứng với các ngôn ngữ, framework và lệnh thực tế của nó. Một bản mẫu chung chung, một chỗ trống, hay nội dung sao chép từ một repository khác không thỏa mãn một tiêu chí.

1. AGENTS.md tại gốc. Repository PHẢI chứa một AGENTS.md tại gốc bao gồm (a) một chỉ mục tài liệu, (b) các quy tắc bắt buộc cho repository, và (c) một khối Quick Commands với các lệnh thật và chạy được trong repository này. Các lệnh chỗ trống (ví dụ, npm test trong một repository không dùng npm) KHÔNG ĐƯỢC xuất hiện. Chỉ mục KHÔNG ĐƯỢC liên kết tới một tệp docs/ không tồn tại, và tệp này NÊN giữ trong ngân sách 150–500 dòng, chuyển chi tiết sang docs/ và liên kết tới đó thay vì lớn lên vô hạn.
2. CLAUDE.md phân giải tới AGENTS.md. Một CLAUDE.md PHẢI tồn tại và phân giải tới AGENTS.md (một symlink, hoặc một thứ tương đương bảo đảm một nguồn chân lý duy nhất). Cả hai KHÔNG ĐƯỢC lệch nhau.
3. Một hệ thống docs/. Repository PHẢI chứa một thư mục docs/ bao quát các hạng mục chuẩn (kiến trúc, chuẩn mực, kiểm thử, lệnh phát triển, bảo mật và khởi tạo agent) với nội dung thật, riêng cho repository. Các mô-đun phức tạp NÊN mang README.md của riêng chúng. Hướng dẫn kiểm thử PHẢI định nghĩa một bộ công cụ test, lint và kiểm tra kiểu thực — hoặc, đối với một repository không có, một thiết lập cụ thể được đề xuất từ ngăn xếp công nghệ trong quá trình khởi tạo. Một hướng dẫn kiểm thử rỗng hay “không có test” không thỏa mãn tiêu chí này: không có một cách xác định để kiểm chứng hành vi, một kế hoạch không có cổng kiểm chứng khách quan nào.
4. Một thư mục .agents/. Repository PHẢI chứa một thư mục .agents/ với agents/, commands/ và skills/, cùng một catalog dưới .agents/docs/ khớp với những gì có trên đĩa. Các command dwp-* PHẢI là các bộ ủy thác mỏng tới skill đã cài. Một đường dẫn .claude PHẢI phân giải tới .agents.
5. Một không gian làm việc .dwp/ được gitignore. Repository PHẢI chứa một thư mục .dwp/ với plans/, và .dwp/ PHẢI được gitignore. Một không gian nháp tmp/ NÊN tồn tại và NÊN được gitignore.
6. Skill phương pháp luận phân giải được. Skill Deep Work Plan PHẢI được cài hoặc tham chiếu sao cho một agent trong repository có thể gọi các sub-skill của nó.

Một repository hoàn toàn tuân thủ với không addon tùy chọn nào. Các addon tùy chọn (devcontainer, Dailybot, dependency-upgrade, design-system) KHÔNG ĐƯỢC bao giờ bắt buộc để tuân thủ. Kể từ chuẩn 2.3.0, đánh giá cục bộ AI Diff Reviewer (skill vendored + tệp tiện ích mở rộng) là một phần của chuẩn cơ sở: sự vắng mặt của nó là một thất bại đối với một repository khai báo 2.3.0 hoặc mới hơn, và một phát hiện phiên bản harness đối với một repository cũ. Bề mặt CI của nó vẫn là tùy chọn.

Một kế hoạch chỉnh dạng

Một Deep Work Plan trong .dwp/plans/ là chỉnh dạng khi:

1. Mỗi tác vụ PHẢI khai báo một phạm vi rõ ràng, tiêu chí chấp nhận, và ít nhất một cổng kiểm chứng (một lệnh hay bước kiểm tra đạt hoặc không đạt một cách khách quan).
2. Mỗi tác vụ thêm chức năng lõi mới hoặc thay đổi hành vi sản phẩm PHẢI bao gồm độ phủ test tự động cho hành vi đó trong tiêu chí chấp nhận của nó, và PHẢI chạy các test của repository cùng với các bước kiểm tra lint và kiểm tra kiểu trong cổng kiểm chứng của nó — chứ không phải chỉ riêng bước build. Các test hiện có PHẢI tiếp tục xanh; một thay đổi hành vi PHẢI cập nhật một test mà nó làm hỏng thay vì xóa hay bỏ qua nó. 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 chạy cổng của repository.
3. Mỗi tác vụ chạm tới xác thực, xử lý đầu vào, bí mật hay cấu hình, bề mặt mạng, hoặc các phụ thuộc PHẢI mang các kỳ vọng bảo mật của thay đổi đó trong tiêu chí chấp nhận của nó, và mỗi commit PHẢI không chứa tư liệu bí mật.
4. Kế hoạch PHẢI lưu giữ tiến độ để công việc vượt qua gián đoạn và có thể được tiếp tục bởi một agent khác. Một tác vụ KHÔNG ĐƯỢC ghi là completed trong khi bất kỳ bản ghi cổng kiểm chứng nào của nó vẫn cho thấy một lần chạy thất bại, chưa giải quyết, và nhật ký hoàn tất của một tác vụ KHÔNG ĐƯỢC mâu thuẫn với trạng thái đã ghi của nó (ví dụ một tác vụ completed mà nhật ký của nó vẫn ghi “Status: pending” là một lỗi, không phải một kết quả đạt).
5. Kế hoạch PHẢI khép lại bằng bước rà soát cuối được ghi lại của mình. Một kế hoạch được viết dưới phiên bản này PHẢI kết thúc bằng đúng một Final Review bắt buộc — bước rà soát bảo mật, kiểm chứng trạng thái cuối cùng, và sự đối chiếu skill. Một kế hoạch được viết dưới một phiên bản sớm hơn kết thúc bằng ba tác vụ cuối bắt buộc (Security Review, Skills & Agents Discovery, Executive Report) và vẫn tuân thủ. 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 được sửa hoặc được chấp nhận một cách rõ ràng. Bản thân việc hoàn tất là một giao dịch đã kiểm chứng, có thể khôi phục, chứ không phải một sự chuyển đổi trạng thái đơn thuần: tác vụ cuối cùng đóng lại qua một bước công bố được bảo vệ, xác minh các hiện vật của kế hoạch đã hoàn thành trước khi ghi trạng thái và để lại một biên nhận FINALIZATION.json có thể kiểm tra được về mặt máy móc; một lần công bố bị gián đoạn được khôi phục từ bằng chứng, không bao giờ được âm thầm tuyên bố lại là đã hoàn tất. Bất kỳ con trỏ bằng chứng nào mà một bản ghi cổng viện dẫn PHẢI phân giải được bên trong thư mục riêng của kế hoạch — một con trỏ lơ lửng hay thoát ra ngoài là một phát hiện, không phải bằng chứng hợp lệ.
6. Các tác vụ NÊN neo lại vào mục tiêu của kế hoạch trước khi thực thi, để ngăn trôi dạt qua một chân trời dài.

Kiểm chứng sự tuân thủ

Sự tuân thủ NÊN được kiểm chứng một cách máy móc thay vì bằng việc xem xét thủ công. Chạy /dwp-verify tạo một báo cáo đạt/không đạt so với các tiêu chí trên: sự hiện diện và nội dung thật của AGENTS.md, sự phân giải của CLAUDE.md, các hạng mục docs/, sự khớp giữa catalog .agents/ và đĩa, trạng thái gitignore của .dwp/ và tmp/, và — đối với một kế hoạch — rằng mỗi tác vụ mang tiêu chí chấp nhận và một cổng kiểm chứng, cùng độ phủ test cho các tác vụ thay đổi hành vi và sự hiện diện của bước rà soát cuối được ghi lại. Đối với một kế hoạch, nó cũng kiểm tra rằng markdown của kế hoạch và trạng thái đọc được bằng máy của nó khớp nhau (một sự desync giữa README và state.json là một phát hiện, không bao giờ là một kết quả đạt âm thầm), rằng các tác vụ đã hoàn tất mang bằng chứng cổng và nhật ký không mâu thuẫn, và — nơi một kế hoạch đã hoàn tất đạt tới đó — rằng một biên nhận công bố hậu thuẫn cho việc hoàn tất được tuyên bố. Trình kiểm tra nhận thức phiên bản: nó PHẢI chấp nhận một kế hoạch cũ (ba tác vụ cuối bắt buộc, không có Touched Surface) là tuân thủ, và PHẢI từ chối một kế hoạch khai báo phiên bản này mà về khách quan không hợp lệ dưới nó. Nó cũng báo cáo một dòng xuất xứ DWP standard: bị thiếu hoặc lỗi thời là một phát hiện nêu tên nâng cấp harness có mục tiêu. Lớp cơ học trung thực về giới hạn của mình: không có trình thông dịch đủ khả năng (Python 3.9+), nó kết thúc bằng mã thoát khác 0 và phán quyết UNVERIFIED rõ ràng thay vì bỏ qua các bước kiểm tra — một trình kiểm chứng không bao giờ báo cáo kết quả mà nó chưa kiểm tra.

Một repository NÊN được kiểm chứng lại sau khi khởi tạo và sau mỗi kế hoạch hoàn tất, để sự tuân thủ được duy trì thay vì chỉ được tuyên bố một lần.