Viết gì trong CLAUDE.md

Nếu bạn thường xuyên phải nhắc Claude Code về cùng một bộ quy tắc của dự án, hãy ghi chúng vào CLAUDE.md. Đây chỉ là một tệp văn bản thông thường theo định dạng Markdown. Claude Code đọc tệp này khi bắt đầu phiên và tiếp nhận các quy ước của bạn cùng với phần ngữ cảnh còn lại.

Ban đầu, chỉ cần vài dòng đã được kiểm chứng: làm việc ở đâu, kiểm tra kết quả thế nào và cần giữ lại điều gì khi có thay đổi.

Ví dụ về CLAUDE.md

Hãy lấy một trang đơn giản có các thẻ. Phần markup, style và JavaScript đều nằm trong cùng một tệp index.html; bạn có thể mở trang trực tiếp trong trình duyệt. Với dự án như vậy, tệp hướng dẫn có thể trông như sau:

# CLAUDE.md

## Dự án
- Trang, style và JavaScript nằm trong `index.html`.

## Kiểm tra
- Mở `index.html` trong trình duyệt.
- Kiểm tra trang ở màn hình rộng và hẹp.

## Quy tắc
- Giữ nguyên màu sắc và phong cách thẻ hiện tại.
- Không xóa các khối đã hoàn thiện nếu chưa được xác nhận.
- Sau khi làm xong, liệt kê các thay đổi và bước kiểm tra.

Ở đây có ba nhóm: cấu trúc dự án, cách kiểm tra kết quả và các quy ước. Giờ đây, khi yêu cầu "thêm một thẻ nữa", bạn không cần nhắc lại mọi quy tắc. Tuy vậy, bạn vẫn có thể tự kiểm tra trang: có hướng dẫn không đồng nghĩa agent có thể dùng trình duyệt nếu không được cung cấp công cụ đó.

Đây là ví dụ cho dự án chỉ gồm một tệp, không phải mẫu dùng cho mọi dự án. Dự án của bạn có thể có các thư mục và lệnh khởi chạy riêng. Hãy ghi đúng những thư mục và lệnh đó; nếu không có kiểm thử, đừng bịa thêm lệnh chỉ để cho đủ.

Nên ghi lại những gì

Tiêu chí chính: ghi chú này có cần cho các tác vụ sau không? Những lệnh đã kiểm chứng, đường dẫn quan trọng và quy ước mà agent không thể tự suy ra một cách chắc chắn từ mã đều hữu ích. Nhất là những điều bạn đã phải nhắc lại.

Hãy viết quy tắc sao cho rõ agent cần thực hiện hành động nào:

• "kiểm tra mọi thứ" → "sau khi sửa các thẻ, hãy kiểm tra trang ở màn hình rộng và hẹp";
• "đừng đụng vào phần quan trọng" → "đừng xóa các khối đã hoàn thiện nếu chưa được xác nhận: nội dung của chúng đã được thống nhất".

Ví dụ đầu nêu rõ bước kiểm tra, ví dụ sau nêu phạm vi giới hạn và lý do. Cách này hữu ích hơn một danh sách dài những mong muốn như "hãy làm cẩn thận".

README.md giải thích cho người đọc dự án này là gì và cách bắt đầu. CLAUDE.md tập hợp hướng dẫn dành cho agent. Không cần chép lại toàn bộ README. Còn giả thuyết như "có vẻ chú thích bị lệch vì chiều rộng của thẻ" thì hãy để trong ghi chú của tác vụ hiện tại, chẳng hạn PROJECT_NOTE.md. Đây là một tệp thông thường với tên do bạn chọn; khi tiếp tục tác vụ, hãy yêu cầu agent đọc tệp đó.

Đừng ghi giả định thành sự thật đã được xác nhận, và cũng đừng lưu mật khẩu hay khóa truy cập ở đây. CLAUDE.md dùng chung thường được đưa vào Git để đồng nghiệp nhận được những hướng dẫn đó ngay khi lấy dự án về.

Cách tạo và kiểm tra tệp

Hãy bắt đầu với những quy tắc bạn đã biết. Không cần đợi đến khi có cả danh sách dài các lỗi hay mô tả trước mọi tình huống có thể xảy ra.

1. Kiểm tra xem dự án đã có tệp CLAUDE.md chưa. Nếu có, hãy đọc rồi bổ sung. Nếu tạo tệp mới, hãy đặt ở thư mục gốc của dự án; .claude/CLAUDE.md cũng được hỗ trợ, nhưng không cần tạo cả hai bản.
2. Tự viết vài dòng hoặc nhập /init trong Claude Code đang mở ở thư mục dự án. Lệnh này sẽ khảo sát dự án và tạo bản nháp; nếu tệp đã tồn tại, nó sẽ đề xuất cải thiện.
3. Đọc kết quả. Đối chiếu lệnh và đường dẫn với dự án rồi xóa những điều phỏng đoán. Chẳng hạn, nếu agent thêm lệnh kiểm thử mà dự án không có, hãy xóa lệnh đó. Tự bổ sung những giới hạn chỉ bạn mới biết.
4. Lưu tệp rồi mở một phiên mới trong thư mục dự án. Nhập /context: trong mục Memory files phải có đường dẫn đến CLAUDE.md của bạn.

Sau đó thử sửa một chi tiết nhỏ: chẳng hạn yêu cầu thêm một thẻ, rồi xem màu sắc có được giữ nguyên và báo cáo kiểm tra có xuất hiện không. Nếu không thấy tệp trong danh sách, trước hết hãy kiểm tra tên tệp và thư mục khởi chạy. Nếu thấy tệp nhưng kết quả không khớp quy tắc, hãy xem lại cách diễn đạt và các mâu thuẫn có thể có.

Ghi những điều khác ở đâu

Một tệp CLAUDE.md là đủ cho dự án đầu tiên. Khi có thêm chỉ dẫn cá nhân hoặc nhiều quy tắc chung, sơ đồ sau sẽ giúp bạn chọn nơi ghi lại:

Một quy tắc chung có thể chỉ áp dụng cho một thư mục mà vẫn cần thiết với cả nhóm. .claude/rules/ giúp chia các hướng dẫn như vậy theo chủ đề; giới hạn theo đường dẫn cụ thể được cấu hình riêng. Với vài quy tắc thì không cần làm cấu trúc phức tạp hơn.

CLAUDE.local.md phù hợp để ghi chỉ dẫn cá nhân trong dự án này, chẳng hạn sở thích nhận câu trả lời ngắn. Thêm tệp vào .gitignore để tránh commit. Agent vẫn đọc tệp cục bộ, vì vậy cũng đừng để bí mật trong đó.

Bộ nhớ tự động (auto memory) là các ghi chú riêng mà Claude lưu trong quá trình làm việc nếu tính năng này được bật. Đừng để một quy tắc quan trọng phụ thuộc hoàn toàn vào việc cơ chế này có lưu hay không: hãy yêu cầu thẳng việc thêm quy tắc đó vào CLAUDE.md. Giả thuyết tạm thời về bug thì để trong ghi chú của tác vụ.

Nếu dự án đã có AGENTS.md, đừng chép nội dung của nó sang tệp thứ hai. Bạn có thể nạp tệp nằm cạnh bằng dòng @AGENTS.md trong CLAUDE.md. Điều này đặc biệt hữu ích khi thêm CLAUDE.local.md: tệp cá nhân có thể ảnh hưởng đến việc đọc trực tiếp AGENTS.md. Các lựa chọn khác được mô tả trong tài liệu.

Khi nào nên cập nhật quy tắc

Hãy chỉnh sửa tệp cùng với dự án. Nếu chuyển style từ index.html sang một tệp riêng, hãy sửa dòng mô tả cấu trúc. Nếu thay đổi cách kiểm tra, hãy thay hướng dẫn cũ. Đừng thêm quy tắc mới chồng lên quy tắc cũ đang mâu thuẫn.

Một lời nhắc bạn cứ phải lặp lại có thể giao cho agent ghi vào tệp:"Thêm vào CLAUDE.md quy tắc rằng tôi cần xác nhận trước khi xóa một khối đã hoàn thiện". Sau đó hãy đọc lại thay đổi: nội dung phải thể hiện đúng điều bạn đã thống nhất, agent không được tự thêm giới hạn mới. Thường một dòng là đủ.

Nếu một quy tắc bị vi phạm, trước hết hãy tìm nguyên nhân thay vì nhắc lại thêm ba lần. Xóa những ghi chú đã lỗi thời và chỉ giữ lại điều hữu ích cho tác vụ tiếp theo.