Duy trì tri thức project với ak:docs

Dùng ak:docs để thiết lập, cập nhật hoặc tóm tắt tài liệu project trong khi vẫn giữ code và artifact thực thi làm chủ sở hữu hành vi hiện tại. Skill khám phá các bề mặt thẩm quyền thật của repo, giữ lại lý do và ràng buộc bền vững, đồng thời loại bỏ tài liệu chỉ lặp lại chi tiết triển khai.

Chọn ak:docs cho tài liệu project

Dùng ak:docs khi

• Project cần tuyến tài liệu mạch lạc đầu tiên.
• Hành vi hướng người dùng, kiến trúc, cấu hình hoặc hướng dẫn vận hành đã đổi và tài liệu bị ảnh hưởng cần được đối chiếu.
• Bạn cần bản tóm tắt project dựa trên bằng chứng mà không bắt buộc tạo tệp mới.
• Tài liệu hiện có chứa path cũ, hướng dẫn trùng lặp hoặc inventory được sao chép.

Chọn workflow khác khi

• Bạn cần tài liệu hiện tại cho thư viện bên ngoài. Dùng workflow khám phá tài liệu.
• Bạn cần visual được tạo nhưng không đổi tài liệu. Dùng ak:preview.
• Bạn cần sửa product code. Dùng workflow lập kế hoạch hoặc triển khai phù hợp; ak:docs không được triển khai product code.
• Bạn chỉ cần biết Skill nào phù hợp. Dùng ak:help.

Chuẩn bị project và runtime

Trước khi bắt đầu:

• Hoàn tất Làm quen, và xác nhận Engineer Kit đã được cài cho runtime và scope bạn đang dùng.
• Mở project và cung cấp chỉ dẫn repo, README gốc cùng navigation tài liệu hiện có.
• Nêu audience, kết quả, quyết định bị ảnh hưởng, bằng chứng và tiêu chí chấp nhận cho thao tác tài liệu.
• Tách hướng dẫn evergreen khỏi plan, audit, bằng chứng phát hành và record có trạng thái khác.
• Xác định tài liệu được tạo hoặc do máy sở hữu cần thay đổi qua owner thay vì sửa thủ công.

Chạy Skill

/ak:docs update "Reconcile onboarding docs with the current authentication flow. Preserve generated CLI pages, remove duplicated command lists, and verify links."

/ak:docs update "Reconcile onboarding docs with the current authentication flow. Preserve generated CLI pages, remove duplicated command lists, and verify links."

$ak:docs update "Reconcile onboarding docs with the current authentication flow. Preserve generated CLI pages, remove duplicated command lists, and verify links."

Đối số đầu tiên chọn thao tác:

Chọn cấu trúc docs cố định với --preset classic

Theo mặc định, ak:docs init khám phá tuyến tài liệu thật của project: đọc chỉ dẫn repo, README gốc và navigation docs hiện có, sau đó chỉ tạo những tệp xứng đáng có mặt. Project muốn dùng cấu trúc cố định trước đây có thể opt-in rõ ràng:

/ak:docs init --preset classic

--preset classic tạo bảy tệp dưới docs/: project-overview-pdr.md, code-standards.md, codebase-summary.md, design-guidelines.md, deployment-guide.md, system-architecture.md và project-roadmap.md.

Khai báo cùng tuyến này trong CLAUDE.md, AGENTS.md hoặc docs/README.md của chính project đạt kết quả tương tự mà không cần flag, và nó tồn tại cho các lần chạy update, summarize sau — Skill tái sử dụng bất kỳ tuyến nào project đã cam kết.

Preset chỉ chọn tên tệp. Mọi quy tắc nội dung vẫn áp dụng: mỗi tệp trỏ tới code sở hữu hành vi thay vì mô tả lại nó, và tệp không có thông tin thật sẽ bị bỏ qua thay vì lấp đầy bằng placeholder.

Khám phá là mặc định vì tài liệu mô tả lại code trở thành nguồn sự thật thứ hai mà không test nào kiểm tra được — nó lệch dần và gây hiểu sai cho agent — và mỗi tệp được tạo ra đều tốn context ở mọi phiên sau.

Quản lý agent context ở root

Dùng agent-context cho instruction tại repository root; giữ ak:folder-context cho thư mục con.

/ak:docs agent-context --advice
/ak:docs agent-context --audit

Trong Codex, dùng cách viết $ak:docs. --advice hỏi kongming trước khi trình bày thay đổi đề xuất. --audit lấy một audit, sau đó hỏi từng quyết định keep, cut, fix hoặc migrate và chỉ áp dụng thay đổi đã xác nhận. Skill xác minh hành vi runtime hiện tại, loại secret và chỉ khuyến nghị—không sửa—setting cùng cấu hình Hook mang tính deterministic. Bản phát hành này không định nghĩa filename root context cho Cursor.

ak:docs áp dụng một bậc thang write-authority chung cho init, update và agent-context: việc bảo trì thường xuyên, trong phạm vi được tự cấp quyền, và Skill chỉ dừng lại để xác nhận trước khi thay thế prose hiện có, một tài liệu sở hữu, hoặc một chỉnh sửa bạn đã đưa ra trước đó. Điều này bao gồm cả việc tự bảo trì — đối chiếu lại các instruction bị ảnh hưởng sau khi có công việc đã được cấp quyền khác trong project, kể cả khi không có source file nào thay đổi. Khi không có gì bền vững thực sự thay đổi, lần chạy đó là no-op thật sự: không ghi gì.

Với một tuyến vận hành — cách lấy một secret, log source và window nào cần đọc cho một environment, hoặc destination nào được phép cho audience nào — Skill giữ chi tiết lookup trong operational guide riêng của project và chỉ để lại một pointer một dòng tới đó trong agent context ở root. Skill redact output quan sát được trước khi lưu giữ, chuyển giao hoặc publish, và không bao giờ ghi credential value, tokenized URL, account hoặc project ID, hay tên khách hàng vào bất kỳ tệp repo nào, kể cả operational guide và chính tệp agent context.

Dùng agents khi các quy tắc process ở root cần xuất phát từ bằng chứng lặp lại thay vì một audit không giới hạn:

/ak:docs agents 30d --source
/ak:docs agents --dry-run

Dùng cách gọi phù hợp với runtime của bạn. Một lần chạy agents thông thường ngầm bao gồm --advice; không cần thêm flag riêng. Mặc định, thao tác khai thác tối đa 90 ngày hoặc 300 commit, tùy giới hạn nào nhỏ hơn, cùng tối đa 200 lượt chạy CI. Nếu gh chưa được xác thực, thao tác báo đã bỏ qua CI signal và tiếp tục chỉ với bằng chứng Git. --source bổ sung việc khai thác source marker chỉ đọc vào lượt kiểm tra git và CI; --dry-run dừng sau khi xếp hạng signal, không khởi chạy adviser và không ghi gì. Các quy tắc đề xuất vẫn cần bạn xác nhận.

Tạo index tài liệu mà AI có thể đọc

/ak:docs llms

Thao tác llms khám phá thẩm quyền tài liệu của project, sau đó tạo hoặc đối chiếu llms.txt và llms-full.txt trong thư mục public/static của site hoặc, khi không có site được xuất bản, ở repository root. Thao tác giữ index tuyển chọn ngắn gọn, bảo toàn cách tổ chức hiện có còn hợp lệ, xác minh link và báo cáo kích thước tệp full-content.

Xác định contract tài liệu

Trước khi viết, Skill thiết lập:

• Audience: Xác định con người, AI collaborator hoặc cả hai sẽ dùng tuyến này.
• Kết quả: Nêu các quyết định hoặc tác vụ tài liệu phải hỗ trợ.
• Thẩm quyền: Xác định bề mặt repo sở hữu hướng dẫn bền vững.
• Bằng chứng: Nêu source, test, script, manifest, artifact được tạo hoặc live state chứng minh hành vi hiện tại.
• Ranh giới trạng thái: Tách ý định evergreen khỏi plan, report, audit và record phát hành tạm thời.
• Tiêu chí chấp nhận: Xác định path, link, ví dụ hoặc quyết định phải xác minh được sau đó.

Skill tái sử dụng plan đã chấp nhận hoặc contract tài liệu trước đó khi các nội dung này đã được quyết định.

Hiểu những gì diễn ra trong một lần chạy

1. Skill xác nhận contract. Skill chạy một lượt brainstorm tài liệu có giới hạn và chỉ mở lại quyết định quan trọng còn thiếu.
2. Skill khám phá tuyến. Skill đọc chỉ dẫn repo, README gốc, docs index hiện tại, tài liệu được liên kết và bằng chứng liên quan.
3. Skill ánh xạ quyền sở hữu. Skill phân biệt hướng dẫn bền vững về lý do và vị trí với chi tiết có thể thực thi về nội dung và cách làm.
4. Skill chọn thay đổi nhỏ nhất. init thiết kế tuyến tối thiểu; update ánh xạ claim đã đổi tới owner; summarize giới hạn lượt đọc bằng chứng.
5. Skill trình bày thay đổi thẩm quyền quan trọng. Skill đưa ra tuyến đề xuất trước khi thay thế tài liệu hoặc đổi thẩm quyền của chúng.
6. Skill viết hoặc tóm tắt. Skill có thể dùng delegate docs-manager khi khả dụng hoặc tự thực hiện cùng workflow evidence-first.
7. Skill xác minh kết quả. Skill kiểm tra link, path, ví dụ, config key, lệnh và generator hoặc contract script sở hữu nội dung.

Giữ tài liệu an toàn và dễ bảo trì

Các ranh giới quan trọng:

• Tài liệu sở hữu lý do, quyết định, thuật ngữ, ràng buộc và navigation bền vững. Tài liệu nên trỏ tới owner thực thi cho hành vi hiện tại.
• Inventory do máy sở hữu và reference được tạo phải thay đổi qua manifest, generator hoặc source layer của chúng.
• Skill không được tạo bộ ADR, roadmap, generator, bot hoặc CI gate chỉ cho docs trừ khi bạn yêu cầu rõ bề mặt vận hành đó.
• Chỉ thêm sơ đồ khi visual giúp hiểu tốt hơn đáng kể và phải review sau khi tạo.
• Khi tài liệu hoặc root context chứa hướng dẫn test, Skill áp dụng các nguyên tắc test qua cùng gate về bằng chứng riêng cho project và xác nhận thay vì sao chép nguyên khối hướng dẫn chung.
• Workflow trong source không yêu cầu provider bên ngoài, xuất bản, credential hay dịch vụ trả phí.

Xác minh kết quả

Bằng chứng phụ thuộc thao tác đã chọn:

Kết quả đầy đủ cũng liệt kê câu hỏi chưa giải quyết ở cuối. Tài liệu ngắn là hợp lệ khi project có ít lý do bền vững mà code không thể biểu đạt.

Khắc phục sự cố hoặc tiếp tục

Biết giới hạn hiện tại

• Skill không thể phục hồi lý do chưa được ghi lại và không có trong repo hay ngữ cảnh project khả dụng.
• Claim về live state vẫn bị giới hạn bởi tool, credential và bằng chứng có thể truy cập.
• Công việc tài liệu được delegate phụ thuộc khả năng runtime và phải nhận cùng quy tắc ownership và chống drift.
• Cách gọi slash trên Cursor là bằng chứng do người dùng xác minh, không chứng minh tính tương đương về delegation hay tool sơ đồ.