SpecGuard - plugin CLI/Codex kiểm tra đặc tả trước khi AI viết mã

Xin chào. Tôi đang tạo ra một công cụ mã nguồn mở tên là SpecGuard.

Khi dùng các công cụ AI coding như Codex hay Claude Code, tốc độ triển khai chắc chắn tăng lên. Nhưng sau khi dùng lặp lại vài lần, tôi nhận ra vấn đề mình thường gặp trên thực tế không hẳn là “AI không biết viết code” mà gần hơn với việc “bản đặc tả giao cho AI vốn đã không hoàn chỉnh”.

Nếu đặc tả có khiếm khuyết, AI sẽ tự suy đoán để lấp vào các khoảng trống đó rồi triển khai. Lúc đầu trông có vẻ hợp lý, nhưng càng phát triển thì các vấn đề sau càng lớn lên.

• Chất lượng và cấu trúc của code dần dần xuống cấp.
• Đặc tả và code ngày càng không còn khớp nhau.
• Về sau rất khó phân biệt là code sai, đặc tả đã lỗi thời, hay ngay từ đầu yêu cầu đã mơ hồ.

Vì vậy tôi nghĩ chỉ review code sau khi triển khai thôi là chưa đủ. Trước khi một bản đặc tả có lỗi được chuyển nguyên trạng cho agent triển khai, cần có một bước làm lộ ra các khoảng trống của chính đặc tả đó.

SpecGuard là plugin CLI/Codex được tạo ra để giảm vấn đề này. Đây không phải công cụ kiểm tra kết quả sau khi sinh code, mà là công cụ kiểm tra đặc tả trước khi giao việc triển khai cho AI.

Luồng cơ bản mà tôi hướng tới như sau.

1. Con người viết đặc tả sản phẩm.
2. Kiểm tra đặc tả bằng SpecGuard.
3. Nếu là NOT_READY thì bổ sung đặc tả.
4. Khi đạt READY thì chuyển cho các agent triển khai như Codex/Claude Code.

SpecGuard chủ yếu tìm các kiểu lỗ hổng như sau.

• Ranh giới xác thực/phân quyền không rõ ràng
• Thiếu phạm vi ownership của tenant/user
• Không có xử lý cho idempotency, replay, race condition
• Quy tắc hết hạn/thu hồi/chuyển trạng thái còn mơ hồ
• Không có chính sách retry cho side effect bên ngoài, webhook, background job
• Các yêu cầu chỉ tin vào kiểm tra phía client

Kết quả được chia thành ba loại lớn.

• READY: Có thể chuyển cho agent triển khai
• READY_WITH_WARNINGS: Có thể chuyển nhưng có điểm cần lưu ý
• NOT_READY: Có vấn đề Critical/Major nên cần bổ sung đặc tả

Đường mặc định là kiểm tra heuristic bằng --no-llm. Lý do là trong CI hay PR Review, kết quả nhanh và có thể tái hiện được là rất quan trọng. Có thể gắn thêm review chi tiết dựa trên OpenAI Platform hoặc Codex, nhưng hiện tại tôi để đó như một nhánh phụ dùng tùy chọn khi muốn xem sâu hơn.

Những gì được thêm trong v0.4.0

Trong bản v0.4.0 này, tôi đã thêm MVP plugin cho ứng dụng Codex.

pip install spec-guard  
specguard --help  
codex plugin marketplace add KoreaNirsa/spec-guard --ref main  

Nếu chọn source SpecGuard Plugins trong ứng dụng Codex và cài plugin SpecGuard, bạn có thể yêu cầu chạy SpecGuard ngay bên trong Codex. Ví dụ sau khi tạo đặc tả mẫu

specguard example copy specs/your-feature-name --force  

Hãy mở thư mục đó trong Codex rồi có thể yêu cầu như sau.

1. @SpecGuard hãy chạy SpecGuard cho specs/your-feature-name.  
2. @SpecGuard hãy chạy SpecGuard cho gói đặc tả specs/your-feature-name và tóm tắt trạng thái READY/NOT_READY cùng các finding chính.  
3. @SpecGuard hãy chạy SpecGuard cho specs/your-feature-name. Hãy dùng kiểm tra heuristic mặc định và tóm tắt trạng thái kết quả cùng việc cần làm tiếp theo.  

Plugin không triển khai lại engine của SpecGuard. Nó gọi CLI specguard hiện có, rồi đọc kết quả đã sinh ra để tóm tắt trạng thái hiện tại và hành động tiếp theo.

Khi SpecGuard tạo được trạng thái READY, mục tiêu là tạo một tài liệu handoff có thể chuyển cho agent triển khai, rồi sau đó Codex bắt đầu thực hiện phần code.

Cũng hỗ trợ PR Review

Ngoài ra còn có workflow SpecGuard PR Review dựa trên GitHub Actions.

Đây là luồng sẽ chạy SpecGuard Review khi gói đặc tả thay đổi trong PR, rồi để lại kết quả trong PR. Tính năng này hoạt động bằng cách gọi OpenAI.

Mục tiêu không phải là “review code do AI tạo ra” mà là “review đầu vào đặc tả trước khi giao cho AI”.

Bạn có thể dùng khi muốn đặt các quy tắc kiểu như sau trong team.

• Không chuyển đặc tả NOT_READY sang triển khai
• Hiển thị finding Critical/Major trước ngay trong PR
• Quản lý chất lượng đầu vào yêu cầu trước, thay vì chỉ quản lý sản phẩm triển khai đầu ra

Có thể cài đặt bằng specguard actions install-pr-review trong CLI, hoặc yêu cầu Codex @specguard hãy thiết lập workflow SpecGuard PR Review. để cấu hình.

Tuy vậy, vì đây vẫn là tính năng thử nghiệm nên chưa hỗ trợ thiết lập tự động; bạn cần tự cấu hình trong GitHub Secret như dưới đây.

SPECGUARD_OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx  
SPECGUARD_PR_REVIEW_MODEL=gpt-5.4-nano  
SPECGUARD_REVIEW_SPEC_PATHS=specs/your-feature-name  

Tình trạng hiện tại và giới hạn

Đây vẫn là phiên bản đầu nên chưa phải công cụ có thể đánh giá hoàn hảo mọi loại đặc tả.

Tuy vậy, nếu bạn đang dùng AI coding và gặp vấn đề “đặc tả yếu khiến việc triển khai đi chệch hướng”, thì có lẽ có thể dùng nó như một lớp an toàn để lọc trước khi triển khai.

Tôi muốn nhận được phản hồi. Đặc biệt tôi tò mò về các điểm sau.

• Nó phù hợp với những loại đặc tả nào
• Finding nào là quá tay hoặc còn thiếu
• Luồng plugin Codex có thực sự dùng được trong thực tế không
• Việc ép buộc bằng PR Review có phù hợp với workflow của team hay không

Hiện tại vẫn còn ở giai đoạn trước beta, mới chỉ ở mức đang bắt đầu phát triển, nhưng về sau tôi muốn biến nó thành một dự án đủ thực dụng để dùng tốt trong công việc thực tế.

Tôi cũng rất hoan nghênh issue/PR từ những ai quan tâm. Hiện tại issue và PR trong repository chủ yếu được quản lý bằng tiếng Anh, nhưng viết bằng tiếng Hàn cũng không sao.

GitHub : https://github.com/KoreaNirsa/spec-guard

[veltrix]

Bạn có thể xem nội dung chi tiết hơn về dự án này tại https://nirsa.tistory.com/487.