Phân tích cấu trúc thư mục `.claude/`

• Thư mục .claude/ là thư mục điều khiển cốt lõi của Claude Code, quản lý quy tắc, lệnh, quyền hạn và trạng thái bộ nhớ theo từng dự án
• CLAUDE.md là tệp trung tâm định nghĩa nguyên tắc hành vi và quy tắc dự án của Claude, được áp dụng bằng cách hợp nhất nhiều lớp cấu hình
• Các thư mục commands/, skills/, agents/ lần lượt cấu thành lệnh tùy biến, workflow tự động và sub-agent chuyên biệt, giúp tăng hiệu quả cộng tác
• settings.json kiểm soát quyền thực thi lệnh và phạm vi truy cập tệp, còn settings.local.json cho phép ghi đè theo từng cá nhân
• Toàn bộ cấu trúc hoạt động như một giao thức truyền đạt bản sắc và quy tắc của dự án cho Claude, và thiết lập rõ ràng sẽ tối đa hóa năng suất cũng như hiệu quả cộng tác

---

Cấu trúc thư mục .claude/ và các thành phần

• Thư mục .claude/ là thư mục cốt lõi điều khiển hoạt động của Claude Code, quản lý quy tắc, lệnh, quyền hạn và trạng thái bộ nhớ theo từng dự án
• Thư mục ở root dự án chứa cấu hình cấp nhóm và được commit vào Git
• Thư mục trong home directory (~/.claude/) lưu cấu hình cá nhân và lịch sử phiên, bao gồm bộ nhớ tự động và lệnh cá nhân

• CLAUDE.md — tài liệu chỉ dẫn của Claude

  • Đây là tệp được đọc đầu tiên khi bắt đầu một phiên Claude Code, dùng để định nghĩa nguyên tắc hành vi và quy tắc dự án của Claude
  • CLAUDE.md ở root dự án phụ trách quy tắc dùng chung của nhóm, ~/.claude/CLAUDE.md là quy tắc cá nhân toàn cục, còn CLAUDE.md trong các thư mục con đảm nhiệm quy tắc theo từng thư mục
  • Claude hợp nhất nhiều tệp CLAUDE.md để áp dụng
  • Nội dung được khuyến nghị gồm lệnh build/test, các quyết định kiến trúc chính, các ràng buộc khó đoán, quy tắc đặt tên và xử lý lỗi
  • Khuyến nghị giữ dưới 200 dòng; quá dài sẽ làm giảm mức độ tuân thủ chỉ dẫn của Claude

• CLAUDE.local.md — ghi đè theo từng cá nhân

  • Là tệp cho phép phản ánh sở thích cá nhân tách biệt với quy tắc chung của nhóm
  • Nếu tạo CLAUDE.local.md ở root dự án, Claude sẽ đọc cùng với các tệp khác
  • Tệp này tự động được đưa vào .gitignore nên không bị commit vào kho lưu trữ

• Thư mục rules/ — quản lý quy tắc theo mô-đun

  • Khi CLAUDE.md trở nên lớn, có thể tách ra để quản lý trong thư mục .claude/rules/
  • Mỗi tệp quy tắc được tách theo từng chủ đề, giúp dễ bảo trì
    • Ví dụ: code-style.md, testing.md, api-conventions.md, security.md
  • Dùng trường paths trong YAML frontmatter để chỉ định quy tắc chỉ áp dụng cho các đường dẫn cụ thể
    • Ví dụ: chỉ áp dụng quy tắc API cho đường dẫn src/api/**/*.ts
  • Quy tắc không chỉ định đường dẫn sẽ luôn được tải trong mọi phiên

• Thư mục commands/ — lệnh slash tùy chỉnh

  • Mỗi tệp Markdown trong thư mục .claude/commands/ sẽ được đăng ký thành lệnh slash (/)
    • Ví dụ: review.md → /project:review, fix-issue.md → /project:fix-issue
  • Có thể dùng cú pháp backtick ! để chèn kết quả thực thi lệnh shell vào prompt của Claude
    • Ví dụ: !git diff main...HEAD
  • Có thể dùng biến $ARGUMENTS để truyền đối số khi thực thi lệnh
    • Ví dụ: /project:fix-issue 234 → tự động tải nội dung GitHub issue 234
  • Lệnh dự án được chia sẻ với cả nhóm, còn lệnh cá nhân được lưu trong ~/.claude/commands/ và có thể dùng ở mọi dự án

• Thư mục skills/ — workflow tự động chạy

  • Hoạt động như workflow tương tự lệnh nhưng được kích hoạt tự động
  • Claude phân tích nội dung hội thoại và tự động chạy trong tình huống phù hợp
  • Mỗi skill được định nghĩa bằng tệp SKILL.md trong thư mục con, với YAML frontmatter để chỉ định điều kiện kích hoạt và công cụ được phép dùng
    • Ví dụ: skill security-review sẽ tự động chạy khi có hội thoại liên quan đến bảo mật
  • Thư mục skill có thể chứa tài liệu bổ trợ hoặc tệp mẫu như DETAILED_GUIDE.md
  • Skill cá nhân được lưu trong ~/.claude/skills/ và có thể dùng toàn cục

• Thư mục agents/ — sub-agent chuyên biệt

  • Thư mục .claude/agents/ định nghĩa các sub-agent (persona) đảm nhiệm vai trò cụ thể
  • Mỗi agent có system prompt, model và quyền truy cập công cụ riêng biệt
    • Ví dụ: code-reviewer.md, security-auditor.md
  • Có thể giới hạn công cụ được truy cập bằng trường tools để thực hiện bảo mật và phân tách vai trò
  • Có thể chọn model Claude phù hợp với công việc bằng trường model (ví dụ: Haiku, Sonnet, Opus)
  • Khi cần, Claude sẽ chạy agent đó trong ngữ cảnh riêng rồi chỉ tóm tắt kết quả để báo lại

• settings.json — quyền hạn và cấu hình dự án

  • .claude/settings.json định nghĩa quyền thực thi lệnh và phạm vi truy cập tệp của Claude
  • Trường $schema hỗ trợ tự động hoàn thành và kiểm tra hợp lệ trong VS Code và các công cụ tương tự
  • Danh sách allow chỉ định các lệnh được tự động phê duyệt, còn danh sách deny chỉ định các lệnh bị chặn hoàn toàn
    • Ví dụ: cho phép — Bash(npm run *), Read, Write, Edit
    • Chặn — Bash(rm -rf *), Bash(curl *), đọc tệp .env
  • Các lệnh không có trong danh sách sẽ yêu cầu người dùng xác nhận trước khi chạy
  • Thay đổi quyền hạn theo từng cá nhân được lưu trong .claude/settings.local.json và không được đưa vào Git

• Thư mục ~/.claude/ — cấu hình toàn cục và bộ nhớ

  • ~/.claude/CLAUDE.md là chỉ dẫn cá nhân áp dụng chung cho mọi dự án
  • ~/.claude/projects/ lưu lịch sử phiên theo từng dự án và bộ nhớ tự động
    • Duy trì các lệnh, mẫu và insight cấu trúc mà Claude đã học được
    • Có thể xem và chỉnh sửa bằng lệnh /memory
  • ~/.claude/commands/, ~/.claude/skills/, ~/.claude/agents/ là nơi lưu lệnh, skill và agent cá nhân toàn cục

• Ví dụ về toàn bộ cấu trúc

  your-project/  
  ├── CLAUDE.md  
  ├── CLAUDE.local.md  
  └── .claude/  
      ├── settings.json  
      ├── settings.local.json  
      ├── commands/  
      ├── rules/  
      ├── skills/  
      └── agents/  
  ~/.claude/  
  ├── CLAUDE.md  
  ├── settings.json  
  ├── commands/  
  ├── skills/  
  ├── agents/  
  └── projects/  
  

• Các bước thiết lập ban đầu

  • Bước 1: Tạo CLAUDE.md cơ bản bằng lệnh /init, sau đó chỉ giữ lại những nội dung cốt lõi
  • Bước 2: Viết .claude/settings.json, định nghĩa các quy tắc cho phép/chặn thực thi

  • Bước 3:Thêm lệnh phù hợp với các workflow dùng thường xuyên (ví dụ: review code, sửa issue)

    • Bước 4: Khi CLAUDE.md quá lớn, tách sang .claude/rules/
    • Bước 5: Thêm các quy tắc sở thích cá nhân vào ~/.claude/CLAUDE.md

Insight cốt lõi

• Thư mục .claude/ là giao thức truyền đạt bản sắc và quy tắc của dự án cho Claude
• CLAUDE.md là tệp quan trọng nhất, và nó càng được định nghĩa rõ ràng thì năng suất của Claude càng được tối đa hóa
• Các thành phần còn lại là những lớp tối ưu hóa bổ trợ cho nó và có thể mở rộng dần theo từng bước
• Thiết lập rõ ràng sẽ giúp giảm yêu cầu chỉnh sửa của Claude và tăng hiệu quả cộng tác

Thảo luận thêm

• Danh sách deny trong settings.json an toàn khi con người sử dụng, nhưng trong agent mode vẫn cần bảo vệ bổ sung vì có thể truy cập Bash
• OneCLI cung cấp lớp proxy ở cấp độ mạng thay thế credential token, giúp ngăn lộ thông tin bí mật
• Có ý kiến cho rằng về sau sẽ cần cấu hình .claude dành riêng cho agent mode (tách riêng quy tắc, quyền hạn, skill)
• Theo tài liệu mới nhất, commands và skills đang được hợp nhất: .claude/commands/deploy.md và .claude/skills/deploy/SKILL.md đều tạo ra lệnh /deploy, còn skill hỗ trợ thêm tính năng như tệp phụ trợ, tự động kích hoạt, v.v.

[GN⁺]

Bình luận trên Hacker News

• Việc xây bộ công cụ cho AI agent tạo cảm giác giống như đi tìm một thiết lập năng suất hoàn hảo
  Xem bài blog và YouTube để dựng quy trình, nhưng rốt cuộc người chỉ kiên trì làm việc với một danh sách việc cần làm đơn giản lại đi xa hơn
  Theo kinh nghiệm của tôi, cách đơn giản là để Plain Claude lập kế hoạch, rà soát rồi thực thi vẫn hoạt động tốt nhất

  • Với codebase lớn hoặc hệ thống phân tán thì câu chuyện khác
    Những kỹ năng kỹ thuật như để agent truyền dữ liệu, tạo request, theo dõi hệ thống và cập nhật mã giúp hiệu suất phát triển tăng vọt
    Với code quy mô 10 triệu dòng, năng suất đã tăng đáng kể, và phần tạo mã thực sự còn không chiếm đến 5%
    Phần lớn là nhờ khả năng nhanh chóng dựng toolchain để test và xác minh
  • Nhiều người đang rơi vào cái bẫy này và tốn tiền
    Thực ra nếu bạn biết rõ mình muốn gì và truyền đạt tốt, thì chỉ với AI cũng đã làm được rất nhiều việc
    Phần lớn mọi người không biết điều đó. Vì thế quá trình bắt nó lên kế hoạch trở thành đường tắt để đạt được sự thấu hiểu
  • Tôi là PM nên muốn agent tiết kiệm thời gian và tạo ra hiệu ứng lãi kép (compounding) cho đầu ra
    Nhưng việc phải lặp lại context ở mỗi session và sao chép các file .md là một sự kém hiệu quả
    Mục tiêu hiện tại là loại bỏ sự lặp lại này.
    Tôi tò mò mọi người quản lý một “context bank” tích lũy context như thế nào — ví dụ các thông tin cơ bản như “vai trò của tôi, sản phẩm tôi phụ trách, tài liệu mới nhất”
    Tài liệu thì bị trùng lặp và có nhiều thứ đã cũ nên cũng không thể đơn giản là nối toàn bộ Drive vào
    Nếu cùng một context lặp lại quá hai lần thì có nên tạo file Skill hay gom tài liệu vào một thư mục để quản lý hay không, tôi đang phân vân
  • Tôi cũng có trải nghiệm tương tự. Hầu hết các đầu ra sinh ra trong quá trình làm việc đều bị bỏ đi
    Cấu hình quá mức (over-configuration) gây suy giảm chất lượng và vấn đề lặp vòng
    Vì mô hình ngày càng tốt hơn nên những chỉ dẫn từng cần thiết trước đây đôi khi lại cản trở hiệu năng
    Tôi cũng nghe nói đội Anthropic reset claude.md mỗi 30 ngày
  • Ngược lại, tôi đang làm một dự án phải tích hợp API kế toán nội địa, mà đây là API hoàn toàn tùy biến nên LLM không biết
    Vì vậy tôi đã để Claude tạo một MCP server, và giờ nó tự động xử lý công việc kế toán
    Sau khi chốt sổ cuối tháng, tôi cho Claude trích xuất các tác vụ chính và biến chúng thành Skill, thì nó làm việc như thể có thêm một kế toán viên junior
    Tôi thấy custom MCP và Skill thực sự rất hữu ích

• Có cảm giác nhiều người dựng lên một bức tường cấu hình khổng lồ trước khi bắt đầu agentic coding
  Nhưng lúc đầu đúng ra nên bắt đầu với .claude trống và AGENTS.md để tự học cách điều khiển

  • Tôi thậm chí nghĩ chỉ nên dùng những skill do chính mình tạo
    Cài hàng loạt skill của người khác sẽ làm tăng tính bất định (nondeterminism) và còn lãng phí context window
    Ngoại lệ thì tôi chỉ khuyên cài thêm playwright-cli từ bên ngoài
  • Trong các nhóm lớn thì cần những guardrail (quy tắc) nhất quán
    Ví dụ, nếu cấu hình để kiểm tra điều kiện tiên quyết như quy tắc này thì sẽ ổn định hơn
    Có vẻ đội bảo mật cũng sẽ thích cách tiếp cận kiểu này
    Tôi cũng đã định nghĩa quy tắc để Claude không commit nếu không có chữ ký GPG
    Tuy vậy những quy tắc này không phải thứ cố định, mà phải tiếp tục tiến hóa
  • Bài viết này không hề ép mọi người phải dùng cấu hình khổng lồ
    Ngược lại, nó liên tục nhấn mạnh rằng hãy bắt đầu nhỏ và giữ ngắn gọn
    Ngay cả người mới cũng chỉ cần thêm vài dòng vào AGENTS.md là AI đã hiểu ý định của người dùng tốt hơn
    Thiết lập đơn giản giúp giảm mạnh sự cố hoạt động sai của AI
  • Tự mình xử lý code và xử lý dự án dùng chung theo nhóm là hai chuyện hoàn toàn khác nhau
    Khi mỗi lập trình viên dùng công cụ agentic thì chính cách cộng tác cũng thay đổi
  • Trước mắt chỉ cần dùng chế độ plan thôi là giải quyết được 90%
    Tôi nghĩ các cuộc thảo luận về cấu hình phức tạp thế này sẽ phần lớn biến mất trong vòng 1 năm khi mô hình tiếp tục tiến bộ

• Thư mục ~/.claude/projects mới thực sự là phần thú vị

• Tôi thấy càng ít cấu hình không cần thiết thì kết quả càng tốt
  Mọi người hay quy định hóa tài liệu quá mức, nhưng AI giống như một người lớn có năng lực nhưng đang căng thẳng
  Nếu đưa quá nhiều chỉ dẫn thì ngược lại nó còn trở nên ngốc hơn

• Bài này cho cảm giác được sinh ra hơn là từ trải nghiệm thực tế
  Claude.md nên ngắn, chỉ nên đưa vào vài liên kết
  Khi context tích tụ thì hiệu năng đi xuống, nên cần tách kế hoạch và triển khai rồi reset mỗi lần

  • Phần mở đầu giống văn phong của Claude quá nên tôi cũng nghĩ hay là hỏi thẳng Claude luôn cho rồi
  • Tôi thấy khó hiểu sự khác nhau giữa skill và command
    Không rõ có phải skill thì luôn nằm trong context còn command thì chỉ được gọi thủ công hay không

• Tôi ước mọi nhà cung cấp mô hình đều dùng chung một bộ file tiêu chuẩn
  Như vậy sẽ dễ chuyển đổi giữa Claude, Codex, Cursor và Opencode hơn

  • Nhưng tổ hợp giữa mô hình và harness ảnh hưởng rất lớn đến kết quả
    Cùng một prompt nhưng mỗi mô hình phản ứng khác nhau, nên tinh chỉnh prompt cũng phải khác nhau theo từng mô hình
  • Chỉ cần tạo một agents.md rồi để Claude.md tham chiếu tới nó, sau đó nối giữa các thư mục bằng symlink (sync) là được
    Không hoàn hảo nhưng hoạt động khá tốt
  • Bây giờ giống như thời kỳ đầu của trình duyệt. Chính việc chưa được chuẩn hóa đã tạo ra những đổi mới như AJAX
    Nên sự đa dạng hiện tại ngược lại là điều tích cực
  • Tạm thời tôi đang dùng dotagents by Sentry để giải quyết vấn đề này
  • Tôi không nghĩ các nhà cung cấp mô hình có lý do gì để cố làm cho việc chuyển đổi trở nên dễ dàng

• Tài liệu thay thế của Claude Fast rất hữu ích
  Tôi không hiểu vì sao phải ghét định nghĩa thư mục .claude
  Có thể để agent chính tự viết file, cập nhật lặp đi lặp lại và tạo thành một hệ thống tự cải thiện
  Giờ thì .claude tự sao chép, tự đánh giá và tự cập nhật — tôi không phải viết code mà là đang lập trình cho .claude

  • Tóm lại, CLAUDE.md không phải tài liệu đơn thuần mà là hệ điều hành của Claude
    Đó là cách định nghĩa hành vi, ủy quyền tri thức cho các skill và tạo ra một hệ thống tự cải thiện theo thời gian

• Rào cản mà nhiều người không biết là, dù để Claude sửa file đi nữa thì nếu không bảo nó đọc lại một cách rõ ràng nó sẽ không phản ánh thay đổi đó
  Ví dụ nếu vừa viết mới CLAUDE.md thì phải reload để Claude nhận nó như chỉ dẫn mới

• Thư mục ~/.claude/plans lưu các file kế hoạch được tạo khi chạy chế độ plan
  Tôi thường mở thư mục này để backup hoặc tham khảo

• Tôi xây dựng xoay quanh MCP server toàn cục và composite agent
  Mỗi MCP server định nghĩa một bộ công cụ, còn agent thì tự chủ làm việc trong đó
  .agent.md chỉ đơn giản là tài liệu mô tả các công cụ có sẵn, cấu hình phức tạp là không cần thiết
  Tôi thấy skill hay prompt tái sử dụng không có nhiều giá trị
  Mô hình vốn đã đủ thông minh, thứ cần thiết là định hướng (orientation)