File hướng dẫn dành cho AI agent trong repository tôi đang làm ghi rằng kiến trúc đã duyệt có mười một service. File quy ước mà nó trỏ tới thì ghi mười ba. Không ai sai vào ngày viết câu của mình cả. Con số đó đúng ở thời điểm có người chép nó sang file hướng dẫn. Sau đó file quy ước được cập nhật, còn bản chép thì không.
Toàn bộ chuyện viết hướng dẫn cho coding agent gói gọn trong một câu: bản sao là một nhánh rẽ không bao giờ được merge lại. Mỗi lần dán một rule sang file thứ hai, bạn tạo ra phiên bản thứ hai, và nó sẽ lặng lẽ lệch khỏi bản gốc ngay lần đầu có người chỉ sửa một bên. Với con người, bản cũ nằm im trong wiki chẳng ai đọc. Với agent thì khác: bản cũ được nạp thẳng vào context của model và được làm theo.
Bài này là cách tôi tổ chức để nhiều agent cùng làm theo một bộ luật (Claude Code, Codex, OpenCode, thỉnh thoảng có thêm Gemini CLI): file đầu vào thật mỏng, một thư mục rule có chủ sở hữu rõ ràng và thứ tự ưu tiên, skill cho các quy trình, nhãn bằng chứng, một script kiểm tra nhỏ, và hook cho những rule bắt buộc phải giữ. Đây là thói quen thứ hai trong series. Thói quen đầu tiên là để Git nằm trong tay người.
Vì sao hướng dẫn cho AI agent cứ lệch dần?
Bắt đầu từ việc mỗi tool thực sự đọc gì. Coding agent nào khi mở phiên cũng đi tìm một file có tên cố định, và mỗi tool tìm một tên khác nhau:
| Tool | Mặc định đọc | Chi tiết cần để ý |
|---|---|---|
| Claude Code | CLAUDE.md |
Chỉ đọc AGENTS.md khi không có CLAUDE.md |
| Codex | AGENTS.md |
Từ gốc repo xuống thư mục làm việc, giới hạn mặc định 32 KiB |
| OpenCode | AGENTS.md |
Không có thì quay sang CLAUDE.md |
| Gemini CLI | GEMINI.md |
Tên file cấu hình được |
Tôi đối chiếu bảng này với tài liệu của từng tool vào tháng 10/2026. Mấy chi tiết này đổi theo từng bản phát hành, nên trước khi dựa vào thì kiểm tra lại.
Vậy một repository có nhiều tool cùng làm sẽ có ít nhất hai file đầu vào. Phản xạ tự nhiên là làm cho file nào cũng đầy đủ: dán coding standard vào CLAUDE.md, dán lại vào AGENTS.md, có khi thêm lần thứ ba cho Gemini. Agent nào cũng thấy hết. Ngày đầu, mọi thứ chạy ngon lành.
Đến ngày thứ ba mươi, có người siết lại một rule, chẳng hạn tài liệu API phải nằm ở đâu, và sửa đúng cái file của tool mình hay dùng. Các bản còn lại vẫn nói điều cũ. Agent đọc bản cũ không hề cãi lệnh. Nó làm theo hướng dẫn một cách hoàn hảo. Không có lỗi, không có cảnh báo, không có merge conflict, vì nhánh rẽ đã xảy ra mà chẳng có cơ chế nào gộp nó lại.
Hãy hình dung tấm bảng chỉ dẫn ở sảnh một tòa văn phòng. Bảng tốt chỉ ghi Kế toán, tầng 4. Nó không liệt kê số máy lẻ, giờ làm việc hay lịch nghỉ lễ của phòng Kế toán, vì hôm nào phòng Kế toán đổi giờ là bảng sai ngay, mà trên tầng 4 chẳng ai nhớ dưới sảnh có tấm bảng đó. Việc duy nhất của tấm bảng là chỉ đường. File đầu vào cho agent cũng nên là một tấm bảng ở sảnh như vậy.
CLAUDE.md và AGENTS.md nên chứa gì?
Trong repository, CLAUDE.md dài 22 dòng. Nó mở đầu bằng việc nêu tên hai file sở hữu bộ rule, rồi nói thẳng rằng nó cố tình ngắn để không thể lệch khỏi hai file đó. Phần còn lại là vài dòng thỏa thuận làm việc về cách Claude Code nên hành xử, dòng nào cũng truy được về file chủ. Khung của nó trông như sau (đã đổi tên và lược bớt):
# CLAUDE.md
Project rules live in [docs/rules/README.md](docs/rules/README.md) and
[docs/rules/code-standards.md](docs/rules/code-standards.md). This file
stays short so it cannot drift from them.
## Working agreement
- Do not stage, commit, push, rebase or switch branches; a human owns Git.
- Work only in the requested scope and preserve unrelated changes.
- Public client contracts are REST/JSON; gRPC and Kafka stay internal.
- Canonical docs live in `docs/`, never inside the submodules.
## Before you report completion
Verify against the evidence level the rules define and state gaps explicitly.AGENTS.md, file mà Codex và OpenCode đọc, dài 120 dòng. Nó có cùng các con trỏ, cộng thêm bản đồ repository, lệnh làm việc với submodule, bảng commit nào đi vào đâu, các lệnh hay dùng và một danh sách rule cứng. Một phần trong đó đáng nằm ở đây: bản đồ repository là chỉ đường, mà chỉ đường đúng là việc của tấm bảng. Nhưng có hai thứ cho thấy chính xác drift lọt vào bằng cửa nào:
- Nó lặp lại cảnh báo detached HEAD và các lệnh submodule mà file Git workflow đã sở hữu.
- Nó chứa một dữ kiện, cụ thể là số lượng service, thay vì một đường link tới nơi thật sự quản lý con số đó. Chính câu đó đã cũ.
Bài học tôi rút ra: file đầu vào được phép chứa chỉ dẫn và hành vi riêng của từng tool. Nó không được chứa dữ kiện hay rule mà file khác đang sở hữu. Link có thể gãy, nhưng script tìm ra link gãy được. Còn một dữ kiện đã cũ thì trông y hệt dữ kiện mới.
Nên link tới rule hay import thẳng vào?
Chỉ đường bằng link cũng có cái giá của nó. Link Markdown chỉ là lời gợi ý, agent phải tự quyết định có mở nó ra hay không. Claude Code còn hỗ trợ import kiểu @path/to/file bên trong CLAUDE.md, nội dung file được bung vào context ngay lúc khởi động. Import đảm bảo nội dung chắc chắn được nhìn thấy, nhưng phiên nào bạn cũng phải trả giá cho nó, dù task có cần hay không.
Kinh nghiệm của tôi: import vài dòng mà task nào cũng cần (thỏa thuận làm việc, thứ tự ưu tiên), còn lại thì link. Nếu thấy mình đang import một file Git workflow 650 dòng vào mọi phiên, nhiều khả năng nó nên là skill chứ không phải rule. Phần dưới sẽ nói kỹ hơn.
Thêm một chi tiết: khi repository có cả hai file, Claude Code đọc CLAUDE.md và mặc định bỏ qua AGENTS.md. Nếu CLAUDE.md của bạn không import cũng không link tới file chủ dùng chung, Claude đang làm theo một bộ luật khác với mọi agent còn lại. Hai tấm bảng ở hai cửa vào thì không sao. Hai tấm bảng chỉ người ta lên hai tầng khác nhau mới là vấn đề.
Hai file mâu thuẫn thì nghe file nào?
Trỏ về một chỗ chỉ có ích khi chỗ đó phân xử được mâu thuẫn. File index của bộ rule trong repository làm hai việc ngay phần đầu.
Thứ nhất, mỗi nhóm rule có đúng một file chủ:
| Nhóm rule | File chủ |
|---|---|
| Phạm vi, bằng chứng, ngôn ngữ, chất lượng tài liệu | rules/README.md |
| Cấu trúc code, đặt tên, quy ước framework | code-standards.md |
| Branch, commit, merge request, submodule | git-workflow.md |
| AI tool, quy trình bằng chứng, kiểm tra hoàn thành | ai-tooling.md |
| Sơ đồ | diagram-policy.md |
| Bất biến về giao tiếp, định danh, dữ liệu, bảo mật | system-conventions.md |
Câu quan trọng nằm ngay dưới bảng: không tạo trang policy thứ hai cho bất kỳ nhóm nào ở trên. Muốn thêm chi tiết thì thêm vào file chủ, hoặc link tới nó.
Thứ hai, nó ghi rõ thứ tự ưu tiên khi có mâu thuẫn:
- Quyết định rõ ràng mới nhất của con người.
- Yêu cầu nghiệp vụ.
- Kiến trúc mục tiêu và các quyết định công nghệ đã được duyệt.
- Source, test, manifest và lockfile hiện tại, với vai trò bằng chứng triển khai.
- Tài liệu cũ, chỉ khi không có gì mới hơn nói ngược lại.
Lúc đầu tôi hơi bất ngờ khi source code đứng dưới quyết định kiến trúc. Lý do là danh sách này trả lời câu hỏi "hệ thống nên làm gì?". Khi code nói khác quyết định đã duyệt, agent không được lặng lẽ sửa bên này cho khớp bên kia. Nó phải ghi nhận một alignment gap và nói ra. Từ đó dẫn tới câu hỏi thứ hai mà agent nào cũng phải trả lời. Không phải "tài liệu nào thắng?" mà là "mình chắc đến mức nào?"
Agent nói mức độ chắc chắn của mình thế nào?
Cũng file index đó định nghĩa đúng một nhãn bằng chứng cho mỗi khẳng định: Released, Verified implementation, Prototype observation, Architecture decision, Planned, Alignment gap hoặc Unknown. Agent viết "service có validate token" thì phải nói kèm nó thuộc nhãn nào. Nó đã đọc controller, đã chạy một test có phạm vi rõ, hay chỉ đọc ADR?
Nhãn đáng có mặt trong một bài về rule vì nó biến rule mơ hồ thành rule kiểm tra được. "Đừng khẳng định điều chưa kiểm chứng" là lời khuyên. "Mỗi khẳng định mang một trong bảy nhãn, và Released đòi bằng chứng từ controller, runtime contract, kết quả kiểm thử và bản phát hành" là thứ mà reviewer, hay một agent khác, soát được từng dòng. Bộ nhãn và các bậc bằng chứng được nói kỹ trong bài kiểm chứng code do AI agent viết.
Nên viết thành rule hay thành skill?
Rule được nạp ở mọi task, nên mỗi dòng trong rule đều tốn context và tốn sự chú ý. Có hướng dẫn cần ở mọi lần, có cái một tháng mới cần một lần. Trộn hai loại vào nhau làm file rule dài ra, mà file hướng dẫn càng dài thì càng bị làm theo kém. Chính tài liệu của Claude Code cũng khuyên giữ mỗi CLAUDE.md dưới khoảng 200 dòng vì lý do này.
Skill là cái hộp còn lại: một thư mục có SKILL.md, phần frontmatter chứa name và description, kèm file tham khảo và script nếu cần. Agent thấy description ngay từ đầu, và chỉ nạp phần thân khi task khớp với nó.
Phép thử tôi hay dùng:
| Câu hỏi | Rule | Skill |
|---|---|---|
| Khi nào áp dụng? | Mọi task | Một số task |
| Hình dạng? | Ràng buộc: không bao giờ, luôn luôn | Quy trình: các bước |
| Agent bỏ sót thì sao? | Gây hại | Chậm hơn hoặc thiếu nhất quán |
Lấy một dòng thật trong thỏa thuận làm việc của repository: khi phát hành một thay đổi API, phải cập nhật cùng lúc source, OpenAPI sinh ra lúc runtime, tài liệu API công khai, Postman collection và sequence diagram tương ứng. Ràng buộc đó là rule. Nó áp dụng cho mọi task chạm vào endpoint công khai, và quên nó là phát hành tài liệu sai. Nhưng cách sinh lại OpenAPI, script dựng Postman nằm ở đâu, kiểm tra JSON ra sao, đó là quy trình, và quy trình thì thuộc về skill:
---
name: release-api-change
description: Use when a public REST endpoint is added, changed or removed.
Updates generated OpenAPI, the public API page, the Postman collection
and the sequence diagram together, then validates the Postman JSON.
---
# Release an API change
1. Confirm the controller route and DTOs in source.
2. Regenerate the runtime OpenAPI document.
3. Update the public API page for the endpoint.
4. Rebuild the Postman collection and parse it as JSON.
5. Update the matching sequence diagram.
Policy and evidence rules: [AI tooling](../../../docs/rules/ai-tooling.md)Rule nói điều gì phải đúng. Skill nói làm thế nào để nó đúng, và skill link ngược về file chủ chứ không chép lại.
Viết description thế nào để skill được kích hoạt đúng lúc?
Description là phần duy nhất của skill mà agent nhìn thấy trước khi quyết định có dùng nó hay không. Nó không phải đoạn tóm tắt cho người đọc, nó là công tắc kích hoạt. Mở đầu bằng "Use when…", mô tả tình huống bằng đúng những từ người ta sẽ dùng khi nhờ ("public REST endpoint", "Postman"), và nói rõ skill tạo ra cái gì. Description kiểu "API helper" thì hoặc chẳng bao giờ được gọi, hoặc bị gọi cho mọi thứ.
Skill giữ context window gọn bằng cách nào?
Đây là progressive disclosure, và các con số trong repository làm nó cụ thể hơn. Repository có 46 skill cài dưới .agents/skills, tất cả đến từ một framework workflow mã nguồn mở. Tổng cộng khoảng 1,6 MB trên 234 file, riêng phần thân các SKILL.md đã gần 6.900 dòng. Còn description, phần duy nhất luôn hiển thị, cộng lại chưa tới 8 KB.
Nghĩa là mỗi phiên agent chỉ trả chưa tới 8 KB để biết có 46 quy trình tồn tại, và chỉ trả cho phần thân khi thật sự dùng một skill. Bên trong một skill lớn, mẹo này lặp lại: phần thân chỉ trỏ tới từng file bước một, tới bước hai thì agent mới nạp bước hai.
Rule cũng được chia ba lớp y như vậy. File đầu vào luôn nằm trong context, file index được đọc khi liên quan, còn file chủ như Git workflow chỉ được mở khi task đụng tới Git. Claude Code có thêm một lớp ở giữa: path-scoped rule trong .claude/rules/, chỉ nạp khi agent làm việc với file khớp đường dẫn. Thứ nhỏ thì trả giá ở mọi task, thứ lớn chỉ trả khi dùng tới.
Skill chỉ để trỏ đường có được không?
Được, và thường đó là loại skill tốt nhất. Skill cho Gemini CLI trong repository chỉ có một đoạn văn, tồn tại duy nhất để đưa agent tới file Git workflow chuẩn. Một skill nói "việc Git thì đọc file này" chính là tấm bảng ở sảnh, chỉ hiện ra đúng lúc có người hỏi về Git. Nó tốn một dòng description và không chép lại thứ gì.
Mỗi tool một thư mục skill riêng à?
Đúng vậy, và chuyện drift quay lại ngay. Codex quét .agents/skills. OpenCode tìm trong .opencode/skills, .claude/skills và .agents/skills. Tài liệu của Claude Code ghi .claude/skills. Để skill ở một thư mục thì tool tìm chỗ khác sẽ không thấy, và cũng không báo lỗi gì. Nếu hai tool cần cùng một skill, giữ một bản gốc, link hoặc sinh ra vị trí thứ hai, rồi mở danh sách skill của từng tool để chắc chắn nó thật sự được nạp.
Làm sao biết bộ luật vẫn còn đúng?
Rule về rule ("giữ file đầu vào mỏng", "không chép trùng") cũng cũ đi như mọi đoạn văn khác. Trong repository, chúng nằm trong một checklist hoàn thành mà agent được yêu cầu đọc, và không có gì thực thi nó. Một bước kiểm tra chạy được thì tốt hơn. Đây là một script nhỏ bằng Node, không cần dependency, chạy từ thư mục gốc repository:
// scripts/check-agent-docs.mjs
// Fails when an entry file outgrows its budget, links to a missing file,
// or a skill's frontmatter does not match its folder.
import { existsSync, readFileSync, readdirSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
const ENTRY_FILES = ["AGENTS.md", "CLAUDE.md"];
const MAX_ENTRY_LINES = 60;
const SKILL_ROOTS = [".agents/skills", ".claude/skills"];
const MARKDOWN_LINK = /\[[^\]]*\]\(([^)#\s]+)[^)]*\)/g;
const EXTERNAL_URL = /^[a-z][a-z0-9+.-]*:/i;
const problems = [];
for (const file of ENTRY_FILES.filter((path) => existsSync(path))) {
const text = readFileSync(file, "utf8");
const lineCount = text.trimEnd().split("\n").length;
if (lineCount > MAX_ENTRY_LINES) {
problems.push(`${file}: ${lineCount} lines, budget is ${MAX_ENTRY_LINES}`);
}
for (const [, target] of text.matchAll(MARKDOWN_LINK)) {
if (EXTERNAL_URL.test(target)) continue;
if (!existsSync(resolve(dirname(file), target))) {
problems.push(`${file}: broken link -> ${target}`);
}
}
}
for (const root of SKILL_ROOTS.filter((path) => existsSync(path))) {
for (const folder of readdirSync(root)) {
const skillFile = join(root, folder, "SKILL.md");
if (!existsSync(skillFile)) continue;
const frontmatter = readFileSync(skillFile, "utf8").split("---")[1] ?? "";
const name = frontmatter.match(/^name:\s*['"]?([^'"\n]+)/m)?.[1]?.trim();
if (name !== folder) problems.push(`${skillFile}: name "${name}" != folder`);
if (!/^description:\s*\S/m.test(frontmatter)) {
problems.push(`${skillFile}: missing description`);
}
}
}
if (problems.length > 0) {
console.error(problems.join("\n"));
process.exit(1);
}
console.log("agent docs: ok");Chạy trên repository, nó báo đúng một vấn đề và thoát với mã 1:
$ node scripts/check-agent-docs.mjs
AGENTS.md: 120 lines, budget is 60Mọi link trong các file đầu vào đều trỏ tới file có thật, và cả 46 tên skill đều khớp với tên thư mục. Ngân sách 60 dòng là con số của tôi, không phải chuẩn gì cả. Bạn tự chọn con số của mình, miễn là sai thì nó phải báo to.
Thứ script không bắt được là câu "mười một service" đã cũ. Một dữ kiện sai mà đúng cú pháp thì lọt qua mọi bước kiểm tra cú pháp. Chỉ có rule "file đầu vào không chứa dữ kiện" chặn được nó, và chỉ người review mới thực thi được rule đó. Hãy biết rule nào của mình script kiểm được, rule nào chỉ con người kiểm được.
File rule có chặn được agent làm bậy không?
Không. Mọi thứ nãy giờ đều là chữ cho model đọc, mà chữ thì chỉ khuyên được thôi. Tài liệu của Claude Code nói thẳng điều này: file hướng dẫn được coi là context chứ không phải cấu hình có tính cưỡng chế, và muốn chặn một hành động bất kể model quyết định gì thì dùng hook PreToolUse.
Quay lại sảnh tòa nhà: tấm bảng có thể ghi "không giao hàng qua cửa chính", nhưng người thật sự chặn anh shipper lại là bảo vệ đứng ở cửa xoay.
Bài trước dùng permission deny rule cho nguyên tắc "agent không bao giờ ghi lịch sử Git". Hook là kiểu bảo vệ tổng quát hơn: một script nhìn thấy toàn bộ câu lệnh và áp được bất kỳ logic nào bạn viết ra. Đăng ký nó trong .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-git-writes.sh"
}
]
}
]
}
}Script nhận lời gọi tool sắp chạy dưới dạng JSON qua stdin. Thoát với mã 2 là chặn lời gọi, và những gì script ghi ra stderr sẽ được gửi lại cho agent làm lý do:
#!/usr/bin/env bash
# PreToolUse hook: refuse Git commands that write history or move branches.
command=$(jq -r '.tool_input.command // empty')
pattern='(^|[;&|(][[:space:]]*)git([[:space:]]+-C[[:space:]]+[^[:space:]]+)?[[:space:]]+(add|commit|push|tag|merge|rebase|reset|switch|checkout)([[:space:]]|$)'
if [[ "$command" =~ $pattern ]]; then
echo "Blocked: Git is human-owned here. Leave changes unstaged and report them." >&2
exit 2
fi
exit 0Tôi thử nó với vài câu lệnh. git status, git diff --stat và git log --oneline đi qua. git commit -m x, cd backend && git push, git -C backend checkout main và pnpm test; git add . bị chặn. echo git commit đi qua, đúng như mong muốn.
Nói cho thật: đây là lan can chống sơ suất, không phải ranh giới bảo mật. Regex trên chuỗi lệnh có thể bị lách bằng sh -c, bằng alias, hay bằng một script gọi Git bên trong. Hãy đi kèm những thứ model không thể lý sự để lách qua: môi trường của agent không có credential để push, và branch trên remote được bảo vệ. Các tool khác có đòn bẩy riêng, như sandbox mode, approval policy hay permission rule. Nguyên tắc thì ở đâu cũng vậy: rule bắt buộc phải giữ thì cần một cơ chế, không phải một câu văn.
Cách làm này tốn gì?
- Thêm một bước gián tiếp. Rule nằm sau link chỉ được làm theo nếu agent chịu mở link. Với rule mà task nào cũng cần, hoặc bạn import và trả giá context ở mọi phiên, hoặc chấp nhận có phiên sẽ không đọc tới.
- Một file chủ, sửa một chỗ là ảnh hưởng mọi nơi. Sửa
system-conventions.mdlà đổi hành vi của mọi tool cùng lúc. Đó chính là mục đích, và cũng là lý do file chủ đáng được review kỹ như code. - Description lúc nào cũng bật. Bốn mươi sáu description, mỗi cái khoảng 170 ký tự, thì rẻ. Vài trăm cái, hoặc vài cái na ná nhau, sẽ khiến agent chọn kém đi. Cài cả gói skill hàng loạt cũng làm phạm vi cần review rộng ra: skill có thể kèm script, nên cài gì thì phải đọc kỹ cái đó.
- Mỗi tool một kiểu cấu hình. Tên file khác nhau, thư mục skill khác nhau, quy tắc fallback khác nhau, và tất cả đều thay đổi qua từng bản phát hành. Phải có người kiểm tra lại, và bảng ở đầu bài này rồi cũng sẽ cũ.
Nếu làm lại, tôi sẽ làm khác ở đâu?
- Không để dữ kiện nào trong file đầu vào ngay từ ngày đầu. Vụ drift thật duy nhất tôi tìm thấy đến từ một dữ kiện bị chép vào
AGENTS.md. Nếu là một đường link thì hôm nay nó vẫn đúng. - Viết hook cùng lúc với rule. Trong repository, "agent không bao giờ commit" vẫn chỉ là một câu văn. Ở đó chưa cấu hình hook nào, nên bản thân repository không có gì chặn một agent lờ câu đó đi.
- Chạy script kiểm tra trong CI, thay vì để nó trong checklist rồi mong agent nhớ.
- Tính ngân sách cho
AGENTS.mdnhư với code. Phần lớn 120 dòng là chỉ đường có ích, nhưng đoạn submodule bị lặp nên đổi thành link tới Git workflow, hoặc một skill làm nhiệm vụ điều hướng. - Cài skill có chủ đích. Tôi thà có mười skill viết riêng cho repository này còn hơn một gói 46 skill mà tôi không nói được cái nào từng được gọi.
Tóm tắt
- Rule bị chép là một nhánh rẽ không bao giờ được merge lại, và agent làm theo bản cũ mà không có lỗi nào báo ra.
- File đầu vào như
CLAUDE.mdvàAGENTS.mdlà tấm bảng ở sảnh: chỉ chứa chỉ dẫn và hành vi riêng của tool, không chứa dữ kiện, không chứa rule mà file khác sở hữu. - Mỗi nhóm rule có một file chủ, ghi rõ thứ tự ưu tiên khi mâu thuẫn, và gắn một nhãn bằng chứng cho mỗi khẳng định.
- Rule là ràng buộc cần ở mọi task. Skill là quy trình, chỉ nạp khi description khớp.
- Nhờ progressive disclosure, 46 skill trong repository chỉ chiếm chưa tới 8 KB context luôn bật.
- Thứ gì kiểm được thì viết script. Thứ gì bắt buộc phải giữ thì dùng hook, permission và credential, vì văn bản chỉ khuyên được thôi.
Khi mọi agent đã đọc chung một bộ luật, bạn có thể bắt đầu giao việc qua lại giữa chúng bằng những bản brief tự đứng được.