Cách xây dựng quy trình lập trình AI nhất quán với Viserys

Viserys là gì?

Viserys là một bộ sưu tập khép kín các quy trình kỹ thuật dành cho tác nhân lập trình AI. Thay vì để tác nhân tự tạo quy trình cho từng yêu cầu, Viserys cung cấp các hướng dẫn Markdown có thể tái sử dụng, vai trò người đánh giá, tài liệu tham chiếu dùng chung, lệnh theo vòng đời, bộ dữ liệu đánh giá và tập lệnh xác thực.

Dự án tổ chức công việc phần mềm theo vòng đời gồm sáu giai đoạn:

DEFINE -> PLAN -> BUILD -> VERIFY -> REVIEW -> SHIP

Mỗi quy trình nằm trong một tệp SKILL.md và bao gồm các bước thực hiện, tiêu chí hoàn tất cùng hướng dẫn chống hợp lý hóa. Vì các kỹ năng được viết bằng Markdown thuần túy, chúng có thể được các tác nhân lập trình hỗ trợ kỹ năng tải vào hoặc được đọc trực tiếp như những hướng dẫn độc lập.

Tính năng chính

• Hỗ trợ toàn bộ vòng đời: Các quy trình bao quát việc thu thập yêu cầu, lập kế hoạch, triển khai, kiểm thử, đánh giá và chuẩn bị phát hành.
• 26 kỹ năng đóng gói: Thư mục skills/ chứa các quy trình kỹ thuật có thể tái sử dụng.
• Vai trò người đánh giá: Các tác nhân chuyên biệt đánh giá chất lượng mã, kiểm thử, bảo mật và hiệu năng web.
• Tích hợp OpenCode: Tác nhân Viserys ở chế độ chính được tích hợp sẵn và tải các kỹ năng mà không cần cấu hình toàn cục.
• Tài liệu tham chiếu dùng chung: Có thể tải các danh sách kiểm tra khi cần thay vì luôn đưa chúng vào ngữ cảnh của tác nhân.
• Xác thực và đánh giá: Các tập lệnh Node.js kiểm tra kỹ năng, lệnh, đường dẫn thành phẩm, liên kết tham chiếu, phiên bản và các trường hợp đánh giá.

Tìm hiểu cấu trúc kho lưu trữ

• skills/ chứa các quy trình kỹ năng.
• agents/ chứa bốn vai trò người đánh giá chuyên biệt.
• references/ cung cấp các danh sách kiểm tra dùng chung, tải theo nhu cầu.
• commands/ định nghĩa các lệnh theo vòng đời.
• evals/ chứa các trường hợp đánh giá kỹ năng và dữ liệu mẫu.
• scripts/ chứa các trình xác thực và trình chạy đánh giá.
• hooks/ cung cấp các hook theo vòng đời phiên.
• docs/ chứa tài liệu nội bộ.
• .opencode/agent/viserys.md định nghĩa tác nhân OpenCode.
• .opencode/opencode.json đăng ký các đường dẫn kỹ năng cho OpenCode.

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

Tùy chọn 1: Kích hoạt Viserys trong OpenCode

1. Sao chép kho lưu trữ Viserys bằng Git.
2. Mở thư mục kho lưu trữ đã sao chép trong OpenCode.
3. Nhấn Tab để mở bộ chọn tác nhân.
4. Chọn viserys.

Tác nhân Viserys tích hợp sẵn chạy ở chế độ chính, vì vậy nó xuất hiện trong danh sách tác nhân của OpenCode. Lời nhắc của tác nhân sẽ kiểm tra kỹ năng phù hợp trước khi xử lý yêu cầu và điều phối công việc theo vòng đời của dự án. Cấu hình OpenCode cấp kho lưu trữ đăng ký tất cả kỹ năng đã đóng gói, nên không cần cấu hình toàn cục.

Tùy chọn 2: Sử dụng Viserys với tác nhân hỗ trợ kỹ năng khác

Với Claude Code, Cursor hoặc một tác nhân khác hỗ trợ các kỹ năng có thể tái sử dụng, hãy trỏ tác nhân đến thư mục skills/ của kho lưu trữ. Ngoài ra, bạn có thể sao chép thư mục đó vào vị trí lưu trữ kỹ năng gốc của công cụ.

Đích chính xác tùy thuộc vào tác nhân lập trình. Viserys không yêu cầu chuyển đổi các quy trình Markdown sang định dạng khác, nhưng công cụ máy chủ phải biết nơi khám phá chúng.

Tùy chọn 3: Sử dụng các kỹ năng dưới dạng ngữ cảnh thuần túy

Nếu tác nhân không có hệ thống kỹ năng gốc, hãy mở tệp SKILL.md liên quan và cung cấp nội dung của tệp làm ngữ cảnh. Mỗi kỹ năng được thiết kế để hoạt động độc lập, vì vậy bạn có thể tự làm theo các bước hoặc yêu cầu tác nhân làm theo chúng.

Chọn quy trình phù hợp

Bắt đầu với kỹ năng meta using-agent-skills khi bạn không chắc quy trình nào phù hợp. Nếu không, hãy chọn kỹ năng dựa trên giai đoạn hiện tại của vòng đời.

DEFINE: Làm rõ công việc

• Dùng idea-refine khi ý tưởng còn mơ hồ và cần được khám phá có cấu trúc.
• Dùng interview-me khi cần thu thập yêu cầu theo từng câu hỏi một.
• Dùng spec-driven-development trước khi bắt đầu một dự án, tính năng hoặc thay đổi đáng kể khi chưa có đặc tả.
• Dùng constraint-driven-development khi chưa có tiêu chuẩn chất lượng hoặc các bước kiểm tra đang bị vô hiệu hóa chỉ để khiến bản dựng vượt qua.

PLAN: Chuyển đặc tả thành nhiệm vụ

Sau khi yêu cầu đã ổn định, hãy dùng planning-and-task-breakdown. Kỹ năng này chuyển đặc tả thành các nhiệm vụ theo thứ tự, có thể xác minh và kèm tiêu chí chấp nhận.

BUILD: Triển khai có chủ đích

• incremental-implementation giúp các thay đổi trải rộng trên nhiều tệp được thực hiện theo những phần nhỏ.
• test-driven-development áp dụng khi triển khai logic, sửa lỗi hoặc thay đổi hành vi.
• context-engineering hỗ trợ khởi tạo phiên, chuyển đổi nhiệm vụ hoặc khôi phục khi chất lượng đầu ra suy giảm.
• source-driven-development phù hợp khi tính chính xác phụ thuộc vào tài liệu chính thức hiện hành.
• doubt-driven-development khuyến khích xác minh khi mức độ rủi ro cao và kiểm tra ngay lúc này ít tốn kém hơn gỡ lỗi về sau.
• frontend-ui-engineering hướng dẫn công việc xây dựng giao diện dành cho người dùng.
• api-and-interface-design hỗ trợ thiết kế API, ranh giới mô-đun và giao diện công khai.

VERIFY: Chứng minh thay đổi hoạt động

• Dùng browser-testing-with-devtools cho việc triển khai hoặc gỡ lỗi dựa trên trình duyệt.
• Dùng debugging-and-error-recovery khi kiểm thử thất bại, bản dựng bị lỗi hoặc hành vi lúc chạy không như dự kiến.

REVIEW: Đánh giá chất lượng và rủi ro

• Nên sử dụng code-review-and-quality trước khi hợp nhất một thay đổi.
• code-simplification hữu ích khi mã đang hoạt động nhưng vẫn khó hiểu hoặc khó bảo trì.
• security-and-hardening áp dụng cho dữ liệu đầu vào của người dùng, xác thực, lưu trữ dữ liệu và các tích hợp bên ngoài.
• performance-optimization áp dụng khi có yêu cầu về hiệu suất hoặc nghi ngờ xảy ra suy giảm hiệu suất.

SHIP: Chuẩn bị cho môi trường production

• git-workflow-and-versioning định hướng các thay đổi mã và việc kiểm soát phiên bản.
• ci-cd-and-automation hỗ trợ các thay đổi đối với quy trình build và triển khai.
• deprecation-and-migration hỗ trợ loại bỏ các hệ thống cũ hoặc di chuyển người dùng.
• documentation-and-adrs ghi lại các quyết định kiến trúc và thay đổi API công khai.
• observability-and-instrumentation bao quát log, chỉ số, trace và cảnh báo.
• shipping-and-launch hướng dẫn chuẩn bị triển khai production cuối cùng.

Ví dụ sử dụng cơ bản

Giả sử bạn yêu cầu một tác nhân lập trình AI thêm một endpoint API mới có xác thực. Thay vì bắt tay ngay vào triển khai, hãy áp dụng vòng đời theo đúng trình tự.

1. DEFINE: Chạy interview-me nếu các quy tắc xác thực, dữ liệu đầu vào hoặc phản hồi chưa rõ ràng. Sau đó dùng spec-driven-development để xác lập hành vi mong đợi.
2. PLAN: Áp dụng planning-and-task-breakdown để tạo danh sách tác vụ theo thứ tự và tiêu chí chấp nhận.
3. BUILD: Dùng api-and-interface-design cho hợp đồng của endpoint và test-driven-development cho hành vi. Nếu cần thay đổi nhiều tệp, hãy dùng thêm incremental-implementation.
4. VERIFY: Nếu kiểm thử thất bại hoặc endpoint hoạt động không như dự kiến, hãy làm theo debugging-and-error-recovery.
5. REVIEW: Áp dụng code-review-and-quality và security-and-hardening vì tính năng này xử lý xác thực và dữ liệu đầu vào.
6. SHIP: Sử dụng các quy trình Git, tài liệu, khả năng quan sát và phát hành phù hợp trước khi triển khai production.

Khi đã bật tích hợp OpenCode, tác nhân Viserys được thiết kế để trước tiên kiểm tra các skill phù hợp. Trong thiết lập ngữ cảnh thuần túy, bạn tự thực hiện việc lựa chọn này và yêu cầu tác nhân làm theo từng quy trình Markdown đã chọn.

Sử dụng các persona đánh giá

Viserys bao gồm bốn persona đánh giá trong agents/. Chúng cung cấp các góc nhìn chuyên sâu, bổ trợ cho các skill trong vòng đời.

• agents/code-reviewer.md thực hiện đánh giá theo năm trục, sử dụng tiêu chuẩn phê duyệt của kỹ sư cấp staff.
• agents/test-engineer.md xem xét chiến lược và độ bao phủ kiểm thử bằng mô hình prove-it.
• agents/security-auditor.md bao quát việc phát hiện lỗ hổng, lập mô hình mối đe dọa và đánh giá OWASP.
• agents/web-performance-auditor.md kiểm tra Core Web Vitals ở chế độ nhanh hoặc chuyên sâu.

Hãy chọn persona dựa trên các rủi ro của thay đổi. Ví dụ, kết hợp security auditor với security-and-hardening khi làm việc về xác thực, hoặc sử dụng web performance auditor sau khi chỉnh sửa giao diện hướng đến người dùng.

Xác thực bộ quy trình

Chạy các script Node.js được cung cấp sau khi thay đổi skill, command, tài liệu tham chiếu, phiên bản hoặc fixture đánh giá:

node scripts/validate-skills.js
node scripts/validate-commands.js
node scripts/validate-artifact-paths.js
node scripts/validate-reference-links.js
node scripts/validate-versions.js
node scripts/run-evals.js

Các lệnh này xác thực cấu trúc nội bộ của bộ quy trình và chạy bộ đánh giá. Chúng đặc biệt quan trọng khi mở rộng Viserys thay vì chỉ sử dụng các quy trình hiện có.

Mẹo nâng cao

Kết hợp các skill mà không bỏ qua các cổng của vòng đời

Một tác vụ có thể cần nhiều skill. Ví dụ, một tính năng trình duyệt có thể kết hợp frontend-ui-engineering, test-driven-development và browser-testing-with-devtools. Hãy giữ các tiêu chí hoàn tất của từng skill luôn hiển thị để việc bổ sung quy trình không biến thành hoạt động prompt thiếu cấu trúc.

Chỉ tải tài liệu tham chiếu khi cần

Thư mục references/ dành cho các checklist dùng chung được tải theo nhu cầu. Điều này giúp tập trung ngữ cảnh đang hoạt động của tác nhân, đồng thời vẫn duy trì quyền truy cập vào hướng dẫn chi tiết.

Sử dụng nguồn chính thức cho công việc phụ thuộc phiên bản

Áp dụng source-driven-development khi các chi tiết triển khai phụ thuộc vào tài liệu hiện hành. Kết hợp với doubt-driven-development khi một giả định có vẻ hợp lý nhưng sai có thể gây tốn kém.

Khôi phục khi chất lượng của tác nhân suy giảm

Nếu một phiên làm việc dài trở nên thiếu nhất quán, hãy sử dụng context-engineering. Skill này được thiết kế riêng cho việc thiết lập phiên, chuyển đổi tác vụ và các tình huống chất lượng đầu ra bị giảm.

Tham khảo tài liệu đi kèm

• docs/README.md giải thích về bộ quy trình và bản đồ vòng đời.
• docs/skill-anatomy.md định nghĩa định dạng SKILL.md.
• evals/README.md giải thích cách thức đánh giá skill.

Hãy đọc đặc tả cấu trúc skill trước khi thêm hoặc tái cấu trúc quy trình, sau đó chạy các trình xác thực và bài đánh giá để kiểm tra kết quả.

Kết luận

Viserys biến quá trình phát triển có AI hỗ trợ thành một quy trình kỹ thuật có thể lặp lại. Bắt đầu bằng cách kết nối thư mục skills/ với một tác nhân tương thích hoặc chọn tác nhân Viserys đi kèm trong OpenCode. Sau đó lần lượt thực hiện DEFINE, PLAN, BUILD, VERIFY, REVIEW và SHIP một cách có chủ đích, sử dụng các persona chuyên biệt và script xác thực khi chúng tạo thêm giá trị.