Cấu trúc của thư mục .claude/

Người dùng Claude Code thường coi thư mục .claude giống như một hộp đen. Họ biết nó tồn tại. Họ đã thấy nó xuất hiện trong thư mục gốc dự án của họ. Nhưng họ chưa bao giờ mở nó chứ đừng nói đến việc hiểu từng tập tin bên trong nó làm gì.

Đó là một cơ hội bị bỏ lỡ.

Thư mục .claude là trung tâm điều khiển cách Claude hoạt động trong dự án của bạn.

Nó chứa các hướng dẫn, lệnh tùy chỉnh, quy tắc cấp phép của bạn và thậm chí cả bộ nhớ của Claude qua các phiên. Sau khi hiểu những gì tồn tại ở đâu và tại sao, bạn có thể định cấu hình Claude Code để hoạt động chính xác theo cách mà nhóm của bạn cần.

Bản tin này sẽ hướng dẫn bạn toàn bộ cấu trúc của thư mục, từ các tệp bạn sẽ sử dụng hàng ngày đến những tệp bạn sẽ đặt một lần rồi quên.

Trước khi đi sâu vào, bạn nên biết trước một điều: thực ra có hai thư mục .claude chứ không phải một.

Cái đầu tiên nằm trong dự án của bạn và cái thứ hai nằm trong thư mục chính của bạn:

Thư mục cấp dự án chứa cấu hình nhóm. Bạn commit nó với git. Mọi người trong nhóm đều có cùng quy tắc, lệnh tùy chỉnh giống nhau, chính sách cấp phép giống nhau.

Thư mục ~/.claude/ chung chứa các tùy chọn cá nhân và trạng thái máy cục bộ của bạn, như lịch sử phiên và bộ nhớ tự động.

Đây là tệp quan trọng nhất trong toàn bộ hệ thống. Khi bạn bắt đầu phiên Mã Claude, nội dung đầu tiên nó đọc là CLAUDE.md. Nó tải thẳng vào lời nhắc hệ thống và ghi nhớ nó trong toàn bộ cuộc trò chuyện.

Nói một cách đơn giản: bất cứ điều gì bạn viết trong CLAUDE.md, Claude sẽ làm theo.

Nếu bạn yêu cầu Claude luôn viết bài kiểm tra trước khi triển khai, điều đó sẽ làm theo. Nếu bạn nói “không bao giờ sử dụng console.log để xử lý lỗi, hãy luôn sử dụng mô-đun ghi nhật ký tùy chỉnh”, nó sẽ luôn tôn trọng điều đó.

Một CLAUDE.md tại gốc dự án của bạn là thiết lập phổ biến nhất. Nhưng bạn cũng có thể có một tùy chọn trong ~/.claude/CLAUDE.md cho các tùy chọn chung áp dụng cho tất cả các dự án và thậm chí một tùy chọn bên trong các thư mục con dành cho các quy tắc dành riêng cho thư mục. Claude đọc tất cả chúng và kết hợp chúng lại.

Hầu hết mọi người đều viết quá nhiều hoặc quá ít. Đây là những gì hoạt động.

Viết:

• Các lệnh xây dựng, kiểm tra và tìm lỗi mã nguồn (npm run test, make build, v.v.)

• Các quyết định kiến ​​trúc quan trọng ("chúng tôi sử dụng monorepo với Turborepo")

• Các vấn đề không rõ ràng ("Chế độ nghiêm ngặt của TypeScript được bật, các biến không được sử dụng là lỗi")

• Quy ước nhập, mẫu đặt tên, kiểu xử lý lỗi

• Cấu trúc tệp và thư mục cho các mô-đun chính

Không viết:

• Bất kỳ thứ gì thuộc về cấu hình kẻ nói dối hoặc trình định dạng

• Tài liệu đầy đủ mà bạn có thể liên kết tới

• Các đoạn văn dài giải thích lý thuyết

Giữ CLAUDE.md dưới 200 dòng. Các tệp dài hơn thế bắt đầu chiếm quá nhiều ngữ cảnh và việc tuân thủ hướng dẫn của Claude thực sự giảm xuống.

Đây là một ví dụ tối giản nhưng hiệu quả:

Đó là ~20 dòng. Nó cung cấp cho Claude mọi thứ cần thiết để làm việc hiệu quả trong cơ sở mã này mà không cần phải liên tục làm rõ.

Đôi khi, bạn có một sở thích dành riêng cho mình chứ không phải cho cả nhóm. Có thể bạn thích một trình chạy thử nghiệm khác hoặc bạn muốn Claude luôn mở tệp bằng một mẫu cụ thể.

Tạo CLAUDE.local.md trong thư mục gốc dự án của bạn. Claude đọc nó cùng với CLAUDE.md chính và nó tự động được gitignored để các chỉnh sửa cá nhân của bạn không bao giờ xuất hiện trong repo.

CLAUDE.md hoạt động hiệu quả cho một dự án. Nhưng khi nhóm của bạn phát triển, bạn sẽ có một CLAUDE.md dài 300 dòng mà không ai duy trì và mọi người đều bỏ qua.

Thư mục rules/ sẽ giải quyết vấn đề đó.

Mọi tệp đánh dấu bên trong .claude/rules/ sẽ được tải cùng với bạn CLAUDE.md tự động. Thay vì một tệp khổng lồ, bạn chia hướng dẫn theo mối quan tâm:

Mỗi tệp luôn tập trung và dễ cập nhật. Thành viên nhóm sở hữu các quy ước API chỉnh sửa api-conventions.md. Người sở hữu tiêu chuẩn kiểm tra chỉnh sửa testing.md. Không ai dẫm đạp lên nhau.

Sức mạnh thực sự đến từ các quy tắc có phạm vi đường dẫn. Thêm khối frontmatter YAML vào tệp quy tắc và nó chỉ kích hoạt khi Claude đang làm việc với các tệp phù hợp:

Claude sẽ không tải tệp này khi chỉnh sửa thành phần React. Nó chỉ tải khi nó hoạt động bên trong src/api/ hoặc src/handlers/. Các quy tắc không có trường đường dẫn tải vô điều kiện trong mỗi phiên.

Đây là mẫu phù hợp khi CLAUDE.md của bạn bắt đầu có cảm giác đông đúc.

Ngay từ đầu, Claude Code đã tích hợp sẵn các lệnh gạch chéo như /help và /compact. Thư mục commands/ cho phép bạn thêm lệnh của riêng mình.

Mỗi tệp đánh dấu bạn thả vào .claude/commands/ sẽ trở thành lệnh gạch chéo.

Một tệp có tên review.md tạo ra /project:review. Tệp có tên fix-issue.md tạo /project:fix-issue. Tên tệp là tên lệnh.

Đây là một ví dụ đơn giản. Tạo .claude/commands/review.md:

Bây giờ hãy chạy /project:review trong Mã Claude> và nó sẽ tự động đưa git diff thực vào dấu nhắc trước khi Claude nhìn thấy nó. Cú pháp ! backtick chạy các lệnh shell và nhúng kết quả đầu ra. Đó là lý do khiến các lệnh này thực sự hữu ích thay vì chỉ lưu văn bản.

Sử dụng $ARGUMENTS để chuyển văn bản sau tên lệnh:

Đang chạy /project:fix-issue 234 cung cấp nội dung của vấn đề 234 trực tiếp vào dấu nhắc.

Các lệnh dự án trong .claude/commands/ được cam kết và chia sẻ với nhóm của bạn. Đối với các lệnh bạn muốn ở mọi nơi bất kể dự án, hãy đặt chúng vào ~/.claude/commands/. Thay vào đó, chúng hiển thị dưới dạng /user:command-name.

Một lệnh cá nhân hữu ích: công cụ trợ giúp dự phòng hàng ngày, lệnh tạo thông báo cam kết theo quy ước của bạn hoặc quét bảo mật nhanh chóng.

Giờ đây, bạn đã biết lệnh hoạt động như thế nào. Các kỹ năng bề ngoài trông có vẻ giống nhau, nhưng về cơ bản thì cách kích hoạt lại khác nhau. Đây là điểm khác biệt trước khi chúng ta tiến xa hơn:

Kỹ năng là các quy trình làm việc mà Claude có thể tự thực hiện mà không cần bạn gõ lệnh gạch chéo khi nhiệm vụ khớp với mô tả của kỹ năng. Các lệnh đang chờ bạn. Các kỹ năng theo dõi cuộc trò chuyện và hành động khi đến thời điểm thích hợp.

Mỗi kỹ năng tồn tại trong thư mục con riêng với tệp SKILL.md:

SKILL.md sử dụng YAML frontmatter để mô tả thời điểm sử dụng nó:

Khi bạn nói “xem lại PR này để biết các vấn đề bảo mật”, Claude đọc mô tả, nhận ra nó phù hợp và tự động sử dụng kỹ năng. Bạn cũng có thể gọi nó một cách rõ ràng bằng /security-review.

Sự khác biệt chính so với các lệnh: các kỹ năng có thể gộp các tệp hỗ trợ bên cạnh chúng. Tham chiếu DETAILED_GUIDE.md ở trên dẫn đến một tài liệu chi tiết nằm ngay bên cạnh SKILL.md. Các lệnh là các tập tin duy nhất. Kỹ năng là những gói.

Kỹ năng cá nhân có trong ~/.claude/skills/ và có sẵn trong tất cả các dự án của bạn.

Khi một nhiệm vụ đủ phức tạp để được hưởng lợi từ một chuyên gia tận tâm, bạn có thể xác định nhân cách đại lý phụ trong .claude/agents/. Mỗi tác nhân là một tệp đánh dấu có lời nhắc hệ thống, quyền truy cập công cụ và tùy chọn mô hình riêng:

Đây là giao diện của code-reviewer.md:

Khi Claude cần thực hiện đánh giá mã, nó sẽ sinh ra tác nhân này trong cửa sổ ngữ cảnh biệt lập của riêng nó. Tác nhân thực hiện công việc của mình, nén các phát hiện và báo cáo lại. Phiên chính của bạn sẽ không bị lộn xộn với hàng nghìn mã thông báo khám phá trung gian.

Trường công cụ hạn chế những gì tác nhân có thể làm. Kiểm toán viên bảo mật chỉ cần Đọc, Grep và Glob. Nó không có tập tin văn bản kinh doanh. Hạn chế đó là có chủ ý và đáng được nêu rõ.

Trường mô hình cho phép bạn sử dụng mô hình rẻ hơn, nhanh hơn cho các nhiệm vụ tập trung. Haiku xử lý tốt hầu hết các hoạt động khám phá chỉ đọc. Hãy để dành Sonnet và Opus cho những công việc thực sự cần đến chúng.

Các tác nhân cá nhân truy cập ~/.claude/agents/ và có sẵn trên tất cả các dự án.

Tệp settings.json bên trong .claude/ kiểm soát những gì Claude được phép làm và không được phép làm. Đó là nơi bạn xác định những công cụ nào Claude có thể chạy, những tệp nào nó có thể đọc và liệu nó có cần hỏi trước khi chạy một số lệnh nhất định hay không.

Tệp hoàn chỉnh trông như thế này:

Đây là chức năng của từng phần.

Dòng $schema cho phép tự động hoàn thành và xác thực nội tuyến trong Mã hoặc Con trỏ VS. Luôn bao gồm nó.

Danh sách cho phép chứa các lệnh chạy mà không cần Claude yêu cầu xác nhận. Đối với hầu hết các dự án, danh sách cho phép phù hợp bao gồm:

• Bash(npm run *) hoặc Bash(make *) để Claude có thể chạy tập lệnh của bạn một cách tự do

• Bash(git *) cho các lệnh git chỉ đọc

• Đọc, viết, chỉnh sửa, Glob, Grep for file hoạt động

Danh sách từ chối chứa các lệnh bị chặn hoàn toàn, bất kể điều gì. Danh sách từ chối hợp lý chặn:

• Các lệnh shell phá hủy như rm -rf

• Các lệnh mạng trực tiếp nhưcurl

• Các tệp nhạy cảm như .env và bất cứ thứ gì trong secrets/

Nếu nội dung nào đó không có trong cả hai danh sách, Claude sẽ hỏi trước khi tiếp tục. Nền tảng trung gian đó là có chủ ý. Nó cung cấp cho bạn một mạng lưới an toàn mà không cần phải lường trước mọi lệnh có thể xảy ra.

Điều đó có nghĩa là bạn cũng có thể có settings.local.json để ghi đè cá nhân. Nó có ý tưởng tương tự như CLAUDE.local.md. Tạo .claude/settings.local.json cho những thay đổi về quyền mà bạn không muốn thực hiện. Nó được tự động gitignored.

Bạn không thường xuyên tương tác với thư mục này nhưng sẽ rất hữu ích nếu biết trong đó có gì.

~/.claude/CLAUDE.md tải vào mỗi phiên Claude Code, trên tất cả các dự án của bạn. Nơi lý tưởng cho các nguyên tắc mã hóa cá nhân, phong cách ưa thích của bạn hoặc bất cứ điều gì bạn muốn Claude ghi nhớ, bất kể bạn đang ở kho lưu trữ nào.

~/.claude/projects/ lưu trữ bản ghi phiên và bộ nhớ tự động cho mỗi dự án. Claude Code tự động lưu các ghi chú vào chính nó khi nó hoạt động: các lệnh mà nó phát hiện, các mẫu mà nó quan sát và hiểu biết sâu sắc về kiến ​​trúc. Những điều này vẫn tồn tại qua các phiên. Bạn có thể duyệt và chỉnh sửa chúng bằng /memory.

~/.claude/commands/ và ~/.claude/skills/ lưu giữ các lệnh và kỹ năng cá nhân có sẵn trong tất cả các dự án.

Bạn thường không cần phải quản lý chúng theo cách thủ công. Nhưng biết rằng chúng tồn tại sẽ rất hữu ích khi Claude dường như “ghi nhớ” điều gì đó mà bạn chưa bao giờ kể hoặc khi bạn muốn xóa bộ nhớ tự động của dự án và bắt đầu lại.

Đây là cách mọi thứ kết hợp với nhau:

Nếu bạn bắt đầu lại từ đầu thì đây là một tiến trình hoạt động hiệu quả.

Bước 1. Chạy /init bên trong Claude Code. Nó tạo ra một CLAUDE.md khởi đầu bằng cách đọc dự án của bạn. Chỉnh sửa nó ở mức cần thiết.

Bước 2. Thêm .claude/settings.json với các quy tắc cho phép/từ chối phù hợp với ngăn xếp của bạn. Ở mức tối thiểu, hãy cho phép các lệnh chạy của bạn và từ chối việc đọc .env.

Bước 3. Tạo một hoặc hai lệnh cho quy trình làm việc mà bạn thực hiện nhiều nhất. Đánh giá mã và khắc phục vấn đề là điểm khởi đầu tốt.

Bước 4. Khi dự án của bạn phát triển và CLAUDE.md của bạn ngày càng đông đúc, hãy bắt đầu chia hướng dẫn thành các tệp .claude/rules/. Hãy phân bổ chúng theo đường dẫn phù hợp.

Bước 5. Thêm ~/.claude/CLAUDE.md kèm theo tùy chọn cá nhân của bạn. Đây có thể là những thứ như “luôn viết các loại trước khi triển khai” hoặc “thích các mẫu chức năng hơn là dựa trên lớp”.

Đó thực sự là tất cả những gì bạn cần cho 95% dự án. Các kỹ năng và tác nhân sẽ xuất hiện khi bạn có các quy trình công việc phức tạp định kỳ đáng được chuẩn bị.

Thư mục .claude thực sự là một giao thức để cho Claude biết bạn là ai, dự án của bạn làm gì và dự án đó phải tuân theo những quy tắc nào. Bạn xác định điều đó càng rõ ràng thì bạn càng dành ít thời gian để sửa Claude và nó càng dành nhiều thời gian để làm công việc hữu ích.

CLAUDE.md là tệp có đòn bẩy cao nhất của bạn. Hãy làm điều đó đúng trước. Mọi thứ khác đều là tối ưu hóa.

Hãy bắt đầu từ quy mô nhỏ, tinh chỉnh khi bạn thực hiện và xử lý nó giống như bất kỳ phần cơ sở hạ tầng nào khác trong dự án của bạn: thứ mang lại lợi nhuận hàng ngày khi được thiết lập đúng cách.

Cảm ơn bạn đã đọc!