Tóm tắt nhanh:
ak-docsgiữ docs vàCLAUDE.md/AGENTS.mdcủa dự án đúng, gọn, có bằng chứng. Bạn chọn việc bằng lệnh con, thường gọi nó sau khiak-cookhoặcak-fixxong một thay đổi chạm tới docs. Nó không viết code sản phẩm, và không có gì mới thì không ghi gì.
Công khai: mình là maintainer của AgentKit và có quan hệ affiliate: link AgentKit trong bài là link affiliate, mua qua link này bạn được giảm 30%.
Tóm tắt
Dùng khi dự án chưa có docs, code vừa đổi cách dùng, cấu hình hoặc kiến trúc, CLAUDE.md phình to mà agent vẫn làm sai, agent hay lặp một kiểu lỗi, bạn muốn chốt nguyên tắc sản phẩm, hoặc trang docs cần llms.txt. Không cần khi bạn chỉ đổi tên một biến nội bộ hay sửa chỗ không ảnh hưởng tới cách dùng: chạy update lúc đó cũng sẽ không ghi gì.
flowchart LR
A["Bạn gọi thẳng"] --> B["ak-docs"]
C["ak-cook hoặc ak-fix xong, có đổi chạm tới docs"] --> B
B --> D["docs gọn, trỏ về code"]
B --> E["CLAUDE.md hoặc AGENTS.md"]
B --> F["llms.txt và llms-full.txt"]
B --> G["Không có gì mới: không ghi gì"]Nó làm theo 4 nguyên tắc:
| Nguyên tắc | Câu hỏi | Ví dụ |
|---|---|---|
| Docs chỉ giữ vì sao và ở đâu | Câu này có nên nằm trong docs không? | "Chọn Postgres vì cần transaction qua nhiều bảng" được giữ. "Hàm createUser nhận email và mật khẩu" bị cắt, thay bằng một dòng trỏ tới file code. Khi thiết kế có biến thể thật, ví dụ hai cổng thanh toán dùng chung một interface, docs ghi điều cả hai phải giữ mà code không nói được, vì sao chỗ tách nằm ở interface đó, phương án đã loại, cái giá đã chấp nhận, rồi trỏ phần còn lại về interface. Cổng thứ ba chưa ai cam kết thì cùng lắm là một câu hỏi mở, không thành lộ trình. |
| File ngữ cảnh agent là luật hành xử | Thiếu dòng này thì agent sẽ làm sai việc gì cụ thể? | "Dùng pnpm, không dùng npm" được giữ. "Đây là app quản lý kho" bị cắt, vì agent tự đọc repo là biết. |
| Không đổi gì cũng là kết quả đúng | Lần này có điều gì mới, lâu dài, cần ghi không? | Bạn chỉ đổi tên một biến nội bộ. update không sửa file nào, không đổi ngày tháng, không xếp lại mục để tỏ ra đã chạy. |
| Sửa thường lệ và sửa cần duyệt | Nó tự ghi hay hỏi bạn trước? | Một lệnh trong docs trỏ sai đường dẫn: nó tự sửa. Thay đoạn văn bạn tự viết, đổi điều bạn từng sửa, hoặc nới quyền truy cập: nó đề xuất trước. Giá trị secret thì không bao giờ được ghi, ai duyệt cũng vậy. |
Bảy lệnh con là init, update, summarize, agent-context, agents, philosophy và llms; riêng agents và philosophy luôn chờ bạn duyệt diff. Khi ghi đường lấy credential, docs chỉ ghi theo kho secret bạn đã chọn, không mở file .env và không bao giờ ghi giá trị secret.
Prompt mẫu khi code vừa đổi:
/ak-docs update Phần thanh toán của <tên app> vừa chuyển từ webhook sang polling.
Cập nhật docs bị ảnh hưởng.
Ràng buộc: không đụng docs không liên quan.
--advice| Cờ | Để làm gì | Từ ak |
|---|---|---|
--advice | Model mạnh hơn góp ý nên giữ, cắt, sắp lại gì trước khi ghi | 2.7.0 |
--audit | Bạn tự quyết từng thay đổi, mỗi câu hỏi một quyết định | 2.7.0 |
--dry-run | Chỉ với agents: xem tín hiệu đã xếp hạng, chưa đề xuất quy tắc | 2.13.0 |
--source | Chỉ với agents: tìm thêm dấu hiệu ngay trong code | 2.13.0 |
--preset classic | Chỉ với init: dùng bộ 7 tên file docs cố định | 2.16.0 |
Phần dưới đây là bản chi tiết: luồng chạy, 6 tình huống kèm prompt, giải thích từng cờ (dùng khi, không cần khi, nhận lại gì, đi kèm cờ nào), lịch sử thay đổi theo bản ak và các lỗi hay vấp. Bản chi tiết và trang trực quan dành cho subscriber. Agent của bạn cũng tìm được trong đó qua MCP của portal.
Mở khi tài khoản có quyền subscriber
Bài này dành cho subscriber
Khi tài khoản có quyền, toàn bộ bài, bản visual tương tác và lệnh gọi từ agent đều mở.
- Đăng nhập hoặc tạo tài khoản modernEngineerQuyền đọc gắn với email tài khoản.
- Chọn gói trên trang Bảng giáGói 1, 3 hoặc 12 tháng, trả bằng chuyển khoản VietQR. Quyền đọc mở khoảng một phút sau khi tiền về.
- Hoặc nhập mã Facebook subscriberNgười ủng hộ trang qua Facebook nhận mã kích hoạt qua tin nhắn mỗi tháng.
Đã là subscriber? Đăng nhập để đọc.
Dùng bài này trong agent của bạn
Lấy API keyChép đoạn dưới, dán vào Claude Code, Codex hay agent bạn đang dùng. Agent đọc bài rồi đối chiếu với repo đang mở.
Đọc bài "ak-docs: giữ docs và file ngữ cảnh agent đúng, gọn" trên modernEngineer rồi áp dụng vào repo này.
1. Gọi tool content_get của MCP server modernengineer với locale "vi", slug "ak-docs". Nếu chưa nối MCP server modernengineer, dừng lại và hướng dẫn tôi nối theo https://modernengineer.dev/vi/mcp.
2. Tóm tắt các bước chính của bài, chỉ ra bước nào áp dụng được cho repo này.
3. Đề xuất thay đổi cụ thể và hỏi tôi trước khi sửa file.Nối MCP cho Claude Code (một lần)
claude mcp add --transport http modernengineer \
https://api.modernengineer.dev/mcp \
--header "Authorization: Bearer <API key>"Đọc trọn bài qua MCP cần API key của tài khoản subscriber hoặc đã mua guide này. Không có quyền, agent sẽ chỉ đọc được phần mở đầu.
- Phiên bản
- v1.0.0
- Cập nhật
- 22/10/2026
- Giấy phép
- Bảo lưu mọi quyền
- Slug
- ak-docs
