QuotaCheap Playbook

AGENTS.md cho Codex: biến convention repo thành hướng dẫn bền cho coding agent

Hướng dẫn AGENTS.md cho Codex theo tài liệu OpenAI: global, repo, nested overrides, precedence, AGENTS.override.md, review guidelines, test commands, const…

Prompt tốt giúp một task chạy đúng. AGENTS.md giúp nhiều task chạy đúng hơn vì Codex tự đọc repo guidance, test commands, constraints và review rules trước khi làm việc.

Playbook tiếng Việt về AGENTS.md cho Codex theo tài liệu OpenAI: global/repo/nested instructions, AGENTS.override.md, fallback filenames, precedence, project_doc_max_bytes, review guidelines, test commands, constraints, và cách audit instruction loading.

Prompt tốt giúp Codex làm đúng một task.

AGENTS.md giúp Codex làm đúng nhiều task hơn.

Đây là bước chuyển từ “mỗi lần nhắc lại một đống rule” sang “repo tự nói cho agent biết cách làm việc”.

Với team developer, đó là khác biệt lớn.

Bạn không muốn mỗi người phải nhớ prompt rằng project dùng pnpm, test billing bằng make test billing, không được đổi API response shape, không được log PII, PR phải có regression test.

Những thứ đó nên nằm trong repo guidance.

Tài liệu OpenAI nói Codex reads AGENTS.md files before doing any work.

Codex build một instruction chain khi start, gồm global guidance, project specific guidance và nested overrides theo thư mục.

Files gần current directory có thể override guidance rộng hơn vì chúng xuất hiện later trong combined prompt.

Bài này giải thích cách dùng AGENTS.md cho Codex theo hướng production developer workflow: đặt file ở đâu, viết gì, override thế nào, audit loading ra sao, và tránh biến AGENTS.md thành bãi rác prompt dài ảo tưởng.

AGENTS.md giải quyết vấn đề gì?

Nếu không có AGENTS.md, mỗi prompt phải nhắc lại: repo layout; install command; test command; lint/typecheck command; coding convention; dependency policy; security rules; PR expectation; definition of done; review focus; những file không được đụng.

Lặp lại thủ công kiểu này có ba vấn đề.

Thứ nhất, con người quên.

Task nhỏ thì quên chạy test, task gấp thì quên constraint, task mới thì không biết convention.

Thứ hai, prompt dài làm task khó đọc.

Nếu 70% prompt là rule nền, phần yêu cầu thật bị chìm.

Thứ ba, team không nhất quán.

Mỗi developer prompt một kiểu, Codex hành xử một kiểu.

AGENTS.md biến các rule lặp lại thành instruction bền.

Prompt từng task chỉ cần nói goal/context cụ thể, còn repo guidance được load trước.

Codex đọc AGENTS.md như thế nào?

Theo docs, Codex build instruction chain khi start, thường là một lần mỗi run hoặc một lần mỗi launched TUI session.

Discovery có ba tầng quan trọng.