Claude Code từ zero đến thành thạo · Phần 4 — CLAUDE.md, auto memory và thư mục .claude

Mỗi phiên Claude Code bắt đầu với một context window trắng. Hai cơ chế mang kiến thức đi qua ranh giới đó:

• CLAUDE.md — chỉ dẫn bạn viết để cấp ngữ cảnh lâu dài
• Auto memory — ghi chú Claude tự viết dựa trên những lần bạn sửa lưng nó

Cả hai đều nạp ở đầu mọi hội thoại. Và cả hai đều là context, không phải cấu hình được cưỡng chế — Claude đọc và cố làm theo, nhưng không có gì đảm bảo tuân thủ tuyệt đối. Muốn chặn một hành động bất kể Claude nghĩ gì, bạn cần PreToolUse hook (phần 13), không phải một dòng trong CLAUDE.md.

Chỉ dẫn càng cụ thể và càng ngắn gọn thì Claude càng làm theo nhất quán. Đây không phải lời khuyên chung chung — nó là hệ quả trực tiếp của việc CLAUDE.md cạnh tranh chỗ với phần còn lại của context window.

CLAUDE.md khác auto memory ở đâu

	CLAUDE.md	Auto memory
Ai viết	Bạn	Claude
Chứa gì	Chỉ dẫn và luật	Điều học được và pattern
Phạm vi	Project, user, hoặc tổ chức	Theo repository, dùng chung giữa các worktree
Nạp vào	Mọi phiên	Mọi phiên (200 dòng hoặc 25KB đầu)
Dùng cho	Coding standard, workflow, kiến trúc project	Lệnh build, hiểu biết khi debug, sở thích Claude tự phát hiện

Dùng CLAUDE.md khi bạn muốn định hướng hành vi của Claude. Auto memory để Claude tự học từ những lần bạn sửa lưng mà bạn không phải gõ gì.

---

Khi nào nên thêm vào CLAUDE.md

Coi CLAUDE.md là nơi bạn ghi lại thứ mà nếu không ghi thì bạn sẽ phải giải thích lại. Thêm vào khi:

• Claude mắc cùng một lỗi lần thứ hai
• Code review bắt được thứ mà lẽ ra Claude phải biết về codebase này
• Bạn gõ lại đúng câu chỉnh mà bạn đã gõ ở phiên trước
• Một đồng nghiệp mới sẽ cần đúng ngữ cảnh đó để làm việc được

Giữ nó ở mức sự thật Claude cần nắm trong mọi phiên: lệnh build, convention, bố cục project, các luật dạng “luôn luôn làm X”.

Nếu một mục là quy trình nhiều bước, hoặc chỉ liên quan tới một phần của codebase, hãy chuyển nó thành skill (phần 12) hoặc path-scoped rule thay vì nhét vào CLAUDE.md.

Đặt CLAUDE.md ở đâu

Bảng dưới xếp theo thứ tự nạp, từ phạm vi rộng nhất tới cụ thể nhất — nên chỉ dẫn cấp project xuất hiện trong context sau chỉ dẫn cấp user.

Phạm vi	Vị trí	Dùng cho	Chia sẻ với
Managed policy	macOS /Library/Application Support/ClaudeCode/CLAUDE.md; Linux và WSL /etc/claude-code/CLAUDE.md; Windows C:\Program Files\ClaudeCode\CLAUDE.md	Chỉ dẫn toàn tổ chức do IT/DevOps quản lý	Mọi user trong tổ chức
User instructions	~/.claude/CLAUDE.md	Sở thích cá nhân cho mọi project	Chỉ bạn, mọi project
Project instructions	./CLAUDE.md hoặc ./.claude/CLAUDE.md	Chỉ dẫn dùng chung cả team	Team, qua source control
Local instructions	./CLAUDE.local.md	Sở thích cá nhân riêng project này; nhớ cho vào .gitignore	Chỉ bạn, project hiện tại

CLAUDE.md và CLAUDE.local.md ở các thư mục cha của thư mục làm việc được nạp đầy đủ lúc khởi động. File trong thư mục con nạp theo nhu cầu, khi Claude đọc file trong thư mục đó.

Mẹo khởi đầu: chạy /init để Claude tự sinh một CLAUDE.md — nó phân tích codebase rồi tạo file với lệnh build, cách chạy test và convention nó phát hiện được. Nếu file đã tồn tại, /init đề xuất cải thiện chứ không ghi đè.

Viết chỉ dẫn cho hiệu quả

Vì CLAUDE.md nạp vào context window ở đầu mọi phiên, cách bạn viết ảnh hưởng trực tiếp tới mức độ Claude làm theo.

Kích thước — nhắm dưới 200 dòng mỗi file. File dài hơn tốn context và giảm mức tuân thủ. Đang phình to thì dùng path-scoped rule để chỉ nạp khi Claude làm việc với file khớp.

Cấu trúc — dùng header và bullet markdown để nhóm chỉ dẫn liên quan. Claude quét cấu trúc giống người đọc: mục có tổ chức dễ theo hơn đoạn văn dày đặc.

Tính cụ thể — viết chỉ dẫn đủ cụ thể để kiểm chứng được:

• “Use 2-space indentation” thay vì “Format code properly”
• “Run npm test before committing” thay vì “Test your changes”
• “API handlers live in src/api/handlers/” thay vì “Keep files organized”

Tính nhất quán — nếu hai luật mâu thuẫn nhau, Claude có thể chọn tuỳ tiện một cái. Rà lại CLAUDE.md, các CLAUDE.md lồng trong thư mục con, và .claude/rules/ định kỳ để bỏ chỉ dẫn cũ hoặc xung đột.

Import file khác

CLAUDE.md import được file khác bằng cú pháp @path/to/import. File được import mở rộng và nạp vào context lúc khởi động cùng với file gọi nó.

Cả đường dẫn tương đối lẫn tuyệt đối đều được; đường dẫn tương đối tính từ file chứa lệnh import, không phải thư mục làm việc. Import lồng nhau được, tối đa bốn tầng.

Việc phân tích import bỏ qua code span và code fence. Muốn nhắc một đường dẫn mà không import nó thì bọc backtick.

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

Cảnh báo bảo mật: một import trong file memory cấp project là external khi đường dẫn của nó giải ra ngoài thư mục làm việc — ví dụ import từ thư mục home. Lần đầu gặp import external, Claude Code hiện hộp thoại duyệt liệt kê các file đó. Cơ chế này bảo vệ bạn khỏi file do người khác commit vào project dùng chung. Import trong file memory cấp user thì nạp thẳng, vì đó là file bạn tự viết.

Nếu bạn làm việc trên nhiều git worktree của cùng repo, CLAUDE.local.md bị gitignore chỉ tồn tại ở worktree bạn tạo nó. Muốn dùng chung thì import một file từ thư mục home:

# Individual Preferences
- @~/.claude/my-project-instructions.md

Còn AGENTS.md thì sao

Claude Code đọc CLAUDE.md, không đọc AGENTS.md. Nếu repo của bạn đã dùng AGENTS.md cho các coding agent khác, tạo một CLAUDE.md import nó để cả hai công cụ đọc cùng một nguồn mà không phải nhân đôi nội dung:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Không cần thêm nội dung riêng cho Claude thì dùng symlink cũng được:

ln -s AGENTS.md CLAUDE.md

Trên Windows, tạo symlink cần quyền Administrator hoặc Developer Mode — dùng cách import @AGENTS.md thay thế.

Thứ tự nạp CLAUDE.md

Claude Code đi ngược lên cây thư mục từ thư mục làm việc hiện tại, kiểm tra CLAUDE.md và CLAUDE.local.md ở từng cấp. Chạy Claude Code trong foo/bar/ thì nó nạp foo/bar/CLAUDE.md, foo/CLAUDE.md, và các CLAUDE.local.md đi kèm.

Mọi file tìm được đều được nối vào context chứ không ghi đè lẫn nhau. Thứ tự đi từ gốc filesystem xuống thư mục làm việc — nên foo/CLAUDE.md xuất hiện trước foo/bar/CLAUDE.md, và chỉ dẫn gần chỗ bạn khởi động được đọc sau cùng. Trong mỗi thư mục, CLAUDE.local.md nối sau CLAUDE.md.

Hai chi tiết ít người biết:

• HTML comment cấp block dạng <!-- maintainer notes --> bị loại bỏ trước khi nội dung vào context của Claude. Dùng chúng để để lại ghi chú cho người bảo trì mà không tốn token. Comment bên trong code block thì được giữ.
• Flag --add-dir không nạp CLAUDE.md của thư mục thêm vào theo mặc định. Muốn nạp thì set biến môi trường CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1.

---

Tổ chức chỉ dẫn bằng .claude/rules/

Với project lớn, chia chỉ dẫn thành nhiều file trong .claude/rules/. Cách này giữ chỉ dẫn ở dạng module và dễ bảo trì cho team. Quan trọng hơn: rule gắn được vào path cụ thể, nên chúng chỉ nạp vào context khi Claude làm việc với file khớp — giảm nhiễu và tiết kiệm context.

your-project/
├── .claude/
│   ├── CLAUDE.md           # Chỉ dẫn chính của project
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── security.md

Mọi file .md được tìm đệ quy, nên bạn tổ chức thành thư mục con như frontend/ hay backend/ cũng được. Rule không có frontmatter paths được nạp lúc khởi động với cùng độ ưu tiên như .claude/CLAUDE.md.

Rule gắn theo path

---
paths:
  - 'src/api/**/*.ts'
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

Rule gắn path kích hoạt khi Claude đọc file khớp pattern, không phải ở mọi lần dùng tool.

Pattern	Khớp với
**/*.ts	Mọi file TypeScript ở bất kỳ thư mục nào
src/**/*	Mọi file dưới src/
*.md	File markdown ở gốc project
src/components/*.tsx	React component trong một thư mục cụ thể

Khai nhiều pattern được, và dùng brace expansion để khớp nhiều đuôi trong một pattern:

---
paths:
  - 'src/**/*.{ts,tsx}'
  - 'lib/**/*.ts'
  - 'tests/**/*.test.ts'
---

Mỗi nhóm brace nhân lên số pattern sau khi mở rộng. Để giữ giới hạn, toàn bộ danh sách paths của một rule chia chung một ngân sách 1.000 pattern và 4 MiB; pattern không có brace không tính vào ngân sách này.

Một lưu ý về cú pháp glob: dấu [ được hiểu là mở đầu bracket expression như [abc]. Pattern có [ không đọc được thành bracket expression, ví dụ photos [2024/**, là pattern không hợp lệ — nó không khớp file nào, còn các pattern khác của rule vẫn chạy. Muốn khớp dấu ngoặc vuông theo nghĩa đen thì escape: photos \[2024/**.

Rule cấp user và chia sẻ giữa project

Rule cá nhân trong ~/.claude/rules/ áp dụng cho mọi project trên máy bạn. Chúng được nạp trước rule cấp project, nên rule project có độ ưu tiên cao hơn.

Thư mục .claude/rules/ hỗ trợ symlink, nên bạn duy trì được một bộ rule dùng chung rồi link vào nhiều project. Symlink vòng tròn được phát hiện và xử lý an toàn:

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

Quản lý cho team lớn

Tổ chức triển khai được một CLAUDE.md quản lý tập trung áp cho mọi user trên máy — file này không thể bị loại trừ bởi settings cá nhân. Khoá claudeMd cho phép đặt thẳng nội dung vào managed-settings.json thay vì triển khai file riêng.

Ranh giới giữa managed settings và managed CLAUDE.md đáng nhớ:

Vấn đề	Cấu hình ở
Chặn tool, lệnh hoặc path cụ thể	Managed settings: permissions.deny
Cưỡng chế sandbox isolation	Managed settings: sandbox.enabled
Biến môi trường và routing API provider	Managed settings: env
Cách đăng nhập và giới hạn tổ chức	Managed settings: forceLoginMethod, forceLoginOrgUUID
Hướng dẫn code style và chất lượng	Managed CLAUDE.md
Nhắc nhở về xử lý dữ liệu và tuân thủ	Managed CLAUDE.md
Chỉ dẫn hành vi cho Claude	Managed CLAUDE.md

Nguyên tắc: settings là cưỡng chế kỹ thuật, CLAUDE.md là định hướng hành vi.

Ở monorepo lớn, CLAUDE.md của các team khác trên đường đi lên có thể bị nhặt vào. Dùng claudeMdExcludes để bỏ chúng theo path hoặc glob:

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

---

Auto memory

Auto memory cho Claude tích luỹ kiến thức qua các phiên mà bạn không phải viết gì: lệnh build, hiểu biết khi debug, ghi chú kiến trúc, sở thích code style, thói quen workflow. Claude không lưu gì đó ở mọi phiên — nó tự quyết thứ đáng nhớ dựa trên việc thông tin đó có hữu ích cho cuộc hội thoại tương lai hay không.

Bật/tắt: auto memory bật mặc định. Mở /memory trong phiên để bật tắt, nó lưu autoMemoryEnabled vào settings user. Tắt cho riêng một project thì đặt trong settings của project đó:

{
  "autoMemoryEnabled": false
}

Tắt qua biến môi trường: CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Vị trí lưu: mỗi project có thư mục memory riêng ở ~/.claude/projects/<project>/memory/. Phần <project> suy ra từ git repository, nên mọi worktree và thư mục con trong cùng repo dùng chung một thư mục auto memory. Ngoài git repo thì lấy project root.

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Index ngắn gọn, nạp vào mọi phiên
├── debugging.md       # Ghi chú chi tiết về pattern debug
├── api-conventions.md # Quyết định thiết kế API
└── ...

Cách hoạt động: 200 dòng đầu của MEMORY.md, hoặc 25KB đầu — tuỳ cái nào tới trước — được nạp ở đầu mọi hội thoại. Phần vượt ngưỡng không được nạp. Claude giữ MEMORY.md ngắn bằng cách chuyển ghi chú chi tiết sang file chủ đề riêng; file chủ đề như debugging.md không nạp lúc khởi động mà Claude đọc theo nhu cầu.

Sau khi Claude ghi vào MEMORY.md, Claude Code đo file so với hai giới hạn trên. Gần chạm giới hạn thì nó nhắc Claude rút gọn; vượt giới hạn thì lệnh ghi vẫn thành công nhưng Claude Code trả về lỗi bắt Claude viết lại index, vì mọi thứ quá giới hạn sẽ bị bỏ ở lần nạp sau.

Giới hạn này chỉ áp cho MEMORY.md. CLAUDE.md luôn được nạp đầy đủ bất kể dài bao nhiêu — dù file ngắn vẫn cho mức tuân thủ tốt hơn.

Auto memory là local theo máy, không đồng bộ giữa các máy hay môi trường cloud. Nó cũng được loại trừ khỏi vòng dọn dẹp theo cleanupPeriodDays, nên MEMORY.md và file chủ đề tồn tại tới khi bạn hoặc Claude sửa/xoá chúng.

Auto memory của cuộc hội thoại chính không nạp vào subagent; ngoại lệ là fork, vì fork kế thừa hội thoại và system prompt của cha.

Xem và sửa: chạy /memory để duyệt và mở file memory ngay trong phiên. Toàn bộ là markdown thuần, bạn sửa hay xoá tuỳ ý. Khi bạn bảo Claude “always use pnpm, not npm”, nó lưu vào auto memory; muốn vào CLAUDE.md thì nói thẳng “add this to CLAUDE.md”.

---

Bản đồ thư mục .claude

Đây là bảng tra cứu bạn sẽ quay lại nhiều lần. Cột Commit cho biết file có nên đưa vào source control không.

File	Phạm vi	Commit	Làm gì
CLAUDE.md	Project và global	✓	Chỉ dẫn nạp mọi phiên
rules/*.md	Project và global	✓	Chỉ dẫn theo chủ đề, tuỳ chọn gắn path
settings.json	Project và global	✓	Permission, hook, env var, model mặc định
settings.local.json	Chỉ project		Override cá nhân, bị gitignore khi Claude Code ghi vào
.mcp.json	Chỉ project	✓	MCP server dùng chung cả team
.worktreeinclude	Chỉ project	✓	File bị gitignore cần copy vào worktree mới
skills/<name>/SKILL.md	Project và global	✓	Prompt tái dùng, gọi bằng /name hoặc Claude tự gọi
commands/*.md	Project và global	✓	Prompt một file; cùng cơ chế với skill
output-styles/*.md	Project và global	✓	Mục system prompt tuỳ biến
agents/*.md	Project và global	✓	Định nghĩa subagent với prompt và tool riêng
workflows/*.js	Project và global	✓	Script dynamic workflow; mỗi file thành một lệnh /name
agent-memory/<name>/	Project và global	✓	Memory bền vững cho subagent
~/.claude.json	Chỉ global		App state, OAuth, toggle UI, MCP server cá nhân
projects/<project>/memory/	Chỉ global		Auto memory
keybindings.json	Chỉ global		Phím tắt tuỳ biến
themes/*.json	Chỉ global		Theme màu tuỳ biến

Ba file nằm ở gốc project chứ không trong .claude/: CLAUDE.md, .mcp.json, .worktreeinclude.

Muốn đổi gì thì sửa file nào

Bạn muốn	Sửa
Cấp ngữ cảnh và convention cho project	CLAUDE.md
Cho phép hoặc chặn tool call cụ thể	settings.json mục permissions hoặc hooks
Chạy script trước/sau tool call	settings.json mục hooks
Đặt biến môi trường cho phiên	settings.json mục env
Giữ override cá nhân ngoài git	settings.local.json
Thêm prompt hoặc năng lực gọi bằng /name	skills/<name>/SKILL.md
Định nghĩa subagent có tool riêng	agents/*.md
Điều phối nhiều subagent bằng script	workflows/*.js
Nối tool ngoài qua MCP	.mcp.json
Đổi cách Claude định dạng phản hồi	output-styles/*.md

Thứ tự ưu tiên khi nhiều nguồn đụng nhau: managed settings do tổ chức triển khai thắng tất cả (trừ vài ngoại lệ hẹp), rồi tới CLI flag như --permission-mode hay --settings cho phiên đó, rồi mới tới các file settings.

Dữ liệu Claude Code ghi ra khi bạn làm việc

Ngoài phần cấu hình bạn tự viết, ~/.claude còn chứa dữ liệu sinh ra trong lúc chạy. Toàn bộ là plaintext. Bất cứ thứ gì đi qua một tool đều nằm lại trong transcript trên đĩa: nội dung file, output lệnh, văn bản bạn dán vào.

Những đường dẫn này bị dọn tự động khi cũ hơn cleanupPeriodDays (mặc định 30 ngày, tối thiểu 1):

Đường dẫn dưới ~/.claude/	Nội dung
projects/<project>/<session>.jsonl	Transcript đầy đủ: mọi tin nhắn, tool call, kết quả tool
projects/<project>/<session>/subagents/	Transcript của subagent
projects/<project>/<session>/tool-results/	Output tool lớn được đẩy ra file riêng
file-history/<session>/	Ảnh chụp file trước khi sửa, dùng cho checkpoint restore
plans/	File plan viết trong plan mode
debug/	Log debug theo phiên, chỉ ghi khi chạy --debug hoặc /debug
paste-cache/, image-cache/	Nội dung các lần dán lớn và ảnh đính kèm
shell-snapshots/	Alias, function và shell option chụp lúc khởi động

Còn nhóm này không bị dọn tự động, tồn tại tới khi bạn xoá:

Đường dẫn	Nội dung
history.jsonl	Mọi prompt bạn từng gõ, kèm timestamp và path project. Dùng cho recall bằng mũi tên lên
stats-cache.json	Số token và chi phí tổng hợp mà /usage hiển thị
remote-settings.json	Bản cache của server-managed settings của tổ chức
cache/changelog.md	Bản cache changelog, dùng để hiện release note sau khi cập nhật

Transcript và history không được mã hoá. Quyền file của hệ điều hành là lớp bảo vệ duy nhất. Nếu một tool đọc file .env hoặc một lệnh in ra credential, giá trị đó được ghi vào transcript. Ba cách giảm rủi ro: hạ cleanupPeriodDays, đặt biến CLAUDE_CODE_SKIP_PROMPT_HISTORY để không ghi transcript và prompt history, hoặc dùng permission rule để chặn đọc file chứa credential.

Muốn xoá sạch trạng thái của một project, chạy claude project purge. Nó in ra kế hoạch xoá đầy đủ và hỏi xác nhận trước khi động vào bất cứ thứ gì. Xem trước mà không xoá:

claude project purge ~/work/my-repo --dry-run

---

Khi Claude không làm theo CLAUDE.md

Nội dung CLAUDE.md được đưa vào dưới dạng tin nhắn user sau system prompt, không phải một phần của system prompt. Claude đọc và cố làm theo, nhưng không có gì đảm bảo tuân thủ nghiêm ngặt — nhất là với chỉ dẫn mơ hồ hoặc mâu thuẫn.

Trình tự debug:

1. Chạy /context, xem mục Memory files để xác nhận file đã nạp. Không có tên file ở đó nghĩa là Claude không thấy nó.
2. Kiểm tra file có nằm ở vị trí được nạp cho phiên của bạn không.
3. Làm chỉ dẫn cụ thể hơn. “Use 2-space indentation” ăn đứt “format code nicely”.
4. Tìm chỉ dẫn mâu thuẫn giữa các file CLAUDE.md.

Nếu chỉ dẫn bắt buộc phải chạy ở một thời điểm cố định — trước mỗi commit, sau mỗi lần sửa file — thì viết nó thành hook (phần 13). Hook chạy như lệnh shell tại các mốc vòng đời cố định và có hiệu lực bất kể Claude quyết định gì.

Chỉ dẫn biến mất sau /compact? CLAUDE.md ở gốc project sống sót — Claude đọc lại từ đĩa và chèn lại. Nhưng CLAUDE.md lồng trong thư mục con và rule có paths: không được chèn lại tự động; chúng nạp lại ở lần kế tiếp Claude đọc một file khớp. Nếu chỉ dẫn biến mất, nó hoặc chỉ được nói trong hội thoại, hoặc nằm ở một trong hai chỗ vừa nêu.

CLAUDE.md quá lớn? Bản kiểm tra /doctor đề xuất cắt gọt cho CLAUDE.md đã commit: nó bỏ phần Claude tự suy ra được từ codebase (bố cục thư mục, danh sách dependency, tổng quan kiến trúc) và giữ lại các cạm bẫy, lý do và convention khác với mặc định của công cụ.

---

Hết chặng nền tảng

Bốn phần đầu đã dựng đủ mental model: Claude Code là gì và chạy ở đâu (phần 1), agent loop và tool (phần 2), context window và caching (phần 3), và bộ nhớ xuyên phiên (phần 4).

Từ phần 5, series chuyển sang chặng vận hành hằng ngày: interactive mode, CLI, slash command, permission mode, session và checkpointing.

Nguồn

• How Claude remembers your project
• Explore the .claude directory

Docs gốc cập nhật thường xuyên; khi có mâu thuẫn, tin bản tiếng Anh.