verification-before-completion

Tổng quan

Kỹ năng verification-before-completion là gì?

Kỹ năng verification-before-completion định nghĩa một quy tắc quy trình rất nghiêm cho lập trình viên và agent: không bao giờ được nói là công việc đã xong, test đã pass, hoặc bug đã được sửa trừ khi bạn vừa chạy lệnh kiểm chứng liên quan và đã kiểm tra đầu ra của nó. Nguyên tắc cốt lõi là:

Luôn có bằng chứng trước khi đưa ra tuyên bố.

Trong thực tế, điều này có nghĩa là trước khi bạn viết "tests are passing", "the build is green" hoặc "the bug is fixed", bạn phải:

• Xác định lệnh có thể chứng minh cho tuyên bố đó
• Chạy lại lệnh đó (không dựa vào lần chạy cũ hay suy đoán)
• Đọc đầu ra và mã thoát (exit status)
• Chỉ sau đó mới được nêu kết quả, kèm theo bằng chứng tương ứng

Kỹ năng này dành cho ai?

Hãy dùng kỹ năng verification-before-completion nếu bạn:

• Làm việc trong codebase nơi test fail, build hỏng hoặc sửa lỗi chưa được kiểm chứng thường xuyên lọt qua
• Dựa vào agent hoặc công cụ tự động có thể tuyên bố thành công mà không thực sự chạy kiểm tra
• Muốn có một thực hành kiểm thử và kiểm chứng có kỷ luật, lặp lại được, gắn chặt với quy trình phát triển của bạn

Kỹ năng này đặc biệt hữu ích cho:

• Tự động hóa kiểm thử: đảm bảo test suite thực sự được chạy và kết quả được hiểu đúng
• Tự động hóa quy trình: buộc các bước hoàn thành luôn đi kèm lệnh kiểm chứng
• Các team làm code review, continuous integration, continuous delivery và muốn giảm tối đa bất ngờ sau khi đánh dấu "done".

verification-before-completion giải quyết vấn đề gì?

Nếu không có lan can bảo vệ, rất dễ:

• Cho rằng test sẽ pass vì thay đổi chỉ là "nhỏ"
• Tuyên bố bug đã được sửa sau khi chỉnh code mà không chạy lại kịch bản từng bị lỗi
• Dựa vào một bản build đã từng thành công thay vì build lại sau khi có thay đổi

Kỹ năng verification-before-completion định nghĩa một Iron Law (Luật Sắt) trong repository:

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

Khi áp dụng kỹ năng này, bạn biến luật đó thành quy tắc quy trình cụ thể cho bản thân, cho team hoặc cho các agent. Điều này giúp giảm:

• Các tuyên bố "xanh" sai trong pull request
• Các hồi quy ẩn chưa từng được test
• Hiểu nhầm giữa lập trình viên, người review và hệ thống tự động

Khi nào kỹ năng này phù hợp?

Hãy chọn verification-before-completion khi:

• Bạn đã có sẵn các lệnh test, lint hoặc build và muốn chắc chắn rằng chúng luôn được chạy
• Bạn dùng agent hoặc script để hỗ trợ nhiệm vụ phát triển và cần chúng tuân thủ nghiêm ngặt quy tắc kiểm chứng
• Bạn coi trọng báo cáo trạng thái đáng tin cậy hơn là tiết kiệm vài giây trong quy trình

Kỹ năng này có thể ít hữu ích hơn nếu:

• Dự án của bạn chưa có kiểm tra tự động đáng kể (không có test, không lint, không lệnh build)
• Bạn đang làm việc mang tính khám phá, chưa sẵn sàng đưa ra tuyên bố kiểu "passing" hay "fixed"
• Bạn chỉ dùng repository như tài liệu tham khảo ý tưởng, chứ không dùng để áp quy trình

Trong những trường hợp đó, bạn vẫn có thể dùng kỹ năng này như một hướng dẫn để thiết kế test và kiểm tra trong tương lai.

Cách sử dụng

Cài đặt và thiết lập

Để cài đặt kỹ năng verification-before-completion qua npx:

npx skills add https://github.com/obra/superpowers --skill verification-before-completion

Sau khi cài đặt:

1. Mở thư mục skills/verification-before-completion trong repository obra/superpowers.
2. Bắt đầu với file SKILL.md để xem đầy đủ quy tắc và lý do phía sau.
3. Tích hợp quy tắc này vào tài liệu dự án của bạn, cấu hình agent, hoặc hướng dẫn phát triển.

Bạn không cần sao chép nguyên cấu trúc repository. Hãy dùng nó như tài liệu tham khảo để mô tả và áp dụng quy tắc trong môi trường của riêng bạn.

Quy trình cốt lõi: Gate Function

Kỹ năng này định nghĩa một Gate Function phải được chạy trước mọi tuyên bố hoàn thành. Trong công việc hàng ngày, hãy áp dụng như sau:

TRƯỚC KHI tuyên bố bất kỳ trạng thái nào hoặc thể hiện hài lòng:

1. IDENTIFY: Lệnh nào chứng minh cho tuyên bố này?
2. RUN: Chạy TOÀN BỘ lệnh (mới, đầy đủ)
3. READ: Đọc toàn bộ output, kiểm tra exit code, đếm số lỗi
4. VERIFY: Output có xác nhận cho tuyên bố không?
   - Nếu KHÔNG: Nêu trạng thái thực tế kèm bằng chứng
   - Nếu CÓ: Nêu tuyên bố KÈM bằng chứng
5. CHỈ SAU ĐÓ: Mới được đưa ra tuyên bố

Bỏ qua bất kỳ bước nào nghĩa là bạn không còn tuân thủ verification-before-completion.

Ví dụ các lệnh thường dùng:

• Test: npm test, pytest, go test ./..., mvn test
• Lint: eslint ., flake8, golangci-lint run
• Build: npm run build, make, cargo build --release
• Kiểm chứng bug cụ thể: script, test hoặc thao tác manual tái hiện lại lỗi ban đầu

Ví dụ: dùng kỹ năng trong quy trình phát triển

Kịch bản: Bạn đã cập nhật code và muốn tuyên bố "All tests pass".

Áp dụng verification-before-completion:

1. IDENTIFY lệnh phù hợp: ví dụ pytest.
2. RUN lệnh đó sau khi sửa code:

   pytest
   

3. READ output và xác nhận exit code 0.
4. VERIFY:
   • Nếu test fail, không được tuyên bố thành công. Thay vào đó, báo cáo kiểu: "Tests are failing: 3 tests failing in test_user_flow.py. See pytest output."
   • Nếu test pass, bạn có thể nói: "All tests pass (pytest, exit code 0)."
5. ONLY THEN mới đánh dấu nhiệm vụ hoàn thành, push commit hoặc mở pull request.

Bạn có thể áp dụng mẫu này cho mọi loại tuyên bố trạng thái: build, linter, format hay sửa bug.

Tích hợp với agent và tự động hóa

Nếu bạn dùng agent hoặc script hỗ trợ phát triển:

• Hãy cấu hình để mọi tuyên bố liên quan đến test, build hoặc sửa lỗi đều phải đi sau một lệnh cụ thể đã được chạy kèm tóm tắt output.
• Yêu cầu agent dẫn rõ lệnh đã chạy và kết quả, ví dụ:
  • "Ran npm test: exit code 0, 0 failing tests."
  • "Ran npm run build: exit code 1, build failed. Not claiming completion."

Trong review hoặc pipeline CI, bạn có thể coi mọi tuyên bố không kèm bằng chứng là chưa hoàn chỉnh theo tiêu chuẩn verification-before-completion.

Điều chỉnh cho công cụ và môi trường của bạn

Repository này không áp đặt ngôn ngữ hay framework cụ thể. Để điều chỉnh kỹ năng cho phù hợp:

• Ánh xạ mỗi loại tuyên bố phổ biến sang một lệnh duy nhất, rõ ràng có thể chứng minh nó.
• Ghi lại các ánh xạ đó trong repo của bạn (ví dụ trong CONTRIBUTING.md hoặc WORKFLOW.md).
• Khuyến khích hoặc yêu cầu contributor và agent luôn:
  • Chạy các lệnh này trước khi nói "done"
  • Dán hoặc tóm tắt output liên quan khi đưa ra tuyên bố

Ví dụ ánh xạ tuyên bố–lệnh:

• "Backend tests pass" → pytest backend/tests
• "Frontend builds successfully" → npm run build trong frontend/
• "Go module is clean" → go test ./... và golangci-lint run

Câu hỏi thường gặp (FAQ)

Quy tắc chính của verification-before-completion là gì?

Quy tắc chính là "Iron Law":

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

Nếu bạn chưa vừa chạy lệnh kiểm chứng liên quan và xem output của nó, bạn không thể trung thực mà tuyên bố là đã thành công.

"Bằng chứng kiểm chứng" được tính là gì?

Bằng chứng kiểm chứng là output mới từ một lệnh trực tiếp kiểm tra tuyên bố của bạn, ví dụ:

• Một lần chạy test suite cho thấy 0 lỗi và exit code 0
• Một lần chạy linter không báo lỗi và có exit status thành công
• Lệnh build hoàn tất thành công (exit 0)
• Một script hoặc test tái hiện bug trước đây, giờ đã pass

Kết quả cũ, suy đoán hoặc kiểu "chắc là được" không được coi là bằng chứng trong kỹ năng này.

Tôi có thể dựa vào lần chạy test trước nếu code không đổi không?

Theo verification-before-completion, mặc định là không. Kỹ năng này nhấn mạnh việc kiểm chứng lại trước mỗi lần bạn tuyên bố hoàn thành. Nếu bạn muốn dựa vào kết quả cũ, bạn phải nêu rõ và cân nhắc kỹ điều kiện chấp nhận, đồng thời chấp nhận rằng điều đó làm suy yếu mức đảm bảo.

Kỹ năng này có yêu cầu công cụ hay ngôn ngữ cụ thể không?

Không. Kỹ năng verification-before-completion độc lập với công cụ. Nó hoạt động với bất kỳ stack nào mà bạn có thể:

• Định nghĩa lệnh dùng để kiểm chứng hành vi (test, linter, build, script)
• Chạy chúng theo yêu cầu
• Diễn giải được exit code và output

Bạn chỉ cần điền các lệnh phù hợp với dự án của mình và làm theo các bước trong Gate Function.

Điều này khác gì so với thỉnh thoảng "chạy test"?

Điểm khác biệt là tính kỷ luật và nhất quán:

• Bạn chạy lệnh kiểm chứng mỗi lần trước khi tuyên bố hoàn thành.
• Bạn luôn đọc output thay vì mặc định là thành công.
• Bạn coi mọi tuyên bố không có bằng chứng là không hợp lệ.

Điều này biến việc chạy test và build thành một cổng kiểm soát chính thức, chứ không phải bước tùy chọn.

verification-before-completion có phù hợp cho kiểm thử thủ công không?

Có, miễn là bạn định nghĩa được một quy trình rõ ràng đóng vai trò như một "lệnh" cho tuyên bố. Ví dụ:

• Ghi lại các bước kiểm thử manual để tái hiện bug
• Chạy lại các bước đó sau khi sửa
• Ghi nhận kết quả như một dạng bằng chứng

Tuy nhiên, kỹ năng này phát huy hiệu quả tốt nhất khi kiểm chứng được tự động hóa qua script hoặc framework test, để kết quả dễ lặp lại và chạy lại.

Tôi có thể xem định nghĩa gốc của kỹ năng ở đâu?

Mô tả chính thức cho kỹ năng verification-before-completion nằm trong file SKILL.md của repository obrа/superpowers:

• Repository: https://github.com/obra/superpowers
• File kỹ năng: skills/verification-before-completion/SKILL.md

Hãy tham khảo file đó để xem cách diễn đạt chính xác của nguyên tắc, Iron Law, Gate Function và các ví dụ về lỗi phổ biến cần tránh.