Hướng dẫn CLAUDE.md

Viết CLAUDE.md Hoàn hảo

CLAUDE.md là file duy nhất định hình cách Claude hiểu dự án của bạn. Một file được viết tốt có nghĩa là ít chỉnh sửa hơn, code tốt hơn và agent thực sự biết họ đang làm gì.

Hướng dẫn này đi qua từng phần của file CLAUDE.md, từ khai báo tech stack đến gợi ý đặc thù theo agent. Theo dõi và xây dựng của bạn từng bước một.

CLAUDE.md là gì?

CLAUDE.md là file markdown bạn đặt ở gốc dự án. Khi Claude Code bắt đầu phiên, nó đọc file này trước. Mọi thứ bên trong trở thành một phần ngữ cảnh của Claude: tech stack, cấu trúc file, quy ước nhóm và bất kỳ hướng dẫn cụ thể nào bạn muốn mọi agent tuân theo.

Hãy coi nó như tài liệu briefing. Không có nó, Claude phải đoán cách dự án được tổ chức. Với một tài liệu tốt, Claude đã biết mọi thứ ở đâu, pattern nào cần tuân theo và điều gì cần tránh. Sự khác biệt về chất lượng output khá đáng kể.

“Đầu tư 10 phút vào CLAUDE.md tiết kiệm hàng giờ chỉnh sửa code do AI tạo ra không khớp với pattern dự án.”

Quan sát trên hàng trăm dự án Claude Code

CLAUDE.md Kém vs. Tốt

Cấu trúc và tính cụ thể của CLAUDE.md trực tiếp ảnh hưởng đến mức độ Claude hoạt động tốt trong codebase.

CLAUDE.md Yếu

✗Hướng dẫn mơ hồ như "dùng best practices" mà không có chi tiết cụ thể
✗Không có bản đồ cấu trúc file, Claude đoán đặt code mới ở đâu
✗Thiếu quy ước coding; phong cách output thay đổi giữa các phiên
✗Không có lệnh build hoặc test nào được liệt kê, dẫn đến đề xuất bị hỏng

CLAUDE.md Mạnh

✓Tech stack rõ ràng kèm phiên bản: React 19, Vite 6, Zustand 5, Tailwind 4
✓Bản đồ file rõ ràng hiển thị các thư mục chính và mục đích
✓Pattern đặt tên, xử lý lỗi và tùy chọn phong cách được tài liệu hóa
✓Lệnh build, test và dev sẵn sàng copy và chạy

6 Phần Cần thiết

CLAUDE.md có cấu trúc tốt bao gồm sáu lĩnh vực này. Mỗi lĩnh vực cung cấp cho Claude thông tin cụ thể mà nó có thể hành động ngay lập tức.

Khai báo Tech Stack

Liệt kê framework, thư viện và phiên bản của chúng một cách rõ ràng. Bao gồm package manager, phiên bản Node và bất kỳ yêu cầu runtime nào. Claude dùng điều này để tạo code tương thích mà không cần đoán.

Bản đồ Cấu trúc File

Mô tả các thư mục chính và những gì nằm trong mỗi thư mục. Components, store, service, API route, type. Sơ đồ cây ngắn với mô tả một dòng mỗi thư mục hoạt động tốt.

Quy ước Coding

Tài liệu hóa pattern đặt tên (camelCase cho file, PascalCase cho component), cách xử lý lỗi, thứ tự import và bất kỳ quy tắc đặc thù dự án nào. Điều này giữ output của Claude nhất quán với code hiện có.

Lệnh Build và Test

Bao gồm lệnh dev, build, test và lint. Khi Claude cần xác minh điều gì hoạt động hoặc đề xuất script, nó sẽ dùng các lệnh chính xác mà dự án yêu cầu.

Gợi ý Vai trò Agent

Nếu bạn dùng nhiều agent (QA, frontend, backend, DevOps), thêm phần mô tả mỗi vai trò nên tập trung vào gì. Điều này đặc biệt hữu ích với thiết lập đa agent của AgentsRoom.

Khu vực Cần Tránh

Nói cho Claude biết những gì KHÔNG làm. Đừng sửa file cấu hình, đừng thay đổi hệ thống auth, đừng refactor tầng database. Ranh giới rõ ràng ngăn agent thực hiện các thay đổi không mong muốn.

Xây dựng CLAUDE.md trong 4 Bước

Bạn không cần viết mọi thứ cùng lúc. Bắt đầu với những điều cơ bản và mở rộng khi bạn khám phá Claude cần biết gì.

Kiểm tra Dự án

Mở package.json và liệt kê mọi framework, thư viện và công cụ dự án sử dụng. Ghi chú phiên bản. Kiểm tra yêu cầu runtime (phiên bản Node, Python, database). Đây trở thành phần tech stack.

package.json + phiên bản runtime + database

Lập bản đồ File Tree

Chạy tree nhanh của thư mục src. Xác định các thư mục cấp cao nhất và viết mô tả một dòng cho mỗi cái. Tập trung vào nơi component, store, service, type và API route nằm.

Cây src/ với chú thích mục đích

Tài liệu hóa Quy ước

Xem code hiện có và ghi chú các pattern: cách đặt tên file, xử lý lỗi, cấu trúc import, dùng default hay named export. Viết chúng thành các quy tắc ngắn gọn.

Đặt tên, import, xử lý lỗi, export

Thêm Phần đặc thù theo Agent

Nếu bạn làm việc với agent chuyên biệt, thêm khu vực tập trung cho mỗi vai trò. Agent frontend nên biết thư viện component. Agent DevOps nên biết pipeline deployment. Agent QA nên biết framework kiểm thử.

Khu vực tập trung theo vai trò + khu vực cần tránh

Tại sao Dùng AgentsRoom cho CLAUDE.md?

AgentsRoom được xây dựng xung quanh CLAUDE.md như một khái niệm hạng nhất, không phải suy nghĩ thêm sau.

Trình soạn thảo CLAUDE.md Tích hợp

Chỉnh sửa CLAUDE.md trực tiếp trong AgentsRoom với tô sáng cú pháp và lưu trực tiếp. Không cần chuyển sang trình soạn thảo văn bản hay IDE.

Xem trước Trực tiếp theo Agent

Xem mỗi agent diễn giải CLAUDE.md theo thời gian thực. Xem output terminal để xác minh agent tuân theo quy ước và tôn trọng các khu vực cần tránh.

Ngữ cảnh theo Dự án

Mỗi dự án trong AgentsRoom có CLAUDE.md riêng. Chuyển đổi giữa các dự án và mỗi agent tự động tải file ngữ cảnh đúng cho codebase đó.

Tích hợp Vai trò Agent

14 vai trò agent của AgentsRoom kết hợp trực tiếp với các phần CLAUDE.md. Định nghĩa khu vực tập trung và khu vực cần tránh theo vai trò, và mỗi agent lấy đúng hướng dẫn dành cho nó.

FAQ về CLAUDE.md

Tôi nên đặt file CLAUDE.md ở đâu?+

Đặt ở gốc thư mục dự án, cạnh package.json hoặc file cấu hình tương đương. Claude Code đọc tự động khi bắt đầu phiên trong thư mục đó. Bạn cũng có thể có file CLAUDE.md lồng nhau trong các thư mục con cho ngữ cảnh cụ thể hơn.

File CLAUDE.md nên dài bao nhiêu?+

Không có giới hạn cứng, nhưng hãy nhắm vào 50 đến 300 dòng. Bao gồm những điều cần thiết: tech stack, cấu trúc file, quy ước và lệnh. Quá ngắn thì Claude thiếu ngữ cảnh. Quá dài thì bạn có nguy cơ pha loãng các phần quan trọng bằng nhiễu.

CLAUDE.md có hoạt động với tất cả model Claude không?+

Có. CLAUDE.md được đọc bởi Claude Code bất kể model nào được chọn (Opus, Sonnet hoặc Haiku). Tất cả model đều hưởng lợi từ ngữ cảnh dự án rõ ràng, mặc dù các model lớn hơn như Opus có thể hấp thụ và áp dụng các hướng dẫn chi tiết hơn.

Tôi có nên commit CLAUDE.md vào version control không?+

Có, cho các hướng dẫn dự án dùng chung. Nhóm được hưởng lợi từ hành vi AI nhất quán trên tất cả developer. Đối với sở thích cá nhân, AgentsRoom hỗ trợ cấu hình agent cá nhân được tự động gitignored.

Tôi có thể dùng CLAUDE.md với thiết lập đa agent không?+

Hoàn toàn có thể. Trong AgentsRoom, mọi agent trong dự án đều đọc CLAUDE.md giống nhau. Bạn có thể thêm các phần đặc thù theo vai trò (ví dụ: ghi chú cho agent QA vs. agent frontend) để mỗi chuyên gia nhận được hướng dẫn được nhắm đến.

Tôi nên cập nhật CLAUDE.md thường xuyên như thế nào?+

Cập nhật khi cấu trúc hoặc quy ước dự án thay đổi. Thêm framework mới? Cập nhật tech stack. Chuyển sang bố cục thư mục mới? Cập nhật bản đồ file. CLAUDE.md cũ dẫn đến đề xuất cũ.