AgentSkillsCN

openspec-verify-change

验证部署内容与变更工件是否匹配。当用户希望在正式存储之前，确认部署内容完整、准确且一致时，可使用此技能。

SKILL.md
--- frontmatter
name: openspec-verify-change
description: Xác minh việc triển khai khớp với các artifact của thay đổi. Sử dụng khi người dùng muốn xác thực rằng việc triển khai là đầy đủ, chính xác và nhất quán trước khi lưu trữ.
license: MIT
compatibility: Yêu cầu openspec CLI.
metadata:
  author: openspec
  version: "1.0"
  generatedBy: "1.0.2"

Xác minh rằng việc triển khai (implementation) khớp với các artifact của thay đổi (specs, tasks, design).

Đầu vào: Tùy chọn chỉ định tên thay đổi. Nếu bỏ trống, hãy kiểm tra xem có thể suy luận từ ngữ cảnh cuộc hội thoại hay không. Nếu mơ hồ hoặc không rõ ràng, bạn PHẢI yêu cầu xem danh sách các thay đổi có sẵn.

Các bước

  1. •

    Nếu không cung cấp tên thay đổi, yêu cầu chọn

    Chạy lệnh openspec list --json để lấy danh sách các thay đổi có sẵn. Sử dụng công cụ AskUserQuestion để người dùng chọn.

    Hiển thị các thay đổi có task triển khai (có tồn tại artifact tasks). Bao gồm schema đã được sử dụng cho mỗi thay đổi nếu có. Đánh dấu các thay đổi có task chưa hoàn thành là "(In Progress - Đang thực hiện)".

    QUAN TRỌNG: KHÔNG được đoán hoặc tự ý chọn thay đổi. Luôn để người dùng quyết định.

  2. •

    Kiểm tra trạng thái (status) để hiểu schema

    bash
    openspec status --change "<name>" --json

    Phân tích JSON để hiểu:

    • •schemaName: Workflow đang được sử dụng (ví dụ: "spec-driven").
    • •Artifact nào đang tồn tại cho thay đổi này.
  3. •

    Lấy thư mục thay đổi và tải các artifact

    bash
    openspec instructions apply --change "<name>" --json

    Lệnh này trả về thư mục thay đổi và các file context. Đọc tất cả các artifact có sẵn từ contextFiles.

  4. •

    Khởi tạo cấu trúc báo cáo xác minh

    Tạo một cấu trúc báo cáo với ba khía cạnh:

    • •Tính đầy đủ (Completeness): Theo dõi các task và độ bao phủ của spec.
    • •Tính chính xác (Correctness): Theo dõi việc triển khai yêu cầu và độ bao phủ của kịch bản (scenario).
    • •Tính mạch lạc (Coherence): Theo dõi sự tuân thủ thiết kế và tính nhất quán của các mẫu (pattern).

    Mỗi khía cạnh có thể có các vấn đề ở mức NGHIÊM TRỌNG (CRITICAL), CẢNH BÁO (WARNING), hoặc GỢI Ý (SUGGESTION).

  5. •

    Xác minh Tính đầy đủ (Completeness)

    Hoàn thành Task:

    • •Nếu tasks.md tồn tại trong contextFiles, hãy đọc nó.
    • •Phân tích các checkbox: - [ ] (chưa xong) so với - [x] (đã xong).
    • •Đếm số task đã hoàn thành so với tổng số task.
    • •Nếu tồn tại task chưa hoàn thành:
      • •Thêm vấn đề NGHIÊM TRỌNG cho mỗi task chưa xong.
      • •Khuyến nghị: "Hoàn thành task: <mô tả>" hoặc "Đánh dấu là đã xong nếu đã được triển khai".

    Độ bao phủ của Spec:

    • •Nếu delta specs tồn tại trong openspec/changes/<name>/specs/:
      • •Trích xuất tất cả các yêu cầu (được đánh dấu bằng "### Requirement:").
      • •Với mỗi yêu cầu:
        • •Tìm kiếm trong codebase các từ khóa liên quan đến yêu cầu đó.
        • •Đánh giá xem việc triển khai có khả năng tồn tại hay không.
      • •Nếu các yêu cầu có vẻ chưa được triển khai:
        • •Thêm vấn đề NGHIÊM TRỌNG: "Không tìm thấy yêu cầu: <tên yêu cầu>".
        • •Khuyến nghị: "Triển khai yêu cầu X: <mô tả>".
  6. •

    Xác minh Tính chính xác (Correctness)

    Ánh xạ triển khai yêu cầu:

    • •Với mỗi yêu cầu từ delta specs:
      • •Tìm kiếm bằng chứng triển khai trong codebase.
      • •Nếu tìm thấy, ghi chú đường dẫn file và phạm vi dòng code.
      • •Đánh giá xem việc triển khai có khớp với ý định của yêu cầu hay không.
      • •Nếu phát hiện sự sai lệch:
        • •Thêm CẢNH BÁO: "Việc triển khai có thể sai lệch so với spec: <chi tiết>".
        • •Khuyến nghị: "Xem xét lại <file>:<dòng> so với yêu cầu X".

    Độ bao phủ của kịch bản (Scenario):

    • •Với mỗi kịch bản trong delta specs (được đánh dấu bằng "#### Scenario:"):
      • •Kiểm tra xem các điều kiện có được xử lý trong code không.
      • •Kiểm tra xem có test nào bao phủ kịch bản đó không.
      • •Nếu kịch bản có vẻ chưa được bao phủ:
        • •Thêm CẢNH BÁO: "Kịch bản chưa được bao phủ: <tên kịch bản>".
        • •Khuyến nghị: "Thêm test hoặc triển khai cho kịch bản: <mô tả>".
  7. •

    Xác minh Tính mạch lạc (Coherence)

    Tuân thủ thiết kế:

    • •Nếu design.md tồn tại trong contextFiles:
      • •Trích xuất các quyết định chính (tìm các phần như "Decision:", "Approach:", "Architecture:").
      • •Xác minh việc triển khai có tuân theo các quyết định đó không.
      • •Nếu phát hiện mâu thuẫn:
        • •Thêm CẢNH BÁO: "Quyết định thiết kế không được tuân thủ: <quyết định>".
        • •Khuyến nghị: "Cập nhật triển khai hoặc sửa đổi design.md để khớp với thực tế".
    • •Nếu không có design.md: Bỏ qua bước kiểm tra tuân thủ thiết kế, ghi chú "Không có design.md để xác minh".

    Tính nhất quán của mẫu code (Code Pattern):

    • •Xem xét code mới để đảm bảo tính nhất quán với các mẫu của dự án.
    • •Kiểm tra cách đặt tên file, cấu trúc thư mục, phong cách lập trình.
    • •Nếu tìm thấy các sai lệch đáng kể:
      • •Thêm GỢI Ý: "Sai lệch mẫu code: <chi tiết>".
      • •Khuyến nghị: "Cân nhắc tuân theo mẫu của dự án: <ví dụ>".
  8. •

    Tạo Báo cáo Xác minh

    Bảng điểm tóm tắt (Summary Scorecard):

    code
    ## Báo cáo Xác minh: <change-name>

### Tóm tắt
| Khía cạnh     | Trạng thái        |
|---------------|-------------------|
| Tính đầy đủ   | X/Y task, N yêu cầu|
| Tính chính xác | M/N yêu cầu được bao phủ |
| Tính mạch lạc | Tuân thủ / Có vấn đề |

    Các vấn đề theo mức độ ưu tiên:

    1. •

      NGHIÊM TRỌNG (CRITICAL) (Phải sửa trước khi lưu trữ):

      • •Các task chưa hoàn thành.
      • •Thiếu việc triển khai các yêu cầu.
      • •Mỗi vấn đề kèm theo khuyến nghị cụ thể, có thể thực hiện được.
    2. •

      CẢNH BÁO (WARNING) (Nên sửa):

      • •Sự sai lệch so với spec/design.
      • •Thiếu độ bao phủ kịch bản.
      • •Mỗi vấn đề kèm theo khuyến nghị cụ thể.
    3. •

      GỢI Ý (SUGGESTION) (Nên cải thiện):

      • •Sự không nhất quán về mẫu code.
      • •Các cải tiến nhỏ.
      • •Mỗi vấn đề kèm theo khuyến nghị cụ thể.

    Đánh giá cuối cùng:

    • •Nếu có vấn đề NGHIÊM TRỌNG: "Tìm thấy X vấn đề nghiêm trọng. Cần sửa trước khi lưu trữ."
    • •Nếu chỉ có cảnh báo: "Không có vấn đề nghiêm trọng. Có Y cảnh báo cần cân nhắc. Sẵn sàng lưu trữ (với các cải tiến đã nêu)."
    • •Nếu tất cả đều ổn: "Tất cả các kiểm tra đã vượt qua. Sẵn sàng lưu trữ."

Các quy tắc suy luận xác minh (Verification Heuristics)

  • •Tính đầy đủ: Tập trung vào các mục tiêu khách quan (checkbox, danh sách yêu cầu).
  • •Tính chính xác: Sử dụng tìm kiếm từ khóa, phân tích đường dẫn file, suy luận hợp lý - không yêu cầu sự chắc chắn tuyệt đối.
  • •Tính mạch lạc: Tìm kiếm các điểm không nhất quán rõ ràng, không soi xét quá kỹ về phong cách.
  • •Dương tính giả: Khi không chắc chắn, hãy ưu tiên chọn GỢI Ý thay vì CẢNH BÁO, CẢNH BÁO thay vì NGHIÊM TRỌNG.
  • •Khả năng thực thi: Mỗi vấn đề phải có một khuyến nghị cụ thể kèm theo tham chiếu file/dòng code nếu có thể.

Xử lý khi thiếu thông tin (Graceful Degradation)

  • •Nếu chỉ có tasks.md: chỉ xác minh việc hoàn thành task, bỏ qua kiểm tra spec/design.
  • •Nếu có tasks + specs: xác minh tính đầy đủ và chính xác, bỏ qua thiết kế.
  • •Nếu có đầy đủ artifact: xác minh cả ba khía cạnh.
  • •Luôn ghi chú các kiểm tra nào đã bị bỏ qua và lý do.

Định dạng đầu ra

Sử dụng markdown rõ ràng với:

  • •Bảng cho bảng điểm tóm tắt.
  • •Danh sách nhóm cho các vấn đề (NGHIÊM TRỌNG/CẢNH BÁO/GỢI Ý).
  • •Tham chiếu code theo định dạng: file.ts:123.
  • •Các khuyến nghị cụ thể, có thể thực hiện được.
  • •Không sử dụng các gợi ý mơ hồ như "cân nhắc xem xét lại".