documentation-and-adrs

Tổng quan về skill documentation-and-adrs

Skill documentation-and-adrs làm gì

documentation-and-adrs là skill giúp agent viết tài liệu kỹ thuật xoay quanh quyết định, đặc biệt là Architecture Decision Records (ADR). Giá trị thực sự của nó không phải là “viết thêm tài liệu”, mà là “ghi lại vì sao đội ngũ chọn hướng này, những ràng buộc nào đã tác động, và các phương án nào đã bị loại bỏ.” Vì vậy, skill này đặc biệt hữu ích khi chỉ nhìn vào code sẽ không đủ để giải thích các quyết định bảo trì về sau.

Ai nên dùng và phù hợp với công việc nào

Skill này phù hợp nhất cho kỹ sư, tech lead, kiến trúc sư và các nhóm làm Technical Writing liên quan đến kiến trúc, API, hạ tầng, auth, mô hình dữ liệu hoặc thay đổi tính năng hướng đến người dùng. Hãy dùng documentation-and-adrs khi bạn cần lưu lại bối cảnh có giá trị lâu dài cho các kỹ sư hoặc agent trong tương lai, chứ không chỉ cần một bản giải thích trau chuốt cho công việc trước mắt.

Điểm khác biệt so với một prompt chung chung

Một prompt thông thường có thể tạo ra bản tóm tắt gọn gàng, nhưng documentation-and-adrs skill được thiết kế xoay quanh decision record: bối cảnh, ràng buộc, lựa chọn, đánh đổi và hệ quả. Cách đóng khung này rất quan trọng, vì phần lớn tài liệu yếu thường chỉ mô tả cách triển khai mà bỏ qua phần lý do — thứ mà người bảo trì sau này thực sự cần.

Khi nào không nên cài

Bỏ qua skill này nếu bạn chỉ cần comment nội tuyến trong code, dọn dẹp README nhẹ, hoặc viết tài liệu cho prototype dùng một lần. Nó cũng không phù hợp với những luồng code quá hiển nhiên, nơi phần triển khai đã tự truyền đạt rõ ý đồ và không có lịch sử quyết định đáng để lưu lại.

Cách dùng skill documentation-and-adrs

Bối cảnh cài đặt và nên đọc gì trước

Khi documentation-and-adrs install, hãy thêm skill từ repository addyosmani/agent-skills, sau đó đọc skills/documentation-and-adrs/SKILL.md trước tiên. Skill này được đóng gói dưới dạng một file hướng dẫn duy nhất, nên sẽ không có script hỗ trợ hay file tham chiếu để dựa vào. Điều đó cũng có nghĩa là chất lượng đầu vào của bạn quan trọng hơn so với các skill có tool hỗ trợ.

Nếu môi trường của bạn hỗ trợ cài skill, dùng:
npx skills add addyosmani/agent-skills --skill documentation-and-adrs

Sau đó xem:

• skills/documentation-and-adrs/SKILL.md

Skill documentation-and-adrs cần đầu vào gì

Skill này hoạt động tốt nhất khi bạn cung cấp bề mặt quyết định, chứ không chỉ nêu định dạng đầu ra mong muốn. Đầu vào tốt thường bao gồm:

• thay đổi đang được đề xuất
• các hệ thống hoặc API bị ảnh hưởng
• các ràng buộc như hiệu năng, tuân thủ, chi phí, deadline hoặc khả năng tương thích
• các phương án đã được cân nhắc
• hệ quả và rủi ro dự kiến
• đối tượng đọc và vị trí đặt tài liệu, ví dụ docs/adr/ hoặc docs/architecture/

Đầu vào yếu: “Write an ADR for moving to GraphQL.”

Đầu vào tốt hơn:

• Current state: REST API with versioning pain across mobile clients
• Decision needed: whether to adopt GraphQL for new product surfaces
• Constraints: keep existing REST endpoints for 12 months, small platform team, need field-level client flexibility
• Alternatives: improved REST conventions, tRPC, GraphQL gateway
• Decision owner: platform lead
• Output: ADR with status, context, decision, consequences, and rejected alternatives

Prompt thế nào để dùng documentation-and-adrs hiệu quả hơn

Một prompt tốt cho documentation-and-adrs usage nên yêu cầu cả cấu trúc lẫn chất lượng lập luận. Mẫu ổn định thường là:

1. Nêu rõ quyết định hoặc loại tài liệu cần viết.
2. Cung cấp bối cảnh dự án và các ràng buộc.
3. Liệt kê các phương án đã được cân nhắc.
4. Yêu cầu agent làm rõ các đánh đổi, giả định và hành động tiếp theo.
5. Chỉ định định dạng đích.

Ví dụ prompt:
“Use the documentation-and-adrs skill to draft an ADR for choosing an authentication strategy for our B2B SaaS. Compare hosted auth, self-managed OAuth, and passkeys-first. Include context, constraints, decision drivers, rejected options, consequences, migration notes, and open questions. Audience is future backend and security engineers.”

Quy trình đề xuất cho team thực tế

Hãy dùng thứ tự này như một documentation-and-adrs guide thực tế:

1. Thu thập sự kiện từ issue, PR, ghi chú kiến trúc và chat nội bộ.
2. Yêu cầu agent rút ra các yếu tố dẫn dắt quyết định trước khi soạn bản nháp.
3. Rà soát bản nháp đầu tiên để tìm các phương án còn thiếu và những ràng buộc chưa được nói rõ.
4. Chuyển đầu ra thành tài liệu trong repository hoặc ADR với cách đặt tên và vị trí ổn định.
5. Cập nhật lại bản ghi khi quyết định đã được kiểm chứng trong production.

Skill này đặc biệt hữu ích cho Technical Writing khi đi kèm nguồn tư liệu cụ thể. Nó yếu đi rõ rệt nếu bạn yêu cầu nó tự suy ra lý do kinh doanh hoặc lý do kiến trúc trong khi những thông tin đó chưa từng được cung cấp ở đâu.

Câu hỏi thường gặp về skill documentation-and-adrs

documentation-and-adrs có phù hợp cho người mới làm Technical Writing không?

Có, miễn là người mới đó đã có quyền truy cập vào các dữ kiện đứng sau quyết định. Skill này cung cấp cấu trúc hữu ích cho ADR và tài liệu quyết định, nhưng không thay thế được năng lực phán đoán kỹ thuật. Người mới thường có kết quả tốt hơn khi đưa vào ghi chú họp, link issue hoặc một danh sách ưu/nhược điểm sơ bộ, thay vì yêu cầu tạo tài liệu từ con số không.

Nó khác gì so với việc chỉ yêu cầu “write docs”?

Các prompt viết tài liệu chung thường tối ưu cho độ dễ đọc. documentation-and-adrs tối ưu cho khả năng bảo trì của quyết định: vì sao chọn hướng này, đã có những ràng buộc nào, và người đọc trong tương lai cần biết gì trước khi thay đổi nó. Khác biệt này quan trọng nhất với kiến trúc, public API và các lựa chọn về hạ tầng.

Ranh giới của skill này là gì?

Skill này không phải là hệ thống tài liệu toàn repo, không phải style linter, cũng không phải trình tạo tài liệu có tự động hóa. Nó cung cấp hướng dẫn về quy trình và cấu trúc, chứ không cung cấp script hoặc template được tooling ép buộc. Nếu bạn cần đồng bộ tài liệu tự động, kiểm soát tiêu chuẩn hoặc quy trình publish, bạn sẽ cần thêm công cụ khác bao quanh nó.

Khi nào không nên dùng skill documentation-and-adrs?

Đừng dùng skill này cho các chi tiết triển khai quá nhỏ, các refactor hiển nhiên, comment code trùng lặp, hoặc prototype mang tính thử nghiệm không có giá trị lâu dài. Nếu team vẫn chưa đi đến một quyết định thực sự, bạn có thể dùng skill để so sánh các phương án, nhưng đừng giả vờ rằng đã có ADR cuối cùng khi quyết định đó trên thực tế هنوز chưa được chốt.

Cách cải thiện skill documentation-and-adrs

Cung cấp đầu vào ở cấp độ quyết định, không phải cấp độ tóm tắt

Cách nhanh nhất để cải thiện đầu ra của documentation-and-adrs skill là cung cấp bằng chứng đủ để hậu thuẫn cho một quyết định. Hãy đưa vào các phương án bị loại, các ràng buộc và hệ quả dự kiến. Nếu thiếu những phần này, đầu ra sẽ trông trau chuốt nhưng rất chung chung. Nếu có thể, hãy cung cấp trích đoạn từ design doc, mô tả PR, RFC hoặc báo cáo incident review.

Theo dõi các lỗi thường gặp

Các vấn đề phổ biến nhất là:

• lặp lại chi tiết triển khai thay vì ghi lại lý do ra quyết định
• liệt kê các phương án thay thế nhưng không giải thích vì sao chúng bị loại
• bỏ sót rủi ro, chi phí migration hoặc hệ quả vận hành
• viết cho người review hôm nay thay vì người bảo trì trong tương lai

Nếu thấy một trong các dấu hiệu này, hãy yêu cầu chỉnh sửa theo hướng tập trung vào “decision drivers, rejected alternatives, and downstream consequences.”

Lặp lại trên cấu trúc sau bản nháp đầu tiên

Sau lượt đầu tiên, hãy yêu cầu agent siết chặt các phần còn yếu thay vì viết lại toàn bộ. Các câu follow-up tốt gồm:

• “Make the tradeoffs more explicit.”
• “Add assumptions and what would change this decision.”
• “Separate immediate consequences from long-term maintenance impact.”
• “Rewrite for future engineers unfamiliar with this subsystem.”

Điều chỉnh skill theo quy ước của repo

Để documentation-and-adrs for Technical Writing hữu ích hơn, hãy cho agent biết quy ước đặt tên file, format ADR và vị trí lưu tài liệu của bạn. Ví dụ, hãy chỉ rõ bạn dùng ADR đánh số tuần tự như docs/adrs/0007-auth-strategy.md hay tài liệu theo chủ đề trong docs/architecture/. Prompt của bạn càng khớp với quy ước tài liệu của repository, bạn càng phải dọn dẹp ít hơn sau khi tạo nội dung.