Trả lời nhanh: Khi một người dùng skill thì chỉ cần viết cho đúng. Khi cả đội dùng chung thì phát sinh bốn việc quản lý: đặt kho ở đâu để ai cũng lấy được, quy ước đặt tên và mô tả để hai skill không giẫm chân nhau, quy trình duyệt thay đổi như duyệt code, và ranh giới rõ giữa skill chung của công ty với thói quen riêng của từng người. Bỏ qua bốn việc này thì sau vài tháng kho skill trở thành đống hỗn độn không ai dám sửa.
Viết skill đầu tiên thì dễ. Cái khó xuất hiện ở skill thứ mười lăm, khi năm người cùng thêm bớt và không ai chắc skill nào đang thật sự được dùng. Bài này nói về phần quản trị đó, phần mà tài liệu kỹ thuật ít nhắc nhưng lại quyết định kho skill của bạn sống được bao lâu.
Đặt kho skill ở đâu
Ba mô hình, chọn theo cách đội bạn làm việc:
Trong repo dự án là mặc định tốt. Skill nằm cạnh mã nguồn mà nó phục vụ, ai clone về cũng có, và khi dự án đổi quy ước thì skill đổi theo trong cùng một pull request. Hợp với quy trình gắn chặt với dự án, ví dụ cách viết migration hay cách dựng màn hình theo mẫu.
Một repo chung của công ty hợp với quy trình vượt khỏi phạm vi một dự án, ví dụ quy tắc rà soát bảo mật trước phát hành hay cách viết báo cáo cho khách. Mỗi người kéo về máy rồi trỏ tới, đổi lại phải nhớ cập nhật khi kho thay đổi.
Trong thư mục cá nhân dành cho thói quen riêng, không chia sẻ. Đây là chỗ để những thứ mà áp lên người khác sẽ gây khó chịu.
Nhiều đội dùng cả ba, và ranh giới giữa chúng nên được ghi rõ ở đâu đó, thường là trong file luật chung của dự án như mô tả ở bài CLAUDE.md.
Quy ước đặt tên và mô tả
Chỗ hỏng nhanh nhất của một kho skill đông người là hai skill có mô tả gần giống nhau. Khi đó agent chọn nhầm, và người viết skill thứ hai không hề biết skill thứ nhất đã tồn tại.
Hai quy tắc đủ để chặn phần lớn trường hợp:
- Tên theo việc, không theo công nghệ. Đặt ra-soat-truoc-phat-hanh thay vì bao-mat, vì cái sau quá rộng và sớm muộn sẽ có người viết trùng.
- Mô tả nêu tình huống kèm phạm vi. Viết dùng khi cần rà soát mã nguồn trước lúc phát hành, chỉ áp dụng cho dịch vụ backend. Vế sau chính là thứ giúp phân biệt với một skill tương tự dành cho phía giao diện.
Thêm một thói quen nhỏ mà hiệu quả: trước khi viết skill mới, mở thư mục kho ra đọc lướt danh sách mô tả. Mất một phút và tránh được nhiều tháng lộn xộn.
Duyệt thay đổi như duyệt code
Skill là văn bản chỉ dẫn cho một tác nhân có quyền sửa mã nguồn, nên nó xứng đáng được xem lại nghiêm túc như code. Ba câu hỏi cho người duyệt:
- Mô tả có khiến skill này bị gọi nhầm trong tình huống khác không?
- Các bước có kiểm chứng được không, hay chỉ là những lời khuyên chung chung mà đọc xong vẫn không biết làm gì.
- Phần cấm đã đủ chưa? Đặc biệt với skill động tới dữ liệu, cấu hình máy chủ hoặc thao tác gửi ra ngoài.
Với đội đông, nên có một người chịu trách nhiệm cho kho skill chung, giống vai trò người giữ tài liệu kiến trúc. Không cần chức danh, chỉ cần một người để hỏi khi phân vân skill mới nên nằm ở đâu.
Ranh giới giữa chung và riêng
Câu hỏi thực tế hay gặp: quy ước dùng dấu nháy đơn hay nháy kép, có nên đưa vào skill chung không? Câu trả lời: chỉ khi công cụ định dạng tự động của dự án chưa xử lý được. Còn nếu công cụ đã lo, đưa vào skill là thừa và tạo ra nguồn mâu thuẫn thứ hai.
Bộ lọc đơn giản cho mọi thứ định đưa vào kho chung:
- Nếu làm sai gây hậu quả cho hệ thống hoặc cho khách hàng, đưa vào kho chung.
- Nếu chỉ là sở thích trình bày và đã có công cụ tự động lo, đừng đưa vào.
- Nếu là cách bạn thích làm việc mà người khác làm kiểu khác vẫn ra kết quả đúng, để trong thư mục cá nhân.
Bộ lọc này giữ kho chung nhỏ và có trọng lượng. Kho chung càng phình, người ta càng ít đọc, và tới một lúc thì nó tồn tại chỉ trên danh nghĩa.
Bảo trì kho theo thời gian
Ba việc định kỳ, làm hằng quý là đủ:
Xóa skill đã lỗi thời. Quy trình cũ không còn dùng thì skill mô tả nó là thông tin sai, và thông tin sai còn hại hơn không có gì. Đừng ngại xóa, Git vẫn giữ lịch sử.
Gộp skill trùng lặp. Hai skill cùng nói về một việc thì giữ cái tốt hơn, chuyển phần hay của cái kia sang, rồi xóa.
Kiểm tra phần cấm còn đúng không. Hệ thống đổi thì vùng nguy hiểm cũng đổi. Skill viết từ thời còn dùng máy chủ cũ có thể đang cấm nhầm chỗ và bỏ sót chỗ mới.
Về bảo mật, một dòng nhắc lại vì nó quan trọng: không bao giờ đặt mật khẩu, khóa API hay chuỗi kết nối trong skill. Skill nằm trong Git, được sao chép và chia sẻ, nên mọi thứ bí mật để trong đó xem như đã lộ. Ghi tên biến môi trường, còn giá trị thật để ở nơi quản lý bí mật.
Bảng phân định kho chung và kho riêng
| Loại | Đặt ở đâu | Ví dụ |
|---|---|---|
| Quy trình chuẩn của công ty | Kho chung, có duyệt thay đổi | Quy trình đưa mã lên môi trường thật, quy ước đặt tên |
| Kiến thức về một dự án cụ thể | Trong chính kho mã của dự án đó | Cấu trúc dự án, các quyết định kiến trúc |
| Thói quen cá nhân | Máy cá nhân, không đưa vào kho chung | Cách bạn thích trình bày kết quả |
| Thứ chứa thông tin nhạy cảm | Không đưa vào kho nào | Khóa, mật khẩu, dữ liệu khách hàng |
Nguyên tắc phân loại: nếu người khác trong đội cần biết để làm đúng thì đưa vào kho chung; nếu chỉ mình bạn cần thì để ở máy mình. Trộn hai loại là làm kho chung phình lên và loãng.
Duyệt thay đổi như duyệt mã
- Kho chung nằm trong hệ thống quản lý mã nguồn, mọi thay đổi qua yêu cầu ghép nhánh.
- Ít nhất một người khác đọc trước khi ghép. Một quy trình sai được đưa vào kho chung sẽ lan ra cả đội.
- Ghi lý do thay đổi, vì sáu tháng sau không ai nhớ vì sao có luật đó.
- Đừng để một người tự sửa kho chung mà không ai biết.
Ba việc rà soát mỗi quý
# Ba viec dinh ky, moi quy mot lan: # 1. Ra soat: cai nao khong con dung, cai nao da loi thoi# Xoa manh dan hon them, kho cang lon cang it duoc dung # 2. Kiem trung lap: hai skill cung mo ta mot viec# Tro ly se chon ngau nhien, gay ket qua khong nhat quan # 3. Quet xem co lo thong tin nhay cam khonggrep -rn "password\|api_key\|secret\|token" ./kho-skill/ | grep -v "^Binary" # Quy uoc dat ten: dung mot kieu duy nhat, vi du chu thuong noi bang gach ngang# Ten lech nhau lam viec tim kiem kho honBa việc làm ngay khi lập kho chung
- Viết một tệp mô tả cách dùng kho ngay ở thư mục gốc: kho này chứa gì, ai được thêm, quy trình duyệt thế nào.
- Đặt quy ước đặt tên và mô tả trước khi có mục thứ hai.
- Cấm ghi thông tin nhạy cảm, ghi rõ vào tệp mô tả, và đặt một bước quét tự động trước khi ghép nhánh.
Câu hỏi thường gặp
Nên bắt đầu với bao nhiêu skill chung?
Ba tới năm cái, đúng những quy trình mà người mới vào đội hay làm sai. Viết thêm khi thấy mình lại đang giải thích lại một việc đã giải thích rồi. Đừng ngồi soạn trước hai chục skill cho những tình huống chưa gặp.
Làm sao biết skill có được dùng không?
Cách thực dụng nhất là hỏi lại chính đội mình sau vài tuần, và quan sát kết quả công việc có đều tay hơn không. Nếu một skill viết đã lâu mà không ai nhớ tới, nhiều khả năng mô tả của nó không khớp tình huống thật.
Skill có nên đi kèm bản ghi thay đổi không?
Với skill quan trọng thì nên, chỉ cần vài dòng ở cuối file ghi lần sửa lớn gần nhất và lý do. Phần còn lại đã nằm trong lịch sử Git, không cần chép lại.
Đội dùng nhiều công cụ AI khác nhau thì sao?
Nội dung skill là văn bản mô tả quy trình nên mang sang công cụ khác được, chỉ khác chỗ đặt thư mục và cách khai báo. Hãy viết phần thân theo hướng độc lập công cụ, tránh phụ thuộc vào lệnh riêng của một sản phẩm.