Khi AI Skill được dùng trong nhiều quy trình, một thay đổi nhỏ ở description, instructions hoặc output contract cũng có thể làm hỏng bước kế tiếp. Versioning AI Skill là cách ghi nhận phiên bản, phạm vi thay đổi và khả năng tương thích để cập nhật có kiểm soát, dễ kiểm thử và có thể quay lại bản ổn định.
Versioning AI Skill là gì?
Versioning là việc gắn số phiên bản và lịch sử thay đổi cho Skill, thay vì sửa trực tiếp rồi không biết bản nào đang chạy. Mỗi phiên bản nên trả lời: thay đổi điều gì, ảnh hưởng đến ai và cần chạy lại bộ test nào.
Vì sao sửa Skill không có version dễ gây lỗi?
Khi tên trường output đổi, trigger rộng hơn hoặc giới hạn bị bỏ, các thành phần phụ thuộc có thể nhận dữ liệu sai. Không có version, việc truy tìm nguyên nhân và phục hồi trở nên khó khăn.
Ba lớp cần version riêng
Description và trigger là lớp định tuyến; instructions và references là lớp thực thi; output contract và handoff là lớp giao tiếp. Mỗi lớp có thể tạo ra rủi ro khác nhau khi thay đổi.
Quy tắc đặt phiên bản thực dụng
Dùng bản vá cho sửa lỗi không đổi contract, bản phụ cho bổ sung tương thích và bản chính cho thay đổi trigger, trường bắt buộc, kiểu dữ liệu hoặc hành vi khiến consumer phải cập nhật.
Changelog cần ghi những gì?
Mỗi mục nên có phiên bản, ngày, lý do, trường hoặc rule bị ảnh hưởng, test đã chạy và hướng di chuyển. Changelog giúp truy vết quyết định thay vì chỉ ghi ngày sửa file.
Cập nhật output contract mà không phá consumer
Ưu tiên thêm trường tùy chọn trước khi đổi trường bắt buộc. Nếu đổi tên, duy trì alias trong giai đoạn chuyển tiếp. Khi đổi kiểu dữ liệu hoặc trạng thái lỗi, tăng phiên bản chính và yêu cầu consumer xác nhận.
Quy trình phát hành và rollback
Ghi mục tiêu, tạo bản sao phiên bản mới, cập nhật các lớp liên quan, chạy positive, negative, conflict và edge case, kiểm tra handoff với consumer cũ, phát hành có thể quay lại và theo dõi lỗi. Rollback khi kích hoạt nhầm tăng, output thiếu trường hoặc handoff bị lỗi.
Bộ test hồi quy cho version mới
Test trigger đúng, negative control, contract test, handoff test và rollback test. Mỗi test lưu đầu vào, phiên bản, kết quả mong đợi và kết quả thực tế.
Checklist trước khi đóng gói
Có số phiên bản và changelog; biết lớp nào thay đổi; kiểm tra tương thích consumer; có fixture bản cũ; chạy positive, negative, conflict, edge và rollback case; có kế hoạch alias hoặc deprecation.
Có cần tăng phiên bản cho mọi lần sửa câu chữ?
Không. Nếu sửa câu chữ không đổi phạm vi, hành vi hoặc output contract, có thể ghi dưới dạng bản vá nhưng vẫn nên cập nhật changelog.
Khi nào thay đổi được xem là breaking change?
Khi consumer phải sửa để tiếp tục hoạt động, chẳng hạn đổi tên trường bắt buộc, đổi kiểu dữ liệu, bỏ trạng thái lỗi hoặc mở rộng trigger.
Có nên giữ nhiều phiên bản AI Skill cùng lúc?
Có thể giữ bản cũ trong giai đoạn chuyển tiếp nếu có consumer chưa nâng cấp. Hãy ghi rõ bản mặc định, thời hạn deprecation và cách chuyển sang bản mới.
Versioning biến việc sửa AI Skill thành quy trình có thể kiểm soát. Hãy tách lớp định tuyến, thực thi và giao tiếp; ghi changelog; kiểm thử contract và handoff; đồng thời chuẩn bị rollback. Đọc thêm output contract cho AI Skill, handoff giữa nhiều AI Skill và bộ test hồi quy.