CLAUDE.md và AGENTS.md: là gì, nên viết gì và vì sao agent bỏ qua quy tắc

CLAUDE.md và AGENTS.md là gì

Đây là các tệp Markdown thông thường ở thư mục gốc của repository, và agent tự động nạp chúng vào ngữ cảnh khi bắt đầu phiên. Qua các tệp này, bạn cho agent biết những điều nó không thể tự suy ra từ mã nguồn: cách khởi động môi trường, lệnh nào dùng để kiểm chứng công việc, quy tắc nào của dự án không được bàn cãi và tài liệu chi tiết nằm ở đâu.

CLAUDE.md là tệp mà Claude Code đọc. AGENTS.md là định dạng mở với cùng ý tưởng, và nhiều agent lập trình hỗ trợ nó. Nếu trong nhóm dùng nhiều agent khác nhau, nên giữ nội dung chính trong AGENTS.md và trong CLAUDE.md chỉ tham chiếu đến nó. Claude Code hỗ trợ nhập một tệp khác bằng dòng bắt đầu với @:

# CLAUDE.md
@AGENTS.md

Nhờ vậy các quy tắc nằm ở một nơi duy nhất và không bị lệch nhau giữa hai tệp.

Agent đọc các tệp này như thế nào

Nội dung tệp hướng dẫn được đưa vào cửa sổ ngữ cảnh của mô hình cùng với system prompt và nằm đó suốt phiên. Từ đây có ba hệ quả quan trọng.

• Mỗi dòng đều chiếm chỗ trong ngữ cảnh. Tệp được đọc toàn bộ mỗi lần khởi động, ngay cả khi tác vụ hiện tại chỉ cần một phần mười của nó.
• Đây là văn bản, không phải quy tắc có thể thực thi. Mô hình xem xét nó ngang với phần còn lại của ngữ cảnh, và không có gì đảm bảo nó được tuân thủ 100%. Các cấm đoán nghiêm ngặt cần được hỗ trợ bằng cơ chế: kiểm chứng, hook, quyền truy cập.
• Có thể lồng tệp vào nhau. Claude Code nạp CLAUDE.md từ thư mục gốc dự án và từ thư mục người dùng ~/.claude/, còn các tệp trong thư mục con thì được nạp khi agent làm việc với tệp trong các thư mục đó. Nhờ vậy có thể đặt quy tắc của một module ngay cạnh module đó.

Nên viết gì trong CLAUDE.md và AGENTS.md

Tệp hướng dẫn tốt là bản đồ, không phải sách giáo khoa. Nó trả lời những câu hỏi mà agent sẽ hỏi một đồng nghiệp giàu kinh nghiệm vào ngày đầu tiên.

1. Cách xây dựng và kiểm chứng dự án

Đây là phần có giá trị nhất. Các lệnh cụ thể mà agent bắt buộc phải chạy trước khi nói «xong»: kiểm thử, linter, kiểm tra kiểu, khởi động môi trường. Không có chúng, agent chỉ kiểm tra công việc bằng cảm tính.

2. Ràng buộc cứng

Danh sách ngắn những điều không được vi phạm trong bất kỳ hoàn cảnh nào: các bất biến về an toàn và dữ liệu. Hãy viết dưới dạng bất biến, không phải hướng dẫn triển khai: «mọi truy vấn SQL đều tham số hoá», chứ không phải «dùng hàm đó trong tệp kia».

3. Bản đồ dự án

Mọi thứ nằm ở đâu: vài dòng về cấu trúc thư mục và nơi tìm chi tiết. Với mỗi chủ đề lớn, có một liên kết đến tài liệu riêng mà agent sẽ mở chỉ khi làm việc với chủ đề đó.

4. Trạng thái công việc được lưu ở đâu

Cần nhìn vào đâu để tiếp tục từ chỗ phiên trước đã dừng: tệp kế hoạch, nhật ký tiến độ, backlog. Đây là cách chữa chứng «mất trí nhớ» của agent giữa các phiên.

Những gì không nên viết

• Thứ agent có thể tự biết từ mã nguồn. Danh sách phụ thuộc có trong package.json hoặc pyproject.toml, cấu trúc lớp nằm ngay trong mã.
• Lời khuyên chung chung. «Viết mã sạch», «hãy cẩn thận» không thay đổi hành vi và chỉ chiếm chỗ.
• Lịch sử dự án và ghi chú nhất thời. «Hồi tháng Ba chúng tôi chuyển từ MySQL 5.7» không giúp ích cho tác vụ hiện tại.
• Hướng dẫn chi tiết cho các tác vụ hiếm. Quy trình triển khai hay di chuyển dữ liệu chỉ cần một lần mỗi tuần — hãy chuyển nó sang tài liệu riêng hoặc skill.
• Bí mật. Tệp nằm trong repository và được đưa toàn bộ vào mô hình. Token và mật khẩu chỉ nên để trong biến môi trường.

Vì sao agent bỏ qua quy tắc đã được viết trong tệp

Câu chuyện điển hình: agent mắc lỗi, người ta thêm một quy tắc vào tệp. Lỗi lần nữa, thêm tiếp một quy tắc. Vài tháng sau, tệp đã có hàng trăm dòng, và một quy tắc an toàn quan trọng bị agent vi phạm như thể nó không tồn tại. Thường có bốn nguyên nhân, và chúng tác động cùng lúc.

Tệp phình to

Tệp 600 dòng tương đương khoảng 10–20 nghìn token. Cửa sổ ngữ cảnh có vẻ rất lớn, nhưng nó phải chia sẻ với mã nguồn, kết quả lệnh và lịch sử hội thoại. Hướng dẫn chiếm càng nhiều chỗ thì mỗi quy tắc càng ít được chú ý, và tác vụ thực tế càng bị thu hẹp.

Quy tắc nằm giữa tệp

Các mô hình ngôn ngữ sử dụng thông tin ở giữa một văn bản dài kém hiệu quả hơn so với phần đầu và phần cuối. Quy tắc ở dòng thứ ba trăm trong sáu trăm dòng nằm đúng ở điểm yếu nhất.

Không có thứ tự ưu tiên

Một cấm đoán không được bàn cãi và một ghi chú nhỏ về phong cách được trình bày giống hệt nhau, đều là một dòng trong danh sách. Agent không có cách nào biết điều gì quan trọng hơn. Và nếu tệp có ba quy tắc phong cách mâu thuẫn nhau, hành vi sẽ ngẫu nhiên từ lần chạy này sang lần khác.

Mục nát

Thêm một quy tắc thì miễn phí, nhưng xoá đi thì đáng sợ: «lỡ có thứ gì đó phụ thuộc vào nó thì sao». Vì vậy tệp chỉ tăng lên đều đều, còn tỷ lệ dòng hữu ích thì giảm. Có thể đo điều này bằng tỷ lệ tín hiệu/nhiễu: bao nhiêu dòng thực sự cần cho một tác vụ điển hình, và bao nhiêu dòng thì không.

Cách khắc phục: bộ định tuyến thay vì bức tường văn bản

Chỉ sửa một nguyên nhân thì vô ích: nếu rút gọn tệp mà không tổ chức lại, các quy tắc vẫn lẫn lộn. Cần một tập hợp biện pháp.

1. Biến tệp đầu vào thành bộ định tuyến. 50–150 dòng: lệnh kiểm chứng, ràng buộc cứng, bản đồ dự án và liên kết đến các tài liệu theo chủ đề.
2. Tách chủ đề ra tệp riêng. Ví dụ docs/agents/deploy.md, docs/agents/database.md. Agent mở chúng khi cần. Trong Claude Code, với các quy trình lặp lại, skills rất tiện vì chúng chỉ được nạp khi thực sự cần.
3. Đưa điều quan trọng lên đầu. Ràng buộc cứng đặt ở đầu tệp, thành một khối ngắn có đánh dấu rõ ràng MUST.
4. Loại bỏ mâu thuẫn. Mỗi chủ đề chỉ có một quy tắc. Nếu có ngoại lệ, hãy viết nó ngay bên cạnh quy tắc.
5. Củng cố quy tắc bằng cơ chế. Nếu vi phạm là không thể chấp nhận, chỉ viết văn bản là chưa đủ. Cần một kiểm chứng để bắt lỗi: linter, kiểm thử, hook pre-commit hoặc hook của agent, hay chặn bằng quyền truy cập.
6. Rà soát định kỳ. Đặt giới hạn số dòng, và mỗi lần thêm nội dung hãy tự hỏi: có thể xoá hoặc chuyển đi phần nào?

Quy tắc hay kiểm chứng?

Ví dụ AGENTS.md gọn gàng

# AGENTS.md — backend thanh toán (FastAPI, PostgreSQL)

## MUST — không được vi phạm
- Số tiền là int theo đơn vị xu, tuyệt đối không dùng float
- Chỉ dùng SQL tham số hoá, không dùng f-string
- Không sửa các migration đã áp dụng, chỉ thêm migration mới
- Bí mật chỉ lấy từ biến môi trường

## Kiểm chứng trước khi nói «xong»
docker compose up -d     # môi trường
make lint                # ruff + mypy
make test                # pytest
make e2e                 # kịch bản đặt hàng
Unit test xanh mà không có e2e thì chưa được coi là «xong».

## Bản đồ
- app/payments/   — tính tiền, chiết khấu, webhook của nhà cung cấp
- app/api/        — các HTTP endpoint
- tests/e2e/      — kịch bản người dùng
Chi tiết: docs/agents/architecture.md, docs/agents/database.md

## Trạng thái công việc
- PLAN.md      — mục tiêu hiện tại, tiêu chí hoàn thành, bước tiếp theo
- PROGRESS.md  — những gì đã làm và cách kiểm chứng, ngõ cụt
- BACKLOG.md   — những việc phát hiện «tiện thể»: ghi vào đây, không sửa ngay

Cuối phiên, cập nhật PROGRESS.md và bước tiếp theo trong PLAN.md.

Hãy lưu ý những gì không có ở đây: danh sách thư viện, lời khuyên về phong cách, lịch sử dự án. Tất cả hoặc nhìn thấy được từ mã nguồn, hoặc được đảm bảo bằng kiểm chứng, hoặc nằm trong tài liệu theo chủ đề.

Trí nhớ giữa các phiên: tệp hướng dẫn cộng với tệp kế hoạch

Tệp hướng dẫn mô tả cách làm việc trong dự án, nhưng không nói điều gì đang diễn ra. Vì vậy cần một tệp trạng thái riêng, agent đọc khi bắt đầu và cập nhật khi kết thúc phiên. Trong đó có: mục tiêu, những việc đã làm kèm cách kiểm chứng, các quyết định kèm lý do, các phương án đã bị loại và một câu mô tả bước tiếp theo. Cách kiểm tra chất lượng đơn giản: mở một phiên mới, viết «tiếp tục» và xem agent có bắt đầu làm việc hữu ích mà không cần hỏi thêm không.

Đừng nhầm lẫn hai tệp này. Hướng dẫn thay đổi hiếm và áp dụng cho mọi tác vụ. Kế hoạch thay đổi mỗi phiên và chỉ liên quan đến tác vụ hiện tại. Nếu trộn chúng lại, tệp hướng dẫn sẽ nhanh chóng phình ra với các ghi chú đã lỗi thời.

Làm sao kiểm tra tệp có hoạt động không

Tệp hướng dẫn cũng cần được kiểm tra. Lấy vài tác vụ điển hình — sửa lỗi, một tính năng nhỏ, tái cấu trúc — và xem agent làm gì mà không cần gợi ý: nó có chạy đúng lệnh cần thiết không, có mở đúng tài liệu theo chủ đề không, có tuân thủ ràng buộc cứng không. Nếu một quy tắc bị vi phạm, trước tiên hãy tự hỏi: nó có dễ thấy không, có bị mâu thuẫn với điều khác không, và có thể thay bằng một kiểm chứng tự động không. Thêm một dòng mới là biện pháp cuối cùng.

Tóm lại

CLAUDE.md và AGENTS.md là điểm vào của agent khi làm việc với dự án. Chúng hiệu quả khi vẫn là bản đồ ngắn gọn: lệnh kiểm chứng, ràng buộc cứng ở trên cùng, liên kết đến chi tiết và đến tệp kế hoạch. Nếu một quy tắc bị bỏ qua, nguyên nhân gần như luôn là một tệp phình to, không có cấu trúc; còn các quy tắc thực sự quan trọng cần được củng cố bằng kiểm chứng và hook. Cách tổ chức hướng dẫn và trạng thái của agent được trình bày chi tiết qua thực hành trong khoá học harness engineering.