CLAUDE.md Và Thư Mục .claude/: Cấu Hình Claude Code Từ A-Z (2026)

73% team kỹ thuật dùng AI coding tools hàng ngày, tăng từ 41% năm 2025 (Pragmatic Engineer Survey, 2026). Nhưng bao nhiêu người thực sự config để AI hiểu đúng project, quy tắc, và workflow của mình?

Nếu bạn đang dùng Claude Code là gì, câu trả lời nằm ở hai thứ: file CLAUDE.md và thư mục .claude/. Hai thứ này cùng nhau tạo nên toàn bộ hệ thống cấu hình của Claude Code, từ project instructions đến permissions, từ auto memory đến custom skills.

Bài này là hướng dẫn đầy đủ nhất về cả hai. Mình sẽ đi qua từng phần: CLAUDE.md là gì, thư mục .claude/ có gì, cấu hình settings.json ra sao, và cách kết hợp để làm việc hiệu quả nhất.

CLAUDE.md is a markdown file that Claude Code automatically reads at the start of every session, containing project instructions, coding conventions, and workflow rules. The .claude/ directory extends this with settings, path-specific rules, custom commands, and skills.

CLAUDE.md Là Gì?

CLAUDE.md là file markdown đặt ở root project, được Claude Code tự động đọc mỗi khi bạn bắt đầu phiên làm việc. Claude Code đang có hơn 110.000 GitHub stars (GitHub, 2026), và file chỉ dẫn này là cách bạn “dạy” nó hiểu codebase của mình mà không cần giải thích lại mỗi phiên.

Nghĩ đơn giản thế này: CLAUDE.md giống như bản mô tả công việc cho nhân viên mới. Tech stack, conventions, lệnh build, những điều cần tránh. Tất cả chỉ cần viết một lần, Claude Code sẽ nhớ mãi.

Vị trí và cách hoạt động

Bạn đặt file CLAUDE.md ở thư mục root của project, cùng cấp với .git/ hoặc package.json. Mỗi khi chạy claude trong terminal, file này được đọc tự động. Không cần cấu hình thêm, không cần plugin.

Ngoài vị trí mặc định, bạn còn có thể đặt ở .claude/CLAUDE.md nếu muốn tách biệt khỏi root. Cả hai vị trí đều được Claude Code nhận diện. Chỉ cần chọn một cách nhất quán.

So sánh với các AI coding tools khác

CLAUDE.md không phải khái niệm hoàn toàn mới. Các tools khác cũng có cơ chế tương tự, nhưng Claude Code hỗ trợ multi-level hierarchy và path-specific rules, hai thứ các tool khác chưa có.

Cấu Trúc Thư Mục .claude/ Như Thế Nào?

Thư mục .claude/ là nơi chứa toàn bộ cấu hình nâng cao của Claude Code, từ settings đến rules theo path, từ custom commands đến skills. Theo tài liệu chính thức, cấu trúc này được thiết kế để phân tách rõ ràng giữa cấu hình team (git committed) và cấu hình cá nhân (gitignored).

Đây là toàn bộ cấu trúc bạn cần biết:

project/
├── CLAUDE.md                    # Project instructions (team, git committed)
├── CLAUDE.local.md              # Personal prefs (gitignored)
├── .claude/
│   ├── CLAUDE.md                # Vị trí thay thế cho project instructions
│   ├── settings.json            # Team settings (git committed)
│   ├── settings.local.json      # Personal settings (gitignored)
│   ├── rules/                   # Path-specific rules
│   │   ├── frontend.md          # Rules cho src/components/**/*.tsx
│   │   └── testing.md           # Rules cho tests/**/*
│   ├── commands/                # Custom slash commands (deprecated)
│   │   └── deploy.md            # /deploy command
│   └── skills/                  # Custom skills (dùng SKILL.md files)
│       └── blog-publish.md      # /blog-publish skill

~/.claude/                       # Global user config
├── CLAUDE.md                    # Personal instructions (mọi project)
├── settings.json                # Global settings
├── rules/                       # Global rules
└── projects/<project>/memory/  # Auto-memory theo project
    ├── MEMORY.md                # Index (200 dòng đầu tự động load)
    └── topic-files.md           # Notes chi tiết (load on-demand)

Project vs User config

Có hai vị trí chính: trong project và trong home directory (~/.claude/). Project config áp dụng cho dự án cụ thể, được commit vào git để cả team dùng chung. User config áp dụng cho mọi project trên máy bạn, là preferences cá nhân.

Bạn nên tách bạch rõ ràng: những gì team cần biết thì để trong project, những gì chỉ bạn cần thì để trong ~/.claude/. Ví dụ, ~/.claude/CLAUDE.md có thể chứa “Luôn trả lời bằng tiếng Việt khi mình hỏi tiếng Việt” mà không cần cả team biết.

Local files và .gitignore

Các file .local được thiết kế để gitignore. Quy tắc đơn giản: nếu tên file có .local, đừng commit nó. Thêm vào .gitignore:

CLAUDE.local.md
.claude/settings.local.json

Bằng cách này, mỗi developer trên team có thể có preferences riêng mà không ảnh hưởng đến người khác. Đây là pattern mình dùng cho dự án ongboit.com, cực kỳ hiệu quả khi làm việc với người khác.

settings.json Cấu Hình Gì?

File .claude/settings.json là trung tâm cấu hình của Claude Code, gồm 8 sections chính. Theo tài liệu chính thức, đây là nơi bạn kiểm soát mọi thứ từ quyền truy cập file system đến hooks tự động hóa và environment variables.

1. permissions – Kiểm soát quyền truy cập

Section quan trọng nhất. Bạn định nghĩa Claude Code được phép làm gì qua ba loại: allow, deny, và ask. Hỗ trợ glob patterns để nhắm đúng file hoặc lệnh cụ thể.

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Write(src/**)",
      "Bash(npm run *)",
      "Bash(git *)"
    ],
    "deny": [
      "Write(.env*)",
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ],
    "ask": [
      "Write(package.json)",
      "Bash(git push *)"
    ]
  }
}

2. hooks – Tự động hóa theo sự kiện

Hooks cho phép chạy script tự động khi Claude Code thực hiện các hành động. Ví dụ: chạy linter sau khi write file, log mọi bash command để audit. Bốn hook events chính: PreToolUse, PostToolUse, PreCompact, PostCompact.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --fix"
          }
        ]
      }
    ]
  }
}

Đọc bài Claude Code Hooks để xem cách mình dùng hooks để tự động validate code sau mỗi lần Claude ghi file.

3. model – Chọn model mặc định

Bạn có thể chỉ định model nào được dùng mặc định. Hữu ích khi bạn muốn dùng model rẻ hơn cho tasks đơn giản, hoặc model mạnh hơn cho tasks phức tạp.

{
  "model": "claude-sonnet-4-6",
  "env": {
    "NODE_ENV": "development",
    "CUSTOM_API_KEY": "${MY_SECRET_KEY}"
  }
}

4. env – Environment variables

Thay vì export biến môi trường mỗi lần, bạn định nghĩa một lần trong settings. Claude Code sẽ inject tự động. Lưu ý: không đặt secrets trực tiếp trong settings.json nếu file này được commit vào git. Dùng settings.local.json cho secrets.

5-8. Các sections còn lại

Bốn Scope Settings Ưu Tiên Thế Nào?

Claude Code áp dụng settings theo thứ tự ưu tiên từ cao xuống thấp qua 4 scopes. Scope có độ ưu tiên cao hơn sẽ override scope thấp hơn. Theo tài liệu chính thức, cơ chế này cho phép tổ chức đặt policy bắt buộc ở tầng cao nhất mà developer không thể override.

Managed Policy dùng khi nào?

Managed Policy là scope dành cho enterprise và tổ chức. IT admin cài đặt ở cấp hệ thống, developer không thể override. Dùng khi bạn cần enforce security rules bắt buộc, ví dụ: “không bao giờ được phép đọc file *.pem” hoặc “không được push thẳng lên production branch.”

Với cá nhân và team nhỏ, bạn có thể bỏ qua scope này. Tập trung vào Project Shared (.claude/settings.json) và User Global (~/.claude/settings.json).

Thứ tự load CLAUDE.md

Tương tự settings, CLAUDE.md cũng có thứ tự load riêng. Claude Code đọc từ trên xuống dưới, nội dung đọc sau có thể override nội dung đọc trước:

1. Managed Policy CLAUDE.md (toàn tổ chức, bắt buộc)
2. CLAUDE.md từ các thư mục cha (đi từ thư mục hiện tại lên root)
3. Project root CLAUDE.md hoặc .claude/CLAUDE.md
4. CLAUDE.local.md (personal, gitignored)
5. ~/.claude/CLAUDE.md (user global)
6. Subdirectory CLAUDE.md (load on-demand khi Claude đọc file trong thư mục đó)

Cách Viết CLAUDE.md Hiệu Quả?

Một CLAUDE.md tốt gồm 5 phần chính, giữ dưới 200 dòng theo khuyến nghị của tài liệu chính thức Anthropic. Theo blog kỹ thuật của Anthropic, các team viết file chỉ dẫn rõ ràng thấy Claude Code thực hiện đúng yêu cầu từ lần đầu, giảm đáng kể số vòng chỉnh sửa.

Năm phần cần có:

• Project overview: 2-3 câu mô tả project là gì, mục tiêu chính.
• Tech stack và architecture: Liệt kê công nghệ, kiến trúc tổng thể.
• Commands: Lệnh build, test, lint, deploy. Claude Code sẽ dùng chính xác những lệnh này.
• Code conventions: Naming, file structure, import order, error handling.
• Gotchas: Những lỗi thường gặp, giới hạn kỹ thuật, điều cần tránh.

Template thực tế – Next.js project

# Project Overview
E-commerce platform. Next.js 14 + App Router. Vietnamese market.

## Tech Stack
- Next.js 14 (App Router, Server Components by default)
- TypeScript strict
- Tailwind CSS + shadcn/ui
- Supabase (auth + database)
- Vercel (deployment)

## Commands
```
npm run dev          # Dev server port 3000
npm run build        # Production build
npm run lint         # ESLint
npm run test         # Vitest
npm run db:migrate   # Supabase migrations
```

## Code Conventions
- Named exports only (no default exports)
- File naming: kebab-case
- Server Components by default; "use client" only when needed
- Error handling: Result pattern, never throw in lib/

## Gotchas
- Supabase RLS enabled, test với anon key
- Always use next/image, never raw <img>
- Vietnamese text: Unicode NFC normalization required

@import – Tách file khi cần

Khi file vượt quá 200 dòng, tách thành nhiều file và import chúng bằng cú pháp @path/to/file. Claude Code sẽ expand file được import vào context. Hỗ trợ tối đa 5 hops (import trong import trong import…) và đường dẫn tương đối tính từ file đang import.

# Project Overview
E-commerce platform. Next.js 14. Vietnamese market.

@docs/coding-standards.md
@docs/api-conventions.md
@docs/deployment-guide.md

Kỹ thuật này giúp giữ file chính ngắn gọn. Đặt nội dung theo chủ đề vào các file riêng, dễ maintain hơn khi cần cập nhật. Mình dùng cách này cho dự án ongboit.com, tách directives thành nhiều file .md nhỏ.

Best practices mình đúc kết được

Sau hàng trăm giờ dùng CLAUDE.md, mình nhận ra: phần Gotchas mang lại giá trị cao nhất. Đây là những lỗi bạn đã gặp và không muốn Claude lặp lại. Viết cụ thể: “Không dùng npm install --legacy-peer-deps vì lý do X” tốt hơn nhiều so với “Cẩn thận với npm install.”

Một rule quan trọng khác: HTML comments trong CLAUDE.md bị strip trước khi inject vào context. Bạn có thể dùng comments để note cho người đọc file mà không làm “bẩn” context của Claude.

Template CLAUDE.md mẫu (copy về dùng ngay)

Đây là CLAUDE.md thực tế mình dùng cho project ongboit.com. Không phải template lý thuyết, đây là file đang chạy production hàng ngày. Copy về, chỉnh lại Architecture và Commands cho project của bạn.

# CLAUDE.md

> You are the **orchestration layer**, intelligent glue between
> human intent (directives) and deterministic execution (scripts).

## Architecture

directives/*.md   → SOPs: the "what"
You (Claude)      → Parse intent, plan, call tools: the "how"
execution/*.py    → Deterministic scripts: the "do"

## Project Structure

project/
├── directives/          # SOPs in Markdown
├── execution/           # Deterministic scripts
│   ├── data/
│   ├── integrations/
│   └── utils/
├── mcp_servers/         # MCP server implementations
├── tests/
├── .tmp/                # Intermediate files (gitignored)
└── CLAUDE.md

## Commands

python -m pytest tests/              # Run all tests
python execution/main.py             # Run main entry point

## Decision Flow

1. Directive exists? → Follow it.
2. No directive? → Ask before creating one.
3. Existing tool? → Use it.
4. No tool? → Create minimal new tool.
5. Error? → Diagnose, fix, test, update directive.

## Key Principles

- Check for tools first before writing new code
- Self-anneal when things break
- Update directives as you learn
- Fail fast, recover gracefully
- Simple beats clever

## Human-in-the-Loop

Require approval: financial, data deletion, external comms
Auto-approve: read-only, internal tools, formatting

.claude/rules/ Dùng Khi Nào?

Thư mục .claude/rules/ cho phép tạo rules theo path pattern, chỉ load khi Claude làm việc với file phù hợp. Đây là cách hiệu quả nhất để quản lý rules trong project lớn, vì Claude không phải load mọi rules mọi lúc. Rules không có path sẽ load vô điều kiện khi khởi động.

Cú pháp YAML frontmatter

Mỗi file trong .claude/rules/ là một markdown file với YAML frontmatter ở đầu. Frontmatter định nghĩa rule áp dụng cho paths nào. Claude Code đọc frontmatter và chỉ inject rule vào context khi bạn đang làm việc với file phù hợp.

---
description: Rules cho React components
paths:
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
---

- Functional components only, no class components
- Props interface phải được export
- Mỗi component file cần có .test.tsx tương ứng
- Dùng Tailwind CSS, không inline styles
- Không import trực tiếp từ node_modules, dùng aliased paths

---
description: Rules cho test files
paths:
  - "tests/**/*"
  - "**/*.test.ts"
  - "**/*.spec.ts"
---

- Dùng describe/it pattern
- Mỗi test file test một module duy nhất
- Mock external dependencies, không call API thật
- Coverage tối thiểu 80% cho code mới

Rules không có paths

Nếu bạn không khai báo paths trong frontmatter, rule đó được load mọi lúc khi Claude Code khởi động. Dùng cho các quy tắc chung như “luôn dùng tiếng Việt trong comments” hoặc “không bao giờ commit credentials.”

Symlinks để chia sẻ rules

Một tính năng ít được biết đến: .claude/rules/ hỗ trợ symlinks. Nếu bạn có monorepo với nhiều packages, bạn có thể tạo rules ở một chỗ và symlink vào các packages khác. Giúp DRY hoàn toàn cho rules management. Đây là cách mình muốn thử khi mở rộng dự án ongboit.com.

Loại Trừ Files Khỏi Context Thế Nào?

Claude Code không có file .claudeignore riêng. Thay vào đó, có 3 cơ chế loại trừ files khỏi context để tiết kiệm token:

1. .gitignore (mặc định)

Claude Code tự động respect .gitignore khi dùng @ file picker. Setting respectGitignore mặc định là true. Các files như node_modules/, .env, dist/ tự động bị loại khỏi autocomplete.

2. permissions.deny trong settings.json

Đây là cách mạnh nhất để block Claude Code truy cập files nhạy cảm. Không chỉ ẩn khỏi picker mà còn deny read/write hoàn toàn:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)",
      "Read(./*.pem)",
      "Bash(rm -rf *)"
    ]
  }
}

3. claudeMdExcludes

Dùng khi bạn muốn Claude Code bỏ qua CLAUDE.md files từ thư mục khác (phổ biến trong monorepo):

{
  "claudeMdExcludes": [
    "**/other-team/CLAUDE.md",
    "**/legacy/.claude/rules/**"
  ]
}

Custom Commands Và Skills Để Ở Đâu?

Claude Code hỗ trợ hai cơ chế để tùy chỉnh hành vi: custom commands (deprecated, đang dần thay thế bởi skills) và skills. Với hơn 110.000 GitHub stars, cộng đồng đã tạo ra nhiều skills hữu ích chia sẻ công khai. Nắm rõ sự khác biệt giúp bạn chọn đúng công cụ.

commands/ – Legacy, đang deprecated

Thư mục .claude/commands/ chứa custom slash commands dạng markdown. Ví dụ, file deploy.md tạo command /deploy. Cơ chế này hoạt động nhưng đang được thay thế dần bởi skills. Nếu bạn đang bắt đầu mới, hãy dùng skills ngay.

skills/ – Hệ thống mới, nên dùng

Skills là phiên bản mạnh hơn của commands. Mỗi skill là một file SKILL.md trong .claude/skills/. Skills hỗ trợ cả project-level (.claude/skills/) và user-level (~/.claude/skills/).

# Blog Publish Skill

Skill để publish bài viết lên WordPress qua WP MCP.

## Trigger
/blog publish

## Steps
1. Validate HTML content (check headings, links, images)
2. Upload to WordPress as draft
3. Set RankMath focus keywords
4. Schedule publish 24h from now
5. Confirm with user before final publish

## Requirements
- WP MCP must be connected
- Post must have meta description (150-160 chars)
- At least 3 internal links

Đọc thêm về hệ thống skills của Claude Code và cách tự tạo skill cho workflow của bạn.

So sánh commands vs skills

Auto Memory Hoạt Động Thế Nào?

Auto memory là tính năng cho phép Claude Code tự ghi nhớ thông tin qua các phiên làm việc. Theo tài liệu chính thức Anthropic, 200 dòng đầu tiên hoặc 25KB của file MEMORY.md được load tự động khi bắt đầu phiên mới. Đây là cách Claude Code “nhớ” những gì bạn đã nói mà không cần nhắc lại.

Cơ chế hoạt động

Khi bạn nói “nhớ điều này” hoặc Claude nhận ra thông tin đáng nhớ, nó sẽ ghi vào MEMORY.md theo đường dẫn:

# Vị trí: ~/.claude/projects/<project-path>/memory/

# Ví dụ cho project D:projectsmy-app:
~/.claude/projects/D--projects-my-app/memory/
├── MEMORY.md           # Index file - 200 dòng đầu load tự động
├── architecture.md     # Notes về architecture (load on-demand)
└── decisions.md        # Architecture decisions (load on-demand)

MEMORY.md và topic files

Hệ thống memory gồm hai loại file. MEMORY.md là file index, chứa những thông tin quan trọng nhất. Topic files (các file .md khác trong cùng thư mục) chứa thông tin chi tiết, chỉ được load khi cần.

200 dòng đầu của MEMORY.md được load tự động mỗi phiên. Đây là con số quan trọng bạn cần nhớ: đặt thông tin quan trọng nhất vào 200 dòng đầu, thông tin ít dùng hơn vào topic files hoặc cuối MEMORY.md.

Quản lý memory hiệu quả

Mình thấy MEMORY.md phát huy tác dụng nhất khi dùng như một “index” thực sự. File MEMORY.md chỉ chứa danh sách các notes và link đến topic files, không chứa nội dung chi tiết. Cách này giúp 200 dòng đầu luôn có thông tin tổng quan đầy đủ, Claude có thể load topic file khi cần chi tiết. Nhiều người còn dùng Obsidian làm wiki bên cạnh auto memory để quản lý knowledge base project lớn hơn.

# Memory Index

## User Profile
- DevOps engineer, Vietnamese tech blogger
- Focused on Claude Code + n8n + AI automation
- Writes in Vietnamese, technical content

## Project Notes
- [Blog Workflow](feedback_blog_workflow.md) - Rules viết blog
- [Content Plan](project_plan.md) - Danh sách bài cần viết
- [WP Setup](wp_mcp_setup.md) - Cách kết nối WordPress

## Quick Facts
- Brand color: #4F6CF0
- Site: ongboit.com, Category Claude Code ID: 17
- Model for writing: Sonnet 4.6

Bật và tắt auto memory

Auto memory được bật mặc định. Để tắt, dùng lệnh /memory trong Claude Code hoặc thêm vào settings:

{
  "autoMemoryEnabled": false
}

Sub-agents cũng có thể maintain auto memory riêng. Đọc thêm về Claude Code sub-agents và quản lý memory và context trong các bài chuyên sâu hơn.

Lệnh /init Và /memory Làm Gì?

Hai lệnh này là điểm khởi đầu quan trọng nhất khi setup Claude Code cho project mới. /init phân tích codebase và tạo CLAUDE.md tự động. /memory cho phép bạn duyệt và quản lý auto memory. Theo Builder.io, /init là cách nhanh nhất để bắt đầu với dự án đã có sẵn code.

Dùng /init như thế nào?

1. 1 Mở terminal trong thư mục root của project.
2. 2 Chạy claude để khởi động Claude Code.
3. 3 Gõ /init và nhấn Enter.
4. 4 Claude phân tích package.json, pyproject.toml, Dockerfile, cấu trúc thư mục, rồi tạo CLAUDE.md.
5. 5 Review file được tạo, bổ sung phần Gotchas và team conventions.

Những gì /init không tự biết

/init tạo file cơ bản khá tốt. Nó nhận diện tech stack và cấu trúc thư mục rất nhanh. Nhưng có một số thứ nó không thể biết, bạn phải bổ sung thủ công:

• Naming conventions riêng của team
• Gotchas và lỗi đã gặp trong quá khứ
• Architecture decisions và lý do đằng sau
• Workflow riêng (“luôn tạo PR, không push thẳng main”)
• Thông tin business domain cụ thể

Mình thường dùng /init như điểm khởi đầu, rồi bổ sung thêm 30-50% nội dung từ kinh nghiệm thực tế. Phần Gotchas thường bị bỏ qua nhưng lại có giá trị cao nhất.

/memory – Duyệt và chỉnh sửa auto memory

Lệnh /memory mở giao diện để bạn xem toàn bộ notes trong auto memory của project hiện tại. Bạn có thể xem, chỉnh sửa, hoặc xóa từng note. Nếu Claude đã nhớ thứ gì đó sai, đây là nơi để sửa.

Đọc thêm về các slash commands quan trọng khác và cách kết hợp chúng trong workflow hàng ngày.

Câu Hỏi Thường Gặp

Kết Luận

Hệ thống cấu hình của Claude Code gồm nhiều lớp, mỗi lớp phục vụ một mục đích khác nhau. Nhưng đừng để bị overwhelm. Hầu hết developer chỉ cần ba thứ để bắt đầu tốt:

1. CLAUDE.md ở root project: 5 phần chính, dưới 200 dòng, viết cụ thể bằng imperative. Dùng /init để tạo bản đầu, customize phần Gotchas sau.
2. .claude/settings.json: Tối thiểu cần cấu hình section permissions để Claude Code biết được phép làm gì và không được làm gì.
3. Auto memory bật mặc định: Để nó chạy, dùng /memory định kỳ để dọn dẹp notes cũ.

Khi project lớn hơn, thêm .claude/rules/ cho path-specific rules, và .claude/skills/ cho workflow automation. Nhưng bắt đầu đơn giản, rồi mở rộng dần khi thấy cần.

Một điểm quan trọng cần hiểu: CLAUDE.md là “working memory” trong session hiện tại, nhưng không giữ được context giữa các sessions khác nhau. Nếu bạn cần bộ nhớ dài hạn thực sự, hãy xem workflow kết hợp Claude Code với NotebookLM: một lớp memory ngoài miễn phí, hoạt động song song với CLAUDE.md.

Nếu bạn chưa biết Claude Code là gì, đọc bài giới thiệu trước. Nếu bạn đã dùng Claude Code và muốn tiết kiệm token, xem bài về tối ưu token Claude Code. Còn nếu bạn muốn xây dựng workflow automation phức tạp hơn, roadmap Claude Code sẽ chỉ ra hướng tiếp theo.