Viết tài liệu dự án tự động với Claude Code (hướng dẫn 2026)

Vì sao nên để Claude Code viết tài liệu dự án?

Ai cũng biết docs quan trọng, nhưng thực tế thì tài liệu viết tay gần như luôn lỗi thời. Bạn đổi tên một endpoint, thêm một tham số env, refactor cả module - còn README thì vẫn nằm im từ commit đầu tiên. Viết docs tay tốn công, nhàm, và là thứ đầu tiên bị bỏ khi deadline tới.

Điểm khác biệt của Claude Code là nó đọc được cả repo, không chỉ đoán từ tên file. Nó mở package.json, lần theo entrypoint, đọc route, model, config - nên tài liệu sinh ra bám sát code hiện tại chứ không phải mô tả chung chung. Việc tự động hóa tài liệu vì thế không còn là "viết cho có", mà là dựng một bản mô tả trung thực về hệ thống ngay tại thời điểm này.

Quan trọng hơn: khi đã có quy trình, việc sinh README hay cập nhật API docs mỗi lần code đổi chỉ còn là chạy lại một lệnh. Đó là điểm mà phần lớn hướng dẫn tiếng Việt bỏ qua - họ chỉ dạy prompt one-off, mỗi lần một kiểu. Bài này đi theo hướng ngược lại: dựng một backbone tái sử dụng được.

Chuẩn bị: cần gì trước khi bắt đầu

Trước khi sinh dòng docs đầu tiên, bạn cần vài thứ tối thiểu:

• Claude Code đã cài và đăng nhập. Nếu chưa, xem hướng dẫn cài đặt Claude Code trước rồi quay lại.
• Terminal mở đúng trong thư mục repo. Claude Code làm việc theo thư mục hiện hành - nó chỉ "thấy" những file trong cây thư mục bạn đang đứng.
• Hiểu Claude Code đọc gì để nắm dự án. Với một repo Node, nó nhìn package.json để biết scripts và dependencies; với repo Python là pyproject.toml/requirements.txt; rồi lần theo entrypoint và cấu trúc thư mục. Bạn không cần chỉ tay từng file - nhưng repo càng gọn, cấu trúc càng rõ thì docs sinh ra càng chính xác.

Một mẹo nhỏ: nếu repo có phần nào không nên đưa vào docs (thư mục build, file sinh tự động, code thử nghiệm), hãy nói rõ trong prompt hoặc để agent bỏ qua qua .gitignore. Bạn sẽ đỡ được rất nhiều rác trong output.

Quy trình 6 bước viết tài liệu tự động

Đây là xương sống của bài. Mỗi bước có một mục tiêu rõ ràng và một prompt/lệnh thật bạn có thể dán vào Claude Code ngay. Làm đủ 6 bước một lần, bạn sẽ có một quy trình lặp lại được cho mọi repo về sau.

Bước 1 - Cho Claude Code đọc và hiểu codebase

Mục tiêu: để agent nắm kiến trúc tổng thể trước khi viết bất cứ dòng docs nào.

Đừng bắt Claude Code sinh README ngay lập tức. Cho nó "đọc hiểu" trước, rồi tự tóm tắt lại để bạn kiểm chứng nó có hiểu đúng không:

Đọc toàn bộ codebase này và tóm tắt cho tôi:
1. Đây là loại dự án gì, giải quyết vấn đề gì?
2. Kiến trúc tổng thể: các module/layer chính và vai trò.
3. Entrypoint và luồng dữ liệu chính.
4. Stack, framework, dependency đáng chú ý.
Chỉ dựa trên code thật trong repo, đừng suy đoán.

Nếu bản tóm tắt sai chỗ nào, bạn sửa ngay ở đây - rẻ hơn nhiều so với sửa cả trang docs sau này.

Bước 2 - Viết/chuẩn hóa CLAUDE.md (ngữ cảnh cho agent)

Mục tiêu: tạo file ngữ cảnh để mọi lần sinh docs về sau đều đúng bối cảnh dự án.

CLAUDE.md là file agent tự đọc mỗi phiên: quy ước code, cấu trúc thư mục, lệnh build/test, những "luật nhà" của dự án. Nó vừa là tài liệu ngữ cảnh cho agent, vừa là thứ bạn cần viết chuẩn - vì nó quyết định chất lượng của mọi docs sinh sau đó. Prompt gợi ý:

Tạo file CLAUDE.md cho repo này gồm:
- Tổng quan dự án (2-3 câu).
- Cấu trúc thư mục và ý nghĩa từng phần chính.
- Lệnh thường dùng: cài, chạy dev, test, build.
- Quy ước code và những lưu ý quan trọng khi sửa.
Ngắn gọn, chính xác, chỉ dựa trên repo thật.

Muốn hiểu sâu cách cấu trúc file này cho hiệu quả, xem hướng dẫn viết file CLAUDE.md chuẩn. Đây là bước nhiều người bỏ qua nhất - và cũng là lý do docs của họ mỗi lần một kiểu.

Bước 3 - Sinh README từ codebase

Mục tiêu: tạo README hoàn chỉnh, đúng cách cài-chạy-dùng thật.

Viết file README.md cho dự án này gồm:
tiêu đề + mô tả ngắn, tính năng chính, yêu cầu hệ thống,
hướng dẫn cài đặt, cách chạy (dev/production), cấu hình env,
ví dụ sử dụng cơ bản, và cấu trúc thư mục.
Lấy lệnh và tên biến env đúng như trong code, đừng bịa.

Khác biệt "before/after" thường rất rõ. Trước đó README có thể chỉ là:

# my-api
TODO: viết docs

Sau khi chạy, bạn có một README với mục cài đặt, biến env lấy đúng từ file config, và ví dụ gọi API dựa trên route thật. Điểm cần nhớ: sinh README chỉ tốt bằng độ sạch của codebase - code rõ ràng thì docs rõ ràng.

Bước 4 - Sinh tài liệu chuyên sâu

Mục tiêu: vượt khỏi README - sinh API docs, sơ đồ kiến trúc, hướng dẫn onboarding.

Với API docs, chỉ Claude Code vào đúng thư mục route/controller và yêu cầu bảng endpoint kèm method, tham số, response mẫu. Với kiến trúc, yêu cầu mô tả các layer và cách chúng gọi nhau. Với onboarding, yêu cầu một checklist cho dev mới: cài gì, chạy gì, đọc file nào trước.

Từ thư mục src/routes, sinh tài liệu API dạng bảng:
mỗi endpoint gồm method, path, mô tả, tham số, ví dụ response.
Chỉ liệt kê endpoint có thật trong code.

Bước 5 - Rà soát và sửa (human-in-the-loop)

Mục tiêu: bắt và xóa những chỗ agent "bịa" trước khi commit. Bước này bắt buộc, không được bỏ.

Auto-docs vẫn có thể tạo ra endpoint không tồn tại, mô tả sai tham số, hoặc ví dụ response không khớp thực tế. Hãy đối chiếu từng phần quan trọng với code thật: mở đúng route, kiểm tra tên biến env, chạy thử một lệnh trong hướng dẫn cài đặt. Coi output của agent là bản nháp chất lượng cao - không phải chân lý.

Bước 6 - Giữ tài liệu luôn mới (self-updating)

Mục tiêu: để docs không lỗi thời sau vài sprint.

Đây là phần đối thủ hầu như không đề cập. Vài cách giữ docs tươi:

• Chạy lại quy trình khi code đổi lớn: sau mỗi lần refactor hay thêm feature, cho Claude Code cập nhật đúng phần docs liên quan thay vì viết lại từ đầu.
• Git hook / CI: thêm bước rà soát docs vào pipeline - kết hợp tốt với một quy trình Git với Claude Code gọn gàng.
• Audit docs cũ: định kỳ hỏi agent "phần nào trong docs không còn khớp code hiện tại?" để phát hiện chỗ lệch.

Ví dụ thật: viết docs cho 1 repo mẫu

Để cụ thể, hãy hình dung một repo API nhỏ: một service Express với vài route CRUD, kết nối Postgres, có file .env.example. Sau bước 1, Claude Code tóm tắt đúng rằng đây là REST API 4 endpoint, dùng middleware xác thực JWT, và có một lớp repository tách riêng truy vấn DB.

Ở bước 3, README sinh ra có mục cài đặt lấy đúng npm install + npm run migrate từ scripts trong package.json, và bảng biến env đọc từ .env.example. Ở bước 4, API docs cho ra bảng kiểu:

| Method | Path | Auth | Mô tả |
|--------|---------------|------|----------------------|
| GET | /api/tasks | JWT | Liệt kê task |
| POST | /api/tasks | JWT | Tạo task mới |
| PATCH | /api/tasks/:id| JWT | Cập nhật task |
| DELETE | /api/tasks/:id| JWT | Xóa task |

Chỗ phải sửa tay: agent mô tả một tham số query ?status= cho endpoint list - nhưng khi mở route ra kiểm tra thì tham số đó chưa được xử lý, chỉ có trong một comment TODO. Đây đúng là kiểu ảo giác mà bước 5 phải bắt. Xóa dòng đó, docs mới khớp code thật.

Các loại tài liệu Claude Code viết tốt (và loại nên cẩn thận)

Không phải loại docs nào cũng nên giao trọn cho agent. Bảng dưới giúp bạn đặt kỳ vọng đúng:

Nguyên tắc chung: docs mô tả code như-nó-đang-là thì Claude Code làm rất tốt; docs cần phán đoán ngoài code (pháp lý, số đo, cam kết) thì luôn cần người duyệt.

Giới hạn và lỗi thường gặp khi auto-docs

Trung thực mà nói, auto-docs không phải phép màu. Vài giới hạn thật cần biết:

• Ảo giác endpoint/API không tồn tại. Đây là lỗi phổ biến nhất. Agent có thể suy ra một route "hợp lý" nhưng thực ra chưa được viết. Đó là lý do bước 5 (rà soát tay) là bắt buộc.
• Docs lệch sau refactor. Nếu bạn không chạy lại quy trình sau khi đổi code, tài liệu sẽ nhanh chóng nói dối. Docs tự động chỉ đúng tại thời điểm sinh ra.
• Tốn token với monorepo lớn. Repo càng lớn, agent càng đọc nhiều - vừa tốn chi phí vừa dễ bỏ sót. Với monorepo, nên chạy theo từng package/thư mục thay vì quét cả cây.
• Luôn cần human review. Không có ngoại lệ. Coi output là bản nháp tốt, không phải bản cuối.

Nếu gặp trục trặc khi chạy (agent dừng giữa chừng, output cụt), tham khảo thêm các lỗi Claude Code thường gặp và cách xử lý.

Làm nhanh hơn với skill viết-docs dựng sẵn

Gõ lại 6 prompt trên cho mỗi repo dần dần cũng mệt. Cách gọn hơn là dùng một skill đóng gói sẵn cả quy trình. Nếu chưa rõ khái niệm này, xem skill trong Claude Code là gì.

Một ví dụ là skill ak-docs: phân tích codebase rồi tạo / refresh / tóm tắt / audit tài liệu dự án mà không ép một layout cố định - kể cả viết và tối ưu CLAUDE.md/AGENTS.md. Nói cách khác, nó chính là bản "đóng gói sẵn" của quy trình 6 bước ở trên để bạn lặp lại nhanh. Skill này ship trong AgentKit (giảm 20% qua link) - bộ kit cho Claude Code (CLI ak), lưu ý khác hoàn toàn OpenAI AgentKit. Muốn biết cụ thể Engineer Kit gồm những gì, xem bài Engineer Kit có gì (kèm ak-docs).

Câu hỏi thường gặp (FAQ)

Claude Code viết README được không?

Được, và đây là việc nó làm tốt nhất. Claude Code đọc package.json, entrypoint và cấu trúc thư mục để sinh README có mục cài đặt, cấu hình env và ví dụ sử dụng bám sát code thật. Bạn vẫn nên rà lại lệnh và tên biến env trước khi commit.

Docs có tự cập nhật khi code đổi không?

Không tự động hoàn toàn. Tài liệu chỉ đúng tại thời điểm sinh ra; sau refactor bạn phải chạy lại quy trình. Cách bền vững là thêm bước rà soát docs vào git hook hoặc CI để nhắc cập nhật mỗi khi code thay đổi lớn.

Claude Code có bịa API không (ảo giác)?

Có thể. Agent đôi khi suy ra endpoint hoặc tham số "hợp lý" nhưng chưa tồn tại trong code. Vì vậy bước rà soát tay (human-in-the-loop) là bắt buộc: đối chiếu từng endpoint với route thật trước khi tin.

Viết docs tiếng Việt được không?

Được. Chỉ cần yêu cầu trong prompt "viết bằng tiếng Việt", Claude Code sẽ sinh README và tài liệu kỹ thuật bằng tiếng Việt tự nhiên, trong khi vẫn giữ nguyên tên lệnh, biến và code.

Dùng skill nào cho nhanh?

Nếu muốn lặp lại quy trình mà không gõ prompt mỗi lần, có thể dùng skill ak-docs - tạo, refresh và audit tài liệu (kể cả CLAUDE.md) mà không ép layout cố định. Nó gói sẵn đúng quy trình 6 bước trong bài.

Có cần trả phí không?

Bản thân việc viết docs bằng Claude Code dùng chung gói Claude Code của bạn (ví dụ Pro $20/tháng). Skill dựng sẵn như ak-docs đi kèm Engineer Kit của AgentKit - trang niêm yết $99 và không nêu phí định kỳ. Bạn hoàn toàn có thể làm tay theo 6 bước mà không cần mua gì thêm.

Kết luận + bước tiếp theo

Viết docs bằng Claude Code không phải chuyện "gõ một prompt rồi xong", mà là một quy trình 6 bước lặp lại được: đọc repo, chuẩn hóa CLAUDE.md, sinh README và tài liệu chuyên sâu, rà soát tay để xóa ảo giác, rồi giữ docs luôn mới. Làm đúng backbone này, mỗi repo mới chỉ tốn vài phút thay vì cả buổi chiều. Bước tiếp theo nên làm: đọc kỹ cách viết CLAUDE.md chuẩn vì nó là nền cho mọi lần sinh docs, và tìm hiểu skill trong Claude Code để tự động hóa quy trình. Và đừng quên: luôn verify output trước khi tin.

Nguồn tham khảo tính năng đọc codebase của Claude Code: tài liệu chính thức Claude Code (Anthropic). Mô tả skill ak-docs: trang chủ AgentKit (agentkit.best, cập nhật 08/2026).