Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Tạo hoặc cập nhật các file CLAUDE.md theo các thực hành tốt nhất để onboarding tác nhân AI tối ưu
Đầu Vào Người Dùng
$ARGUMENTS
Bạn BẮT BUỘC phải xem xét đầu vào của người dùng trước khi tiếp tục (nếu không trống). Người dùng có thể chỉ định:
create - Tạo CLAUDE.md mới từ đầu
update - Cải thiện CLAUDE.md hiện có
audit - Phân tích và báo cáo về chất lượng CLAUDE.md hiện tại
Một đường dẫn cụ thể để tạo/cập nhật (ví dụ: src/api/CLAUDE.md cho hướng dẫn cụ thể thư mục)
Nguyên Tắc Cốt Lõi
LLMs là không trạng thái: CLAUDE.md là file duy nhất được bao gồm tự động trong mọi cuộc hội thoại. Nó phục vụ như tài liệu onboarding chính cho các tác nhân AI vào codebase của bạn.
Các Quy Tắc Vàng
Less is More: Các LLM biên giới có thể theo ~150-200 hướng dẫn. System prompt của Claude Code đã sử dụng ~50. Giữ CLAUDE.md của bạn tập trung và ngắn gọn.
Ứng Dụng Phổ Biến: Chỉ bao gồm thông tin liên quan đến MỌI phiên. Hướng dẫn cụ thể theo tác vụ thuộc về các file riêng.
Đừng Sử Dụng Claude như Linter: Hướng dẫn phong cách làm phình bối cảnh và làm giảm khả năng tuân theo hướng dẫn. Sử dụng các công cụ xác định (prettier, eslint, v.v.) thay thế.
Không Bao Giờ Tự Động Tạo: CLAUDE.md là điểm đòn bẩy cao nhất của hệ thống AI. Tạo nó thủ công với sự xem xét cẩn thận.
Quy Trình Thực Thi
1. Phân Tích Dự Án
Đầu tiên, phân tích trạng thái dự án hiện tại:
Kiểm tra các file CLAUDE.md hiện có:
Cấp root: hoặc
./CLAUDE.md
.claude/CLAUDE.md
Cụ thể thư mục: **/CLAUDE.md
Cấu hình người dùng toàn cầu: ~/.claude/CLAUDE.md
Xác định cấu trúc dự án:
Technology stack (ngôn ngữ, frameworks)
Loại dự án (monorepo, ứng dụng đơn, library)
Công cụ phát triển (quản lý package, hệ thống build, trình chạy test)
Xem lại tài liệu hiện có:
README.md
CONTRIBUTING.md
package.json, pyproject.toml, Cargo.toml, v.v.
2. Chiến Lược Nội Dung (WHAT, WHY, HOW)
Cấu trúc CLAUDE.md xung quanh ba chiều:
WHAT - Công Nghệ & Cấu Trúc
Tổng quan technology stack
Tổ chức dự án (đặc biệt quan trọng cho monorepos)
Các thư mục chính và mục đích của chúng
WHY - Mục Đích & Bối Cảnh
Dự án làm gì
Tại sao các quyết định kiến trúc nhất định được đưa ra
Mỗi thành phần chính chịu trách nhiệm cho gì
HOW - Workflow & Quy Ước
Workflow phát triển (bun vs node, pip vs uv, v.v.)
Thủ tục và lệnh testing
Phương pháp xác minh và build
Các "gotchas" quan trọng hoặc yêu cầu không rõ ràng
3. Chiến Lược Progressive Disclosure
Đối với các dự án lớn, khuyến nghị tạo thư mục agent_docs/:
Trong CLAUDE.md, tham khảo các file này với các hướng dẫn như:
Để có hướng dẫn build chi tiết, tham khảo `agent_docs/building_the_project.md`
Quan Trọng: Sử dụng các tham chiếu file:line thay vì các đoạn code để tránh bối cảnh lỗi thời.
4. Ràng Buộc Chất Lượng
Khi tạo hoặc cập nhật CLAUDE.md:
Độ Dài Mục Tiêu: Dưới 300 dòng (lý tưởng dưới 100)
Không Quy Tắc Phong Cách: Loại bỏ bất kỳ hướng dẫn linting/formatting nào
Không Hướng Dẫn Cụ Theo Tác Vụ: Di chuyển sang các file riêng
Không Đoạn Code: Sử dụng tham chiếu file thay thế
Không Thông Tin Dư Thừa: Đừng lặp lại những gì trong package.json hoặc README
5. Các Phần Thiết Yếu
Một CLAUDE.md được cấu trúc tốt nên bao gồm:
# Tên Dự Án
Mô tả ngắn một dòng.
## Tech Stack- Ngôn ngữ chính và phiên bản
- Frameworks/thư viện chính
- Database/lưu trữ (nếu có)
## Cấu Trúc Dự Án
[Chỉ cho monorepos hoặc cấu trúc phức tạp]
-`apps/` - Điểm vào ứng dụng
-`packages/` - Thư viện được chia sẻ
## Lệnh Phát Triển- Install: `command`- Test: `command`- Build: `command`## Quy Ước Quan Trọng
[Chỉ các quy ước không rõ ràng, tác động cao]
- Quy ước 1 với giải thích ngắn
- Quy ước 2 với giải thích ngắn
## Vấn Đế Đã Biết / Gotchas
[Những gì luôn làm các nhà phát triển vấp phải]
- Vấn đề 1
- Vấn đề 2
6. Các Anti-Patterns Cần Tránh
KHÔNG bao gồm:
Hướng dẫn phong cách code (sử dụng linters)
Tài liệu về cách sử dụng Claude
Giải thích dài về các mẫu rõ ràng
Các ví dụ code copy-paste
Thực hành tốt chung ("viết code sạch")
Hướng dẫn cho các tác vụ cụ thể
Nội dung được tạo tự động
Danh sách TODO mở rộng
7. Checklist Xác Minh
Trước khi hoàn thành, xác minh:
Dưới 300 dòng (lý tưởng dưới 100)
Mọi dòng áp dụng cho TẤT CẢ các phiên
Không quy tắc phong cách/formatting
Không đoạn code (sử dụng tham chiếu file)
Các lệnh được xác minh hoạt động
Progressive disclosure được sử dụng cho các dự án phức tạp
Các gotchas quan trọng được tài liệu hóa
Không dư thừa với README.md
Định Dạng Đầu Ra
Cho create hoặc mặc định:
Phân tích dự án
Soạn thảo CLAUDE.md theo cấu trúc ở trên
Trình bày bản nháp để xem xét
Ghi vào vị trí phù hợp sau khi được chấp thuận
Cho update:
Đọc CLAUDE.md hiện có
Kiểm tra theo các thực hành tốt nhất
Xác định:
Nội dung để loại bỏ (quy tắc phong cách, đoạn code, cụ thể tác vụ)
Nội dung để cô đọng
Thông tin thiết bị còn thiếu
Trình bày các thay đổi để xem xét
Áp dụng các thay đổi sau khi được chấp thuận
Cho audit:
Đọc CLAUDE.md hiện có
Tạo một báo cáo với:
Số dòng hiện tại vs mục tiêu
Phần trăm nội dung áp dụng phổ biến
Danh sách các anti-patterns được tìm thấy
Khuyến nghị cải thiện
KHÔNG chỉnh sửa file, chỉ báo cáo
Xử Lý AGENTS.md
Nếu người dùng yêu cầu tạo/cập nhật AGENTS.md:
Claude Code KHÔNG đọc AGENTS.md trực tiếp. Để nó có hiệu lực, hãy import từ CLAUDE.md bằng @AGENTS.md, hoặc symlink CLAUDE.md tới nó. Đây là hiểu lầm phổ biến nhất về file này.
AGENTS.md là file bối cảnh dự án dùng chung giữa nhiều công cụ — cùng loại tài liệu với CLAUDE.md, không phải định dạng định nghĩa tác nhân. Nó tồn tại để nhiều coding agent có thể dùng chung một bộ quy ước dự án:
Các lệnh build, test, và lint
Quy ước code style và kiến trúc
Bố cục repository và vị trí của các thành phần
Subagents được định nghĩa riêng, trong .claude/agents/*.md — không phải trong AGENTS.md.
Áp dụng các nguyên tắc tương tự:
Giữ tập trung và ngắn gọn
Sử dụng progressive disclosure
Tham khảo tài liệu bên ngoài thay vì nhúng nội dung
Ghi Chú
Luôn xác minh các lệnh hoạt động trước khi bao gồm chúng
Khi nghi ngờ, hãy loại bỏ - less is more
Lời nhắc hệ thống cho Claude biết rằng CLAUDE.md "có thể hoặc có thể không liên quan" - càng nhiều tiếng ồn, càng bị bỏ qua
Monorepos hưởng lợi nhất từ cấu trúc WHAT/WHY/HOW rõ ràng
Các file CLAUDE.md cụ thể thư mục nên được tập trung hơn nữa
