Tạo Tài Liệu Tự Động

Tài liệu là thứ đầu tiên khách hàng yêu cầu và là thứ cuối cùng kỹ sư viết. Trong outsourcing, khoảng cách này đặc biệt tốn kém: bàn giao bị trì trệ, thành viên team mới mất nhiều ngày reverse-engineer code thay vì deliver tính năng, và khách hàng được bàn giao một hệ thống mà họ không thể tự vận hành. Sun Agent Kit sinh ra tài liệu chất lượng production trực tiếp từ codebase của bạn — tài liệu tham khảo API, hướng dẫn kiến trúc, file README, và gói bàn giao khách hàng có cấu trúc — để delivery của bạn hoàn chỉnh, không chỉ là functional.

Tổng Quan

Mục tiêu: Sinh tài liệu hoàn chỉnh, chính xác, và có thể bảo trì từ source code để bàn giao khách hàng, rotation team, hoặc compliance
Thời gian: 10–30 phút (so với 2–4 giờ viết thủ công)
Agent sử dụng: doc-writer, scout, reviewer
Lệnh: /sk:docs init, /sk:docs update, /sk:docs summarize

Yêu Cầu Trước Khi Bắt Đầu

• Sun Agent Kit đã được cài đặt và xác thực (hướng dẫn cài đặt)
• Source code đã commit vào git (agent đọc repository, không chỉ các file đang mở)
• Để sinh tài liệu API: các file route hoặc controller với pattern nhất quán (Express, FastAPI, Laravel, Spring Boot đều được hỗ trợ)
• Để sinh tài liệu kiến trúc: codebase với ít nhất một layer có thể nhận diện (controller, service, repository, hoặc tương đương)
• Tùy chọn: tài liệu một phần hiện có trong /docs mà agent có thể mở rộng thay vì thay thế

Quy Trình Từng Bước

Bước 1: Sinh tài liệu ban đầu cho dự án

Lần chạy đầu tiên quét toàn bộ codebase và tạo một bộ tài liệu toàn diện.

/sk:docs init

Điều gì xảy ra: Agent thực hiện:

1. Quét cấu trúc dự án để phát hiện framework, database, phương thức auth, và cấu hình deployment
2. Trích xuất bề mặt cấu hình — biến môi trường, npm script, Docker setup
3. Đọc tài liệu một phần hiện có và bảo tồn nó
4. Viết README, API overview, hướng dẫn setup, và tóm tắt kiến trúc vào thư mục docs/

Bước 2: Sinh tài liệu tham khảo API

Trỏ agent vào các route hoặc controller của bạn và nó sinh ra tài liệu API đầy đủ — endpoint, parameter, hình dạng request/response, và error code.

/sk:docs "generate API reference documentation from the route files in src/routes/"

Điều gì xảy ra: Agent thực hiện:

1. Quét file route và khám phá tất cả endpoint cùng HTTP method và path của chúng
2. Trích xuất hình dạng request body từ validation schema (Zod, Joi, v.v.)
3. Suy ra hình dạng response từ câu lệnh return của controller và error handler
4. Viết tài liệu tham khảo API có cấu trúc vào docs/

Bước 3: Sinh tài liệu kiến trúc

Tạo hướng dẫn kiến trúc kỹ thuật giải thích cấu trúc hệ thống — hữu ích cho thành viên team mới và các buổi technical review với khách hàng.

/sk:docs "generate architecture guide — include system overview, layer diagram, data flow, and key design decisions"

Điều gì xảy ra: Agent thực hiện:

1. Phân tích cấu trúc layer của codebase (controller, service, repository, v.v.)
2. Lập bản đồ các tích hợp bên ngoài và xử lý background job
3. Tài liệu hóa các design pattern và quyết định kiến trúc được suy ra
4. Viết hướng dẫn kiến trúc với sơ đồ vào docs/

Bước 4: Cập nhật tài liệu hiện có sau một sprint

Sau khi thêm tính năng hoặc API thay đổi, làm mới tài liệu để khớp với codebase hiện tại mà không cần viết lại mọi thứ.

/sk:docs update

Điều gì xảy ra: Agent thực hiện:

1. Phân tích lại codebase và so sánh với tài liệu hiện có
2. Xác định endpoint mới, interface đã thay đổi, và tính năng đã xóa
3. Cập nhật các file tài liệu bị ảnh hưởng trong khi bảo tồn các phần được viết thủ công
4. Báo cáo những gì đã thay đổi trong lần cập nhật

Bước 5: Sinh gói bàn giao cho khách hàng

Đây là deliverable đánh dấu kết thúc chính thức của một dự án — mọi thứ khách hàng cần để vận hành, bảo trì, và mở rộng hệ thống một cách độc lập.

/sk:docs "generate complete handoff documentation — include system overview, operations guide, runbook, and known issues"

Điều gì xảy ra: Agent thực hiện:

1. Thu thập tất cả tài liệu hiện có và xác định các khoảng trống
2. Tạo operations runbook (deploy, rollback, thiết lập môi trường, health check)
3. Tài liệu hóa các vấn đề đã biết từ GitHub issue hoặc comment TODO trong code
4. Lắp ráp mọi thứ thành gói bàn giao có chỉ mục trong docs/

Ví Dụ Hoàn Chỉnh: Sinh Tài Liệu Bàn Giao Cho Khách Hàng Nhật Bản

Tình huống

Team của bạn đã hoàn thành một dự án sáu tháng xây dựng nền tảng B2B SaaS cho một công ty logistics Nhật Bản. Ngày bàn giao là thứ Sáu. Team nội bộ của khách hàng (hai kỹ sư, không ai trong số đó tham gia vào quá trình xây dựng) sẽ tiếp quản vận hành từ thứ Hai. PM của khách hàng đã gửi danh sách yêu cầu: tổng quan hệ thống, tài liệu API, hướng dẫn thiết lập môi trường, quy trình deployment, và runbook cho các tác vụ vận hành thường gặp. Bạn có ba giờ trước buổi họp bàn giao.

Chuỗi lệnh sử dụng

# 1. Sinh README nếu đã lỗi thời
/sk:docs "Refresh README.md — verify all setup steps are accurate, add Docker deployment section, add troubleshooting for common local setup issues"

# 2. Tài liệu API đầy đủ cho team kỹ thuật của khách hàng
/sk:docs "Generate complete API reference from src/routes/ — all endpoints, authentication requirements, request/response examples, error codes"

# 3. Hướng dẫn kiến trúc — team khách hàng cần hiểu hệ thống
/sk:docs "Generate architecture overview for client handoff — plain language descriptions, focus on how to extend the system"

# 4. Sinh operations runbook
/sk:docs "Generate operations runbook — daily health checks, how to deploy, rollback procedure, database backup verification, monitoring alerts guide"

# 5. Lắp ráp gói bàn giao hoàn chỉnh
/sk:docs "Assemble complete handoff package — include all docs generated today"

# 6. Review về tính đầy đủ và chính xác
/sk:code-review --pending

Kết quả

Hai tiếng rưỡi trước buổi họp bàn giao, bạn có một gói tài liệu toàn diện bao gồm mọi mục trong danh sách yêu cầu của khách hàng. Hướng dẫn kiến trúc dùng ngôn ngữ đơn giản. Operations runbook bao gồm các lệnh CLI chính xác. Tài liệu API có ví dụ cho mỗi endpoint. Các kỹ sư của khách hàng dành buổi họp bàn giao hỏi về business logic và edge case — không hỏi tài liệu ở đâu hay cách deploy ứng dụng.

So Sánh Thời Gian

Bảng Tham Khảo Loại Tài Liệu

Thực Hành Tốt Nhất

1. Chạy /sk:docs update vào cuối mỗi sprint, không chỉ khi bàn giao ✅

Tài liệu được cập nhật liên tục luôn chính xác. Tài liệu được viết một lần và cập nhật vào cuối dự án thường bị cũ 30–40% vào thời điểm tới tay khách hàng. Đồng bộ tài liệu nhanh vào sprint review là không đáng kể; bắt kịp nhiều giờ trước khi bàn giao thì không.

2. Bao gồm gói bàn giao trong Definition of Done của bạn ✅

Thêm “tài liệu bàn giao cập nhật” như một acceptance criterion rõ ràng vào sprint cuối. Khách hàng nhận được gói bàn giao đầy đủ, chính xác đã liên tục có điểm hài lòng cao hơn và ít yêu cầu hỗ trợ sau bàn giao hơn. Biến nó thành tiêu chuẩn delivery, không phải tùy chọn.

3. Đừng chỉnh sửa tài liệu được agent sinh ra mà không đánh dấu các bổ sung thủ công ❌

Nếu bạn thêm context thủ công vào tài liệu được sinh — quy tắc business cụ thể của khách hàng, quyết định được đưa ra bằng miệng trong một buổi họp — hãy đánh dấu những phần đó bằng comment như <!-- Manual addition -->. Điều này ngăn lệnh /sk:docs update tiếp theo ghi đè lên context mà agent không thể suy ra từ code.

4. Đừng dùng tài liệu như thay thế cho code sạch ❌

Một god-object với giải thích nhiều trang vẫn là god-object. Tài liệu mô tả code làm gì — nó không sửa code khó hiểu. Nếu tài liệu kiến trúc cần nhiều đoạn văn để giải thích tại sao một module hoạt động theo cách đó, hãy cân nhắc liệu /sk:plan "refactor" có phải là khoản đầu tư tốt hơn không.

Xử Lý Sự Cố

Vấn đề: Tài liệu API được sinh nhưng hình dạng response không chính xác

Giải pháp: Agent suy ra hình dạng response từ các câu lệnh return của controller. Nếu controller của bạn trả về object chung hoặc dùng một hàm transformer dùng chung, agent có thể không suy ra được hình dạng đầy đủ. Cung cấp thêm context trong prompt: /sk:docs "generate API reference — include request/response examples using data from test files".

Vấn đề: Tài liệu kiến trúc mô tả kiến trúc đã lên kế hoạch, không phải kiến trúc thực tế

Giải pháp: Điều này xảy ra khi codebase phân kỳ so với cấu trúc layer dự định — ví dụ, khi repository thực hiện HTTP call hoặc controller chạy SQL query. Agent tài liệu hóa những gì tồn tại, nhưng đánh dấu các phân kỳ. Nếu bạn thấy cảnh báo về layer violation, hãy giải quyết các vấn đề cấu trúc bằng một lượt tái cấu trúc trước khi sinh lại tài liệu.

Vấn đề: Gói bàn giao có các khoảng trống cần đầu vào thủ công

Giải pháp: Một số thông tin không thể được suy ra từ code: business context, ràng buộc cụ thể của khách hàng, quyết định bằng miệng, và đường dẫn leo thang on-call. Agent đánh dấu chính xác những gì cần đầu vào con người. Điền vào từng phần placeholder trước khi gửi gói cho khách hàng.

Vấn đề: /sk:docs update viết lại các phần tôi đã tùy chỉnh thủ công

Giải pháp: Đánh dấu các phần được viết thủ công bằng HTML comment để agent bảo tồn chúng khi cập nhật. Thêm ghi chú ở đầu file chỉ ra phần nào được tự động sinh ra và phần nào được duy trì thủ công.

Bước Tiếp Theo

• Đánh Giá Code — Sinh delivery checklist song song với tài liệu bàn giao để có hồ sơ chất lượng hoàn chỉnh
• Kiểm Tra Bảo Mật — Bao gồm báo cáo security audit trong gói bàn giao cho khách hàng có ý thức về compliance
• Tái Cấu Trúc Code Cũ — Cải thiện rõ ràng của code trước khi sinh tài liệu kiến trúc để bàn giao hữu ích hơn

Điểm mấu chốt: Tài liệu được viết vào phút cuối dưới áp lực deadline là tài liệu đầy lỗ hổng — Sun Agent Kit sinh nó liên tục từ bản thân codebase, để bàn giao của bạn chính xác, đầy đủ, và sẵn sàng trước khi khách hàng yêu cầu.