CLAUDE.md và AGENTS.md: viết hướng dẫn dự án cho AI

Bài này dựa trên tài liệu Claude Code về cách Claude ghi nhớ dự án và trang AGENTS.md, đọc ngày 11/11/2026. Hỗ trợ AGENTS.md của Claude Code thay đổi trong năm 2026: bài viết cũ có thể ghi là chưa hỗ trợ, còn tài liệu hiện hành nói Claude Code đọc AGENTS.md từ phiên bản 2.1.277. Hãy kiểm tra phiên bản bạn đang dùng.

Vì sao cần tệp hướng dẫn dự án?

Tài liệu Claude Code mở đầu bằng một sự thật đơn giản: mỗi phiên làm việc bắt đầu với một cửa sổ ngữ cảnh mới. Những gì bạn giải thích hôm qua ("dự án dùng pytest", "đừng đụng vào thư mục legacy/") không còn ở đó hôm nay. Có hai cơ chế mang kiến thức qua các phiên: tệp CLAUDE.md do bạn viết, và bộ nhớ tự động do Claude tự ghi khi bạn sửa nó.

CLAUDE.md giống bản bàn giao cho một đồng nghiệp mới, chỉ khác là đồng nghiệp này đọc lại nó mỗi sáng. Tài liệu gợi ý thêm điều vào CLAUDE.md khi:

• Claude mắc cùng một lỗi lần thứ hai;
• buổi duyệt code phát hiện điều mà Claude lẽ ra phải biết về kho mã này;
• bạn gõ lại vào ô chat đúng lời sửa đã gõ ở phiên trước;
• một thành viên mới cũng cần đúng bối cảnh đó để làm việc được.

Một điểm quan trọng: tài liệu nói rõ Claude coi CLAUDE.md là ngữ cảnh, không phải cấu hình bắt buộc. Nội dung CLAUDE.md được đưa vào như một tin nhắn sau chỉ dẫn hệ thống; Claude đọc và cố làm theo, nhưng không có gì bảo đảm tuân thủ tuyệt đối, nhất là với chỉ dẫn mơ hồ hay mâu thuẫn. Muốn chặn một hành động dù Claude nghĩ gì, hãy dùng hook (xem hooks cho AI).

Nên viết gì vào CLAUDE.md, và không nên viết gì?

Tài liệu khuyên chỉ giữ những sự thật Claude cần ở mọi phiên: lệnh build, lệnh test, quy ước, cấu trúc dự án, các luật kiểu "luôn làm X". Hai loại nội dung nên để chỗ khác:

Cũng đừng đưa khóa API hay mật khẩu vào bất kỳ tệp nào trong số này: tệp được commit nằm mãi trong lịch sử git. Xem giữ khóa API an toàn.

Viết thế nào để AI làm theo?

Vì CLAUDE.md là ngữ cảnh chứ không phải luật cưỡng chế, cách viết ảnh hưởng trực tiếp tới việc AI có làm theo hay không. Tài liệu đưa ba nguyên tắc.

Cụ thể đến mức kiểm được. Ví dụ tài liệu đưa ra, chuyển sang tình huống của dự án Python:

Ngắn và có cấu trúc. Tài liệu đặt mục tiêu dưới 200 dòng mỗi tệp: tệp dài tốn ngữ cảnh hơn và làm AI làm theo kém đi. Nhóm chỉ dẫn liên quan dưới các tiêu đề Markdown và gạch đầu dòng; mục rõ ràng dễ theo hơn đoạn văn dày.

Nhất quán. Nếu hai chỉ dẫn mâu thuẫn, Claude có thể chọn một cách tùy ý. Hãy định kỳ rà lại CLAUDE.md, các tệp CLAUDE.md trong thư mục con và .claude/rules/ để bỏ chỉ dẫn lỗi thời hoặc trái nhau. Tài liệu có lệnh /doctor prompt-audit để Claude tự rà các tệp hướng dẫn, tìm chỉ dẫn viết cho mô hình cũ, tệp hay lệnh không còn tồn tại.

Một mẹo nhỏ: chú thích HTML dạng khối (<!-- ghi chú -->) trong CLAUDE.md bị bỏ đi trước khi đưa vào ngữ cảnh. Bạn có thể để lại ghi chú cho người bảo trì mà không tốn chỗ ngữ cảnh.

Một CLAUDE.md mẫu cho dự án Python

Ví dụ cho một bài tập lớn quản lý thư viện viết bằng Python, gọn trong vài chục dòng:

# Dự án quản lý thư viện

## Lệnh
- Cài đặt: `python -m venv .venv` rồi `pip install -r requirements.txt`
- Chạy test: `python -m pytest -q`
- Chạy ứng dụng: `python -m thu_vien`

## Cấu trúc
- `thu_vien/`: mã nguồn; `thu_vien/api/`: các hàm nhận yêu cầu
- `tests/`: test, mỗi tệp `test_<mô-đun>.py` ứng với một mô-đun

## Quy ước
- Thụt lề 4 dấu cách, dòng tối đa 100 ký tự.
- Tên biến và hàm tiếng Việt không dấu, viết thường nối bằng gạch dưới.
- Mỗi hàm mới có ít nhất một test, gồm cả trường hợp danh sách rỗng.

## Không làm
- Không sửa dữ liệu mẫu trong `du_lieu/goc/`.
- Không thêm thư viện mới khi chưa hỏi.

## Quy trình git
@docs/git.md

Dòng cuối là một lệnh nhập (xem mục sau): quy trình git dài được để trong tệp riêng và nạp kèm.

Muốn có bản nháp nhanh, lệnh /init trong Claude Code phân tích kho mã và tạo một CLAUDE.md ban đầu gồm lệnh build, cách chạy test và quy ước nó tìm thấy; nếu đã có CLAUDE.md thì nó đề xuất cải thiện. Đây là điểm xuất phát tốt, nhưng hãy đọc lại và cắt những gì AI tự suy ra được từ code.

Đặt CLAUDE.md ở đâu và chúng được nạp thế nào?

Theo tài liệu, Claude Code nạp CLAUDE.md từ thư mục làm việc và mọi thư mục cha của nó lúc khởi động; các tệp này nối tiếp vào ngữ cảnh chứ không ghi đè nhau, theo thứ tự từ thư mục gốc xuống thư mục hiện tại. Tệp CLAUDE.md trong thư mục con thì không nạp ngay mà nạp khi Claude đọc, ghi hay sửa một tệp trong thư mục con đó. Để chắc tệp đã được nạp, chạy /context all và xem danh sách "Memory files"; lệnh /memory mở các tệp này để sửa.

Nhập tệp khác bằng @

CLAUDE.md có thể nhập tệp khác bằng cú pháp @đường/dẫn. Theo tài liệu:

• Đường dẫn tương đối tính theo tệp chứa lệnh nhập, không theo thư mục làm việc.
• Tệp được nhập có thể nhập tiếp tệp khác, tối đa bốn bước.
• Đường dẫn có dấu cách thì đặt dấu \ trước mỗi dấu cách.
• Lệnh nhập nằm trong dấu nháy ngược hay khối code không có hiệu lực. Muốn nhắc tới @README mà không nhập, hãy đặt nó trong dấu nháy ngược.
• Lần đầu gặp lệnh nhập trỏ ra ngoài thư mục dự án, Claude Code hỏi bạn chấp thuận, để bảo vệ bạn khỏi tệp người khác commit vào dự án chung.

Chia luật theo thư mục với .claude/rules/

Với dự án lớn, đặt các tệp Markdown theo chủ đề vào .claude/rules/ (ví dụ testing.md, security.md). Luật không có giới hạn đường dẫn được nạp lúc khởi động, cùng mức ưu tiên với .claude/CLAUDE.md. Luật có trường paths trong khối YAML đầu tệp chỉ áp dụng khi Claude làm việc với tệp khớp mẫu, nên quy ước riêng cho thư mục api/ không chiếm chỗ khi bạn đang sửa giao diện.

AGENTS.md là gì, và Claude Code đọc nó thế nào?

Trang chính thức gọi AGENTS.md là một định dạng mở, đơn giản để hướng dẫn agent lập trình, tức một "README cho agent". README viết cho người: giới thiệu nhanh, mô tả dự án, cách đóng góp. AGENTS.md chứa bối cảnh chi tiết mà agent cần như các bước build, test và quy ước, những thứ làm README rối hoặc người đọc không cần. Trang gợi ý các mục: tổng quan dự án, lệnh build và test, phong cách code, cách test, lưu ý bảo mật; không trường nào bắt buộc. Với kho nhiều dự án con, mỗi dự án con có thể có AGENTS.md riêng, và agent đọc tệp gần nhất trong cây thư mục.

Theo trang này, định dạng được nhiều công cụ hỗ trợ, như Codex, Cursor, Gemini CLI, VS Code, tác tử lập trình của GitHub Copilot, Windsurf, Zed và Aider, và được quản lý bởi Agentic AI Foundation thuộc Linux Foundation.

Claude Code xử lý AGENTS.md như sau (tài liệu hiện hành, cần phiên bản 2.1.277 trở lên):

Cách đơn giản nhất để mọi công cụ dùng chung một tệp: viết hướng dẫn chung trong AGENTS.md, và nếu cần thêm điều riêng cho Claude thì tạo CLAUDE.md có dòng đầu là @AGENTS.md, phần dưới là phần riêng. Tài liệu cho biết giữ lệnh nhập này không làm Claude đọc AGENTS.md hai lần. Có thể đổi mặc định (đọc cả hai, chỉ CLAUDE.md...) bằng mục "Project instructions" trong /config.

Rà soát CLAUDE.md bằng code

Hai lỗi hay gặp nhất là chỉ dẫn mơ hồ và lệnh nhập trỏ tới tệp không có. Đoạn Python dưới đây rà một tệp CLAUDE.md: đếm dòng, đánh dấu vài cụm từ mơ hồ hay gặp, và lần theo các lệnh @ (tương đối theo tệp chứa nó, tối đa bốn bước, bỏ qua phần trong dấu nháy ngược và khối code). Danh sách cụm từ mơ hồ chỉ là gợi ý; bạn tự thêm những cụm nhóm mình hay viết.

"""Rà soát một tệp CLAUDE.md (hoặc AGENTS.md) theo các khuyến nghị trong tài liệu Claude Code (đọc ngày 11/11/2026).

- Độ dài: nên dưới 200 dòng mỗi tệp.
- Câu chỉ dẫn mơ hồ, không kiểm được (như "viết code sạch") nên đổi thành điều cụ thể ("thụt lề 4 dấu cách").
- Lệnh nhập @đường/dẫn: tính tương đối theo tệp chứa nó, nhập lồng tối đa 4 bước; bỏ qua phần trong dấu nháy ngược
  và khối code. Báo tệp được nhập mà không có.
Công cụ chỉ gợi ý; nó không biết chỉ dẫn nào đúng cho dự án của bạn.
"""
import os
import re
import tempfile

MO_HO = ["code sạch", "cho đẹp", "cho gọn", "cẩn thận", "đúng chuẩn", "tốt nhất có thể", "hợp lý", "kiểm tra kỹ",
         "properly", "clean code", "best practice"]
NHAP = re.compile(r"(?:(?<=\s)|^)@((?:\\ |[^\s`])+)")
SAU_TOI_DA = 4


def bo_code(noi_dung):
    """Bỏ khối code rào bằng ``` và đoạn trong dấu nháy ngược, vì lệnh nhập ở đó không có hiệu lực."""
    noi_dung = re.sub(r"```.*?```", "", noi_dung, flags=re.S)
    return re.sub(r"`[^`\n]*`", "", noi_dung)


def tim_nhap(noi_dung):
    return [m.group(1).replace("\\ ", " ") for m in NHAP.finditer(bo_code(noi_dung))]


def ra_soat(duong_dan):
    ket_qua = []
    with open(duong_dan, encoding="utf-8") as f:
        noi_dung = f.read()
    so_dong = len(noi_dung.splitlines())
    if so_dong >= 200:
        ket_qua.append(f"dài {so_dong} dòng, nên dưới 200: chuyển phần chỉ dùng cho một thư mục sang .claude/rules/")
    for i, dong in enumerate(noi_dung.splitlines(), 1):
        thap = dong.lower()
        for cum in MO_HO:
            if cum in thap:
                ket_qua.append(f"dòng {i}: \"{cum}\" khó kiểm, hãy viết điều cụ thể làm được và kiểm được")
    ket_qua += _kiem_nhap(duong_dan, 0, {os.path.abspath(duong_dan)})
    return ket_qua


def _kiem_nhap(tep, sau, da_tham):
    ket_qua = []
    with open(tep, encoding="utf-8") as f:
        ds = tim_nhap(f.read())
    for dich in ds:
        p = os.path.abspath(os.path.join(os.path.dirname(tep), os.path.expanduser(dich)))
        ten = os.path.relpath(p, os.path.dirname(tep)).replace(os.sep, "/")
        if not os.path.isfile(p):
            ket_qua.append(f"@{dich}: không có tệp {ten}")
            continue
        if sau + 1 > SAU_TOI_DA:
            ket_qua.append(f"@{dich}: lồng {sau + 1} bước, quá {SAU_TOI_DA} bước nên sẽ không được nạp")
            continue
        if p not in da_tham:
            ket_qua += _kiem_nhap(p, sau + 1, da_tham | {p})
    return ket_qua


def tao_mau(goc):
    os.makedirs(os.path.join(goc, "docs"))
    with open(os.path.join(goc, "docs", "git.md"), "w", encoding="utf-8") as f:
        f.write("- Nhánh tính năng đặt tên tinh-nang/<mô-tả-ngắn>.\n")
    with open(os.path.join(goc, "CLAUDE.md"), "w", encoding="utf-8") as f:
        f.write(
            "# Dự án quản lý thư viện\n\n"
            "## Lệnh\n- Chạy test: `python -m pytest -q`\n- Chạy app: `python -m thu_vien`\n\n"
            "## Quy ước\n- Thụt lề 4 dấu cách, tên biến tiếng Việt không dấu.\n"
            "- Viết code sạch và đúng chuẩn.\n- Quy trình git: @docs/git.md\n"
            "- Hướng dẫn triển khai: @docs/trien-khai.md\n"
            "- Ghi chú: email hỗ trợ là ho-tro@vi-du.vn, và `@README` chỉ là chữ.\n"
        )
    return os.path.join(goc, "CLAUDE.md")


def chay_thu():
    with tempfile.TemporaryDirectory() as goc:
        kq = ra_soat(tao_mau(goc))
        print(f"CLAUDE.md: {len(kq)} gợi ý")
        for x in kq:
            print("-", x)
        return kq


if __name__ == "__main__":
    chay_thu()

Với CLAUDE.md mẫu mà đoạn code tạo ra, kết quả là:

CLAUDE.md: 3 gợi ý
- dòng 9: "code sạch" khó kiểm, hãy viết điều cụ thể làm được và kiểm được
- dòng 9: "đúng chuẩn" khó kiểm, hãy viết điều cụ thể làm được và kiểm được
- @docs/trien-khai.md: không có tệp docs/trien-khai.md

Để ý rằng đoạn `@README` trong tệp mẫu không bị coi là lệnh nhập: tài liệu ghi rõ phần nhập bỏ qua chữ nằm giữa nháy ngược. Địa chỉ email ho-tro@vi-du.vn cũng không bị coi là lệnh nhập, nhưng đó là do đoạn code trên tự đặt luật "trước dấu @ phải là khoảng trắng", không phải điều tài liệu nói.

Câu hỏi thường gặp

Học tiếp

• Muốn đóng gói quy trình nhiều bước thay vì nhồi vào CLAUDE.md, đọc Agent Skills là gì.
• Muốn biến luật bắt buộc thành kiểm tra tự động, đọc hooks cho AI.
• Muốn nhìn lại cả bức tranh agent, đọc AI agent là gì.

Nếu bạn muốn học lập trình và cách làm việc với AI một cách có hệ thống, tham khảo khóa học AI của Big-O Coding.

Nguồn tham khảo

• Tài liệu Claude Code: How Claude remembers your project
• AGENTS.md: định dạng mở hướng dẫn agent lập trình
• Tài liệu Claude Code: How Claude Code works
• Tài liệu Claude Code: Skills