claude-md 精选

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

写作 Claude Code MCP 客户端 MIT 4.2 万

在 GitHub 打开

安装方式

cp -r vi/03-skills/claude-md ~/.claude/skills/claude-md-3

把该 skill 目录放进客户端 skills 目录。不同客户端的目录可能不同，Claude Code 默认是 ~/.claude/skills/

整仓一次性获取：git clone --depth 1 https://github.com/luongnv89/claude-howto.git

依赖与权限

无需 API Key
无需联网
依赖外部命令：node bun pip uv cargo
以上为按正文与 frontmatter 自动推断的信号，仅供参考；安装前建议先阅读原文。

SKILL.md 正文

来源 luongnv89/claude-howto@065ab37 · 许可 MIT · 内容未修改

Đầ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: ./CLAUDE.md hoặc .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/:

agent_docs/
  |- building_the_project.md
  |- running_tests.md
  |- code_conventions.md
  |- architecture_decisions.md

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:

Từ v2.1.277, Claude Code đọc AGENTS.md trực tiếp như hướng dẫn dự án — nhưng chỉ khi thư mục làm việc và mọi thư mục phía trên nó đều không có CLAUDE.md, .claude/CLAUDE.md, hay CLAUDE.local.md. ~/.claude/CLAUDE.md, CLAUDE.md được quản lý, và .claude/rules/ không tính vào kiểm tra đó và vẫn được tải song song. Hành vi này được điều khiển bởi Project instructions trong /config: claude-md-or-agents-md (mặc định), claude-md-and-agents-md, claude-md, hoặc managed-only. Ở nơi không hỗ trợ đọc trực tiếp — phiên bản trước v2.1.277 (trước v2.1.281 trên Bedrock/Vertex/Foundry, LLM gateway, hoặc khi telemetry bị tắt), hoặc phiên đầu tiên sau khi nâng cấp — hãy dùng cách dự phòng: import từ CLAUDE.md bằng @AGENTS.md, hoặc symlink CLAUDE.md tới nó.

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