Khám phá “Hộp đen” .claude: Bí mật tối ưu hóa Claude Code cho lập trình viên

Hầu hết các nhóm đã áp dụng AI dưới một hình thức nào đó, nhưng khoảng cách giữa “sử dụng AI” và “thu được lợi tức đầu tư có thể đo lường được từ AI” lớn hơn nhiều người tưởng. Postman đã công bố một phân tích tiết kiệm chi phí, xem xét sáu quy trình phát triển API phổ biến và so sánh sự khác biệt về thời gian và chi phí thực tế khi tích hợp AI vào nền tảng so với việc thêm AI từ bên ngoài.

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

Người dùng Claude Code thường coi thư mục .claude này 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 mình. Nhưng họ chưa bao giờ mở nó ra, chứ đừng nói đến việc hiểu chức năng của từng tập tin bên trong. Đó là một cơ hội bị bỏ lỡ. Thư mục .claude này là trung tâm điều khiển cách Claude hoạt động trong dự án của bạn.

Nó lưu trữ các hướng dẫn, lệnh tùy chỉnh, quy tắc quyền hạn và thậm chí cả bộ nhớ của Claude giữa các phiên làm việc. Khi bạn hiểu rõ dữ liệu nào nằm ở đâu và tại sao, bạn có thể 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ài 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 tin bạn sử dụng hàng ngày đến những tập tin bạn chỉ cần thiết lập một lần và không cần quan tâm nữa.

Hai thư mục, không phải một.

Trước khi đi sâu vào vấn đề, có một điều đáng lưu ý: thực tế có hai thư mục .claude, chứ không phải một. Tệp đầu tiên nằm trong dự án của bạn, và tệp 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 cam kết cấu hình đó lên Git. Mọi thành viên trong nhóm đều có cùng quy tắc, cùng lệnh tùy chỉnh và cùng chính sách quyền hạn.

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

CLAUDE.md: Hướng dẫn sử dụng của Claude

Đây là tập tin quan trọng nhất trong toàn bộ hệ thống. Khi bạn bắt đầu một phiên Claude Code, điều đầu tiên nó đọc là tập tin này CLAUDE.md. Nó tải tập tin này thẳng vào dấu nhắc hệ thống và ghi nhớ nó trong suốt cuộc hội thoại. Nói một cách đơn giản: bất cứ điều gì bạn viết CLAUDE.md, Claude sẽ theo dõi.

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

Tệp cấu hình CLAUDE.md ở thư mục gốc dự án là thiết lập phổ biến nhất. Nhưng bạn cũng có thể có một tệp cấu hình khác ~/.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ệp cấu hình bên trong các thư mục con cho các quy tắc cụ thể của từng thư mục. Claude đọc tất cả các tệp cấu hình này và kết hợp chúng lại.

Những gì thực sự thuộc vềCLAUDE.md

Đa số mọi người hoặc viết quá nhiều hoặc quá ít. Dưới đây là những gì hiệu quả.

• Viết:
  • Các lệnh biên dịch, kiểm thử và kiểm tra cú pháp (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”)
  • Những lỗi khó nhận biết (ví dụ: “Chế độ nghiêm ngặt của TypeScript đang bật, các biến không được sử dụng sẽ gây lỗi”)
  • Quy ước nhập khẩu, mẫu đặt tên, kiểu xử lý lỗi
  • Cấu trúc tập tin và thư mục cho các mô-đun chính
• Đừng viết:
  • Bất cứ thứ gì thuộc về cấu hình của trình kiểm tra cú pháp hoặc trình định dạng.
  • Bạn có thể truy cập trực tiếp vào tài liệu đầy đủ tại đây.
  • Các đoạn văn dài giải thích lý thuyết.

Hãy giữ CLAUDE.md số dòng dưới 200. Các tập tin dài hơn sẽ chiếm quá nhiều ngữ cảnh, và việc tuân thủ hướng dẫn của Claude thực tế sẽ giảm đi. Dưới đây là một ví dụ đơn giản nhưng hiệu quả:

# Project: Acme API

## Commands
npm run dev          # Start dev server
npm run test         # Run tests (Jest)
npm run lint         # ESLint + Prettier check
npm run build        # Production build

## Architecture
- Express REST API, Node 20
- PostgreSQL via Prisma ORM
- All handlers live in src/handlers/
- Shared types in src/types/

## Conventions
- Use zod for request validation in every handler
- Return shape is always { data, error }
- Never expose stack traces to the client
- Use the logger module, not console.log

## Watch out for
- Tests use a real local DB, not mocks. Run `npm run db:test:reset` first
- Strict TypeScript: no unused imports, ever

Chỉ khoảng 20 dòng thôi. Nó cung cấp cho Claude mọi thứ cần thiết để làm việc hiệu quả trong codebase này mà không cần phải liên tục giải thích thêm.

CLAUDE.local.md để thiết lập quyền ghi đè cá nhân

Đôi khi bạn có những sở thích riêng, không phải của 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ở các tập tin theo một mẫu cụ thể. Hãy tạo file này CLAUDE.local.md trong thư mục gốc của dự án. Claude sẽ đọc nó cùng với file chính CLAUDE.md, và nó sẽ tự động được đưa vào danh sách bỏ qua của Git, vì vậy những chỉnh sửa cá nhân của bạn sẽ không bao giờ xuất hiện trong kho lưu trữ.

Thư mục rules/: hướng dẫn dạng mô-đun có thể mở rộng

CLAUDE.md hoạt động rất tốt cho một dự án đơn lẻ. Nhưng một khi nhóm của bạn phát triển, bạn sẽ có một đoạn mã 300 dòng CLAUDE.md mà không ai bảo trì và mọi người đều bỏ qua. Và lúc này thư mục đó rules/ giải quyết vấn đề đó.

Mọi tập tin Markdown bên trong .claude/rules/ đều được tải cùng với tập tin của bạn CLAUDE.md một cách tự động. Thay vì một tập tin khổng lồ, bạn chia nhỏ các hướng dẫn theo từng vấn đề:

.claude/rules/
├── code-style.md
├── testing.md
├── api-conventions.md
└── security.md

Mỗi tập tin đều tập trung vào một chủ đề cụ thể và dễ dàng cập nhật. Thành viên nhóm chịu trách nhiệm về các quy ước API sẽ chỉnh sửa api-conventions.md. Người chịu trách nhiệm về các tiêu chuẩn kiểm thử sẽ chỉnh sửa testing.md. Không ai can thiệp vào công việc của người khác.

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

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---
# API Design Rules

- All handlers return { data, error } shape
- Use zod for request body validation
- Never expose internal error details to clients

Claude sẽ không tải tập tin này khi chỉnh sửa một thành phần React. Nó chỉ được tải khi hoạt động bên trong src/api/ hoặc src/handlers/. Các quy tắc không có trường paths sẽ được tải vô điều kiện, trong mỗi phiên. Đây là cách sắp xếp đúng khi bạn CLAUDE.md bắt đầu cảm thấy chật chội.

Thư mục commands/: các lệnh gạch chéo tùy chỉnh của bạn

Ngay từ khi cài đặt, Claude Code đã có sẵn các lệnh gạch chéo như /help và /compact. Thư mục commands/ này cho phép bạn thêm các lệnh của riêng mình. Mỗi tệp Markdown mà bạn sao chép vào .claude/commands/ đều trở thành một lệnh gạch chéo.

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

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

---
description: Review the current branch diff for issues before merging
---
## Changes to Review

!`git diff --name-only main...HEAD`

## Detailed Diff

!`git diff main...HEAD`

Review the above changes for:
1. Code quality issues
2. Security vulnerabilities
3. Missing test coverage
4. Performance concerns

Give specific, actionable feedback per file.

Giờ hãy chạy lệnh này /project:review trong Claude Code và nó sẽ tự động chèn kết quả khác biệt thực sự của git vào dấu nhắc trước khi Claude nhìn thấy. Cú pháp !`xxx` chạy các lệnh shell và nhúng kết quả đầu ra. Đó là điều làm cho các lệnh này thực sự hữu ích thay vì chỉ là văn bản được lưu trữ.

Truyền tham số cho lệnh

Dùng $ARGUMENTS để truyền văn bản sau tên lệnh:

---
description: Investigate and fix a GitHub issue
argument-hint: [issue-number]
---
Look at issue #$ARGUMENTS in this repo.

!`gh issue view $ARGUMENTS`

Understand the bug, trace it to the root cause, fix it, and write a
test that would have caught it.

Việc chạy /project:fix-issue 234 các nguồn cấp dữ liệu sẽ đưa nội dung của sự cố 234 trực tiếp vào lời nhắc.

Lệnh cá nhân so với lệnh dự án

Các lệnh dự án trong thư mục này .claude/commands/ được lưu lại và chia sẻ với nhóm của bạn. Đối với các lệnh bạn muốn sử dụng ở mọi nơi bất kể dự án nào, hãy đặt chúng vào thư mục này ~/.claude/commands/. Những lệnh đó sẽ hiển thị dưới dạng `<tên tệp>` /user:command-name thay vì `<tên tệp>`.

Một công cụ cá nhân hữu ích: hỗ trợ cuộc họp giao ban hàng ngày, lệnh tạo thông báo commit theo quy ước của bạn, hoặc quét bảo mật nhanh.

Thư mục skills/: các quy trình làm việc có thể tái sử dụng theo yêu cầu

Giờ bạn đã biết cách thức hoạt động của các lệnh. Các kỹ năng thoạt nhìn có vẻ giống nhau, nhưng cơ chế kích hoạt lại khác biệt về bản chất. Dưới đây là điểm khác biệt trước khi chúng ta đi sâu hơn:

Skill (Kỹ năng) là các quy trình công việc mà Claude có thể tự động kích hoạt, mà không cần bạn gõ lệnh, khi nhiệm vụ phù hợp với mô tả của kỹ năng. Lệnh thì chờ bạn. Kỹ năng theo dõi cuộc hội thoại và hành động khi thời điểm thích hợp.

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

.claude/skills/
├── security-review/
│   ├── SKILL.md
│   └── DETAILED_GUIDE.md
└── deploy/
    ├── SKILL.md
    └── templates/
        └── release-notes.md

SKILL.md sử dụng YAML frontmatter để mô tả khi nào nên sử dụng nó:

---
name: security-review
description: Comprehensive security audit. Use when reviewing code for
  vulnerabilities, before deployments, or when the user mentions security.
allowed-tools: Read, Grep, Glob
---
Analyze the codebase for security vulnerabilities:

1. SQL injection and XSS risks
2. Exposed credentials or secrets
3. Insecure configurations
4. Authentication and authorization gaps

Report findings with severity ratings and specific remediation steps.
Reference @DETAILED_GUIDE.md for our security standards.

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

Điểm khác biệt chính so với lệnh: kỹ năng có thể đóng gói các tệp hỗ trợ đi kèm. Tài DETAILED_GUIDE.md liệu tham khảo ở trên dẫn đến một tài liệu chi tiết nằm ngay bên cạnh SKILL.md. Lệnh là các tệp riêng lẻ. Kỹ năng là các gói.

Các kỹ năng cá nhân được tích hợp ~/.claude/skills/ và vận dụng trong tất cả các dự án của bạn.

Thư mục agents/: Tác nhân cho các tác vụ chuyên biệt

Khi một tác vụ đủ phức tạp để cần đến một chuyên gia riêng biệt, bạn có thể định nghĩa một vai trò tác nhân phụ trong .claude/agents/. Mỗi tác nhân là một tệp markdown với lời nhắc hệ thống riêng, quyền truy cập công cụ và tùy chọn mô hình riêng:

.claude/agents/
├── code-reviewer.md
└── security-auditor.md

Đây là hình code-reviewer.md dạng của nó:

---
name: code-reviewer
description: Expert code reviewer. Use PROACTIVELY when reviewing PRs,
  checking for bugs, or validating implementations before merging.
model: sonnet
tools: Read, Grep, Glob
---
You are a senior code reviewer with a focus on correctness and maintainability.

When reviewing code:
- Flag bugs, not just style issues
- Suggest specific fixes, not vague improvements
- Check for edge cases and error handling gaps
- Note performance concerns only when they matter at scale

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

Trường công cụ giới hạn những gì tác nhân có thể làm. Một kiểm toán viên bảo mật chỉ cần các công cụ Read, Grep và Glob. Nó không được phép ghi vào tệp. Sự hạn chế này là có chủ ý và cần đượ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 tác vụ cụ thể. Haiku xử lý tốt hầu hết các thao tác tìm kiếm 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 chuyên viên cá nhân sẽ trực tiếp tham gia ~/.claude/agents/ và sẵn sàng hỗ trợ tại tất cả các dự án.

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

Tệp tin settings.json bên trong .claude/ kiểm soát những gì Claude được phép 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 tin hoàn chỉnh trông như thế này:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Dòng lệnh này $schema cho phép tự động hoàn thành và xác thực trực tiếp trong VS Code hoặc Cursor. Luôn luôn thêm dòng này vào.

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, một danh sách cho phép tốt sẽ bao gồm:

• Bash(npm run *) hoặc Bash(make *) như vậy Claude có thể chạy các tập lệnh của bạn một cách tự do.
• Bash(git *) đối với các lệnh git chỉ đọc
• Đọc, ghi, chỉnh sửa, tìm kiếm ký tự đại diện (glob), tìm kiếm bằng lệnh grep để thao tác với tệp.

Danh sách cấm chứa các lệnh bị chặn hoàn toàn, bất kể điều gì xảy ra. Một danh sách cấm hợp lý sẽ chặn:

• Các lệnh shell phá hoại như rm -rf
• Các lệnh mạng trực tiếp như curl
• Các tập tin nhạy cảm như .env và bất cứ thứ gì trong secrets/

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

Tuy nhiên, bạn cũng có thể sử dụng nó settings.local.json cho các thiết lập ghi đè cá nhân. Ý tưởng tương tự như CLAUDE.local.md việc tạo tệp này .claude/settings.local.json cho các thay đổi quyền mà bạn không muốn commit. Tệp này sẽ tự động được gitignored.

Thư mục ~/.claude/ toàn cầu

Bạn không thường xuyên tương tác với thư mục này, nhưng biết được nội dung bên trong cũng rất hữu ích.

• ~/.claude/CLAUDE.md: Tải dữ liệu vào mọi phiên Claude Code, trên tất cả các dự án của bạn. Đây là nơi tốt để ghi lại các nguyên tắc lập trình cá nhân, phong cách ưa thích hoặc bất cứ điều gì bạn muốn Claude ghi nhớ, bất kể bạn đang ở trong kho lưu trữ nào.
• ~/.claude/projects/: Claude Code lưu trữ bản ghi phiên làm việc và bộ nhớ tự động cho mỗi dự án. Nó tự động lưu ghi chú trong quá trình hoạt động: các lệnh được phát hiện, các mẫu được quan sát và những hiểu biết về kiến ​​trúc. Những ghi chú này được lưu giữ xuyên suốt các phiên làm việc. Bạn có thể duyệt và chỉnh sửa chúng bằng lệnh /memory.
• ~/.claude/commands/ và ~/.claude/skills/: Nắm vững các chỉ huy và kỹ năng cá nhân có thể sử dụng trong tất cả các dự án.

Thông thường bạn không cần phải tự quản lý những thứ này. Nhưng việc biết chúng tồn tại sẽ rất hữu ích khi Claude dường như “nhớ” điều gì đó mà bạn chưa từng nói với nó, hoặc khi bạn muốn xóa bộ nhớ tự động của một dự án và bắt đầu lại từ đầu.

Toàn cảnh

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

your-project/
├── CLAUDE.md                  # Team instructions (committed)
├── CLAUDE.local.md            # Your personal overrides (gitignored)
│
└── .claude/
    ├── settings.json          # Permissions + config (committed)
    ├── settings.local.json    # Personal permission overrides (gitignored)
    │
    ├── commands/              # Custom slash commands
    │   ├── review.md          # → /project:review
    │   ├── fix-issue.md       # → /project:fix-issue
    │   └── deploy.md          # → /project:deploy
    │
    ├── rules/                 # Modular instruction files
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    │
    ├── skills/                # Auto-invoked workflows
    │   ├── security-review/
    │   │   └── SKILL.md
    │   └── deploy/
    │       └── SKILL.md
    │
    └── agents/                # Specialized subagent personas
        ├── code-reviewer.md
        └── security-auditor.md

~/.claude/
├── CLAUDE.md                  # Your global instructions
├── settings.json              # Your global settings
├── commands/                  # Your personal commands (all projects)
├── skills/                    # Your personal skills (all projects)
├── agents/                    # Your personal agents (all projects)
└── projects/                  # Session history + auto-memory

Một thiết lập thực tế để bắt đầu

Nếu bạn mới bắt đầu, đây là một lộ trình học tập hiệu quả.

• Bước 1. Chạy /init bên trong Claude Code. Nó sẽ tạo ra một mẫu khởi đầu CLAUDE.md bằng cách đọc dự án của bạn. Chỉnh sửa nó sao cho chỉ còn lại những phần cần thiết.
• Bước 2. Thêm .claude/settings.json các quy tắc cho phép/từ chối phù hợp với hệ thống của bạn. Tối thiểu, hãy cho phép các lệnh chạy và từ chối việc đọc tệp .env.
• Bước 3. Tạo một hoặc hai lệnh cho các quy trình công việc bạn thực hiện thường xuyên nhất. Rà soát mã và sửa lỗi là những điểm khởi đầu tốt.
• Bước 4. Khi dự án của bạn phát triển và tệp CLAUDE.md trở nên quá tải, hãy bắt đầu chia các hướng dẫn thành .claude/rules/ các tệp riêng biệt. Giới hạn phạm vi của chúng theo đường dẫn khi cần thiết.
• Bước 5. Thêm phần ghi chú ~/.claude/CLAUDE.md với các tùy chọn cá nhân của bạn. Ví dụ như “luôn viết kiểu dữ liệu trước khi viết phần triển khai” hoặc “ưu tiên các mẫu lập trình hàm hơn các mẫu lập trình dựa trên lớp“.

Thực ra, đó là tất cả những gì bạn cần cho 95% dự án. Kỹ năng và chuyên gia chỉ cần thiết khi bạn có các quy trình làm việc phức tạp, lặp đi lặp lại cần được đóng gói lại.

Thông tin quan trọng

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

CLAUDE.md: Đây là tập tin có tầm ảnh hưởng lớn nhất. Hãy ưu tiên xử lý tập tin này trước. Mọi thứ khác chỉ là tối ưu hóa.

Hãy bắt đầu từ những bước nhỏ, tinh chỉnh dần dần và coi nó như bất kỳ phần cơ sở hạ tầng nào khác trong dự án của bạn: thứ sẽ mang lại lợi ích mỗi ngày một khi được thiết lập đúng cách.

Nguồn: Anatomy of the .claude/ Folder