Cách tôi quản lý bộ nhớ của Claude Code: File nào commit, file nào giữ ở máy

Claude Code đọc các file hướng dẫn trước khi làm bất cứ việc gì. Những file này là "bộ nhớ" của nó — tập hợp các quy tắc và thông tin mà nó mang theo vào mỗi phiên làm việc. Làm đúng thì Claude tuân theo quy ước của bạn mà không cần nhắc lại lần hai. Làm sai thì hoặc bạn để lộ cấu hình cá nhân vào một repo dùng chung, hoặc bạn phải lặp đi lặp lại cùng một điều trong mỗi cuộc trò chuyện.

Tôi dùng vài nơi để lưu các quy tắc này: một file user (người dùng), một file project (dự án), và một file local (cục bộ) — cộng thêm một kho bộ nhớ riêng mà Claude tự ghi vào. Mỗi nơi có một nhiệm vụ khác nhau, và chỉ một số trong đó nên đưa vào git. Bài này là cách tôi phân chia chúng, kèm ví dụ thật từ máy của tôi.

Các lớp bộ nhớ, từ rộng đến hẹp

Claude Code nạp bộ nhớ từ nhiều file rồi xếp chồng chúng lại với nhau. Từ phạm vi rộng nhất đến cụ thể nhất:

1. Managed policy (chính sách do tổ chức đặt) — do quản trị viên của tổ chức đặt. Trên Linux nó nằm ở /etc/claude-code/CLAUDE.md; trên Mac thì ở /Library/Application Support/ClaudeCode/CLAUDE.md. Nó áp dụng cho mọi người trong công ty và không thể ghi đè. Nếu bạn làm một mình thì sẽ chẳng bao giờ thấy nó.
2. User memory (bộ nhớ người dùng) — ~/.claude/CLAUDE.md. Quy tắc dành cho bạn, áp dụng cho mọi dự án trên máy của bạn.
3. Project memory (bộ nhớ dự án) — ./CLAUDE.md ở thư mục gốc của repo. Quy tắc cho codebase này, chia sẻ cho cả nhóm.
4. Project-local memory (bộ nhớ cục bộ của dự án) — ./CLAUDE.local.md. Quy tắc cho bạn, chỉ trên dự án này. Không chia sẻ.

Hãy hình dung nó như một chồng đĩa. Quy tắc rộng đặt xuống trước, các file hẹp hơn xếp chồng lên trên. Khi hai file mâu thuẫn nhau, file cụ thể hơn thường thắng — quy tắc của dự án ghi đè thói quen cá nhân, và managed policy ghi đè tất cả.

Claude tìm các file này như thế nào

Việc nạp không chỉ giới hạn ở thư mục hiện tại. Có hai điều xảy ra:

Nó đi ngược lên cây thư mục. Khi bạn khởi động Claude Code, nó đọc CLAUDE.md từ thư mục làm việc của bạn và mọi thư mục cha bên trên, lên tới thư mục gốc của hệ thống file. Nên trong một monorepo, CLAUDE.md ở gốc repo vẫn áp dụng ngay cả khi bạn khởi động Claude bên trong apps/web.

Nó đọc xuống khi cần. Khi Claude mở một file trong thư mục con, nó cũng nhặt luôn bất kỳ CLAUDE.md nào nằm ở đó — nhưng chỉ khi nó thực sự đi vào thư mục đó. Điều này giữ cho ngữ cảnh lúc khởi động gọn nhẹ: một quy tắc chỉ quan trọng với src/payments/ sẽ không tốn gì của bạn cho tới khi Claude đụng vào đoạn code đó.

my-monorepo/
├── CLAUDE.md              # luôn được nạp (quy tắc toàn repo)
├── apps/
│   └── web/
│       └── CLAUDE.md      # nạp khi bạn làm việc trong apps/web
└── packages/
    └── ui/
        └── CLAUDE.md      # chỉ nạp khi Claude mở file trong packages/ui

Trong một monorepo lớn, đôi khi bạn muốn bỏ qua một file của thư mục cha — chẳng hạn quy tắc của nhóm khác. Bạn có thể liệt kê các đường dẫn đó dưới claudeMdExcludes trong .claude/settings.local.json để chúng không được nạp.

File nào thì đưa vào git?

Đây là phần nhiều người làm sai. Quy tắc đơn giản là:

File	Có commit không?	Dành cho ai
~/.claude/CLAUDE.md	Không — nó nằm ngoài repo	Bạn, ở mọi nơi
~/.claude/settings.json	Không — nằm ngoài repo	Bạn, ở mọi nơi
./CLAUDE.md	Có	Cả nhóm
./CLAUDE.local.md	Không — cho vào gitignore	Bạn, chỉ repo này
.claude/settings.json	Có	Cả nhóm
.claude/settings.local.json	Không — cho vào gitignore	Bạn, chỉ repo này

Mẫu dễ nhớ: bất cứ thứ gì có .local. trong tên, hoặc bất cứ thứ gì nằm trong thư mục home của bạn, đều không đưa lên git. Mọi thứ còn lại là dùng chung.

Lý do commit ./CLAUDE.md cũng giống lý do bạn commit README: một đồng nghiệp mới — hay chính bạn, trên một laptop mới — nên nhận được quy ước của dự án một cách miễn phí. Lý do giữ file local ở ngoài là vì nó chứa những cái riêng của bạn: một URL tạm, một đường dẫn chỉ tồn tại trên máy bạn. Những thứ đó chỉ làm người khác rối thêm.

Loại quy tắc nào thuộc về từng file

Các file không chỉ nói về nơi quy tắc được lưu. Mỗi file chứa một loại quy tắc khác nhau. Trộn lẫn chúng chính là thứ khiến một file bộ nhớ phình to và khó tin cậy.

File user — cách bạn thích làm việc

File ~/.claude/CLAUDE.md của tôi thuần về hành vi. Nó không nói gì về một dự án cụ thể nào cả. Vài quy tắc tôi để ở đó:

## Response Style
- Use plain language. Keep sentences short — one idea each.
- No jargon. If a technical term is needed, explain it in plain words.

## Git Commits and Pushes
- Never auto-commit or auto-push. Only when the current message asks for it.
- Approval does not carry forward from a previous message.

## Commit Message Format
- Always prefix the commit message with the ticket number from the branch name.

Những quy tắc này theo tôi vào mọi repo. Chúng nói về khẩu vị và thói quen an toàn của tôi, không phải về một codebase nào. Đó đúng là công dụng của file user:

• Văn phong và giọng điệu bạn luôn muốn.
• Quy tắc an toàn — "đừng bao giờ push trừ khi tôi yêu cầu."
• Công cụ bạn dùng ở khắp nơi — chẳng hạn pnpm thay vì npm.
• Quy ước git cá nhân của bạn.

Một lời cảnh báo: hãy giữ file này gọn. Nó được nạp vào mọi phiên của mọi dự án, nên một đống quy tắc ngóc ngách ở đây là thuế thuần túy đánh vào ngữ cảnh của bạn. Nếu một quy tắc chỉ quan trọng với một repo, nó không thuộc về file user.

File project — cách codebase này vận hành

File CLAUDE.md trong repo của blog này thì ngược lại. Nó không nói gì về tôi mà nói tất cả về dự án:

## Commands
npm run dev        # dev server on http://localhost:3000
npm run seed       # wipe + load sample data — REQUIRES MONGODB_URI

## Architecture — the important parts
- SSR pages call lib/articles.js and hit Mongo directly.
- Client components call the same-origin /api/* route handlers.
- Auth is a JWT in an httpOnly cookie.

Đây là thứ mà mọi lập trình viên cần và không ai nên phải tự mò lại:

• Lệnh build, chạy, và test.
• Kiến trúc và bố cục thư mục.
• Chuẩn code và quy tắc đặt tên của nhóm.
• Những cái bẫy riêng của codebase — kiểu "đừng làm X, nó làm hỏng Y."

Một phép thử tốt: nếu quy tắc vẫn đúng với một đồng nghiệp trên một bản clone mới, nó thuộc về đây. Nếu nó phụ thuộc vào laptop của bạn thì không.

File local — thiết lập của bạn cho repo này

File local dành cho những quy tắc gắn với dự án này nhưng chỉ có ý nghĩa trên máy của bạn:

# CLAUDE.local.md — không commit
- My local API runs on port 4000, not the default 3000.
- Use the seed data in ~/scratch/blog-fixtures.json for testing.
- Skip the Docker step — I run Mongo natively.

URL sandbox, đường dẫn riêng của máy, dữ liệu test cá nhân, một mẹo debug bạn dùng nhưng cả nhóm không cần. Không thứ nào thuộc về file dùng chung, nhưng tất cả đều đáng nhớ giữa các phiên làm việc.

CLAUDE.local.md và @import: hai cách giữ mọi thứ riêng tư

Có một cách thứ hai để giữ quy tắc cá nhân, và nó đáng biết vì nhiều người tưởng nó thay thế file local. Không phải vậy — chúng giải quyết hai vấn đề hơi khác nhau.

Bất kỳ CLAUDE.md nào cũng có thể kéo một file khác vào bằng cú pháp @:

# Personal setup for this repo
@~/.claude/my-blog-preferences.md

Dòng đó bảo Claude nạp file preferences trong thư mục home của bạn như một phần của bộ nhớ dự án. Vì file nằm trong thư mục home, nó được chia sẻ qua mọi worktree của cùng repo — tiện khi bạn giữ vài bản checkout của một dự án song song. Các import có thể lồng nhau vài cấp trước khi Claude ngừng đi theo, và cú pháp @ bị bỏ qua bên trong khối code (đó là lý do các ví dụ trong chính bài này không kích hoạt điều gì).

Một lưu ý an toàn: nếu một CLAUDE.md dùng chung import một file từ ngoài repo, Claude Code sẽ hỏi bạn phê duyệt trong lần đầu. Điều đó ngăn một file đã commit lặng lẽ kéo vào thứ gì đó từ máy của bạn.

Vậy dùng cái nào?

• CLAUDE.local.md — quy tắc cá nhân khép kín cho một repo. Lựa chọn đơn giản nhất. Chỉ cần nhớ cho vào gitignore.
• Import @~/.claude/... — quy tắc cá nhân bạn muốn chia sẻ qua mọi worktree, hoặc tái dùng qua nhiều dự án.

Không cái nào bị khai tử cả. Chọn dựa trên việc quy tắc ở yên một chỗ hay đi theo bạn.

Chia nhỏ file lớn bằng import và thư mục rules

Hai công cụ nữa giúp ích khi một file CLAUDE.md đơn lẻ trở nên cồng kềnh.

Import để có cấu trúc. Bạn có thể tách một file dài thành các file theo chủ đề rồi kéo chúng vào:

# Project memory
@docs/architecture.md
@docs/testing.md
@docs/deploy.md

Cái này là về dễ đọc, không phải để tiết kiệm ngữ cảnh — các file được import vẫn nạp lúc khởi động. Giữ file chính chỉ như một mục lục ngắn giúp dễ bảo trì hơn.

Thư mục rules để giới hạn phạm vi. Với một codebase lớn, bạn có thể đặt quy tắc theo chủ đề dưới .claude/rules/ và gắn cho mỗi cái các đường dẫn mà nó áp dụng. Một quy tắc có header paths chỉ nạp khi Claude đụng vào file khớp:

---
paths:
  - "src/api/**/*.ts"
---
# API rules
- Every endpoint validates its input.
- Use the shared error-response helper.

Giờ các quy tắc API nằm im cho tới khi Claude thật sự mở một file API. Đó cũng chính là ý tưởng "chỉ nạp khi liên quan" như các file CLAUDE.md trong thư mục con, chỉ là chủ động hơn.

Bộ nhớ không giống với settings

Có một điểm phân biệt khiến người ta liên tục vấp. CLAUDE.md và .claude/settings.json trông giống nhau và nằm gần nhau, nhưng làm hai việc khác nhau.

• CLAUDE.md là hướng dẫn. Nó được đưa cho Claude như ngữ cảnh. Claude cố gắng tuân theo, nhưng đó là lời khuyên, không phải hàng rào. Một mô hình đang mất tập trung có thể bỏ sót nó.
• settings.json là sự cưỡng chế. Nó do chính công cụ đọc. Quyền hạn, hook, và biến môi trường ở đây áp dụng bất kể Claude quyết định thế nào.

Một ví dụ hay từ thiết lập của tôi: file user của tôi nói "đừng bao giờ thêm footer ghi công Claude Code vào commit." Đó là hướng dẫn. File settings.json của tôi củng cố điều đó bằng cấu hình cứng:

{
  "attribution": { "commit": "", "pr": "" },
  "includeCoAuthoredBy": false
}

Quy tắc trong CLAUDE.md lo phần văn bản tự do mà Claude tự viết ra; còn setting lo phần cắt bỏ footer mà công cụ sẽ tự thêm vào. Chắc ăn cả đôi đường. Dùng CLAUDE.md cho "cách chúng ta làm việc" và settings.json cho "những gì được phép."

Settings tuân theo cùng quy tắc commit như bộ nhớ, và chúng được giải quyết theo một thứ tự rõ ràng khi mâu thuẫn — managed policy trước, rồi tới cờ dòng lệnh, rồi file project local của bạn, rồi file project dùng chung, rồi settings user:

managed  >  cờ --settings  >  .claude/settings.local.json
         >  .claude/settings.json  >  ~/.claude/settings.json

Nên settings.local.json trên máy bạn thắng file team đã commit, nhưng không gì thắng được managed policy.

Bộ nhớ mà Claude tự viết cho mình

Còn một kho nữa đáng biết, và nó không phải file do bạn soạn. Claude Code có thể giữ ghi chú của riêng nó về một dự án — những thứ nó học được mà không có trong code: một sở thích bạn nêu ra, một chỉnh sửa bạn đưa ra, một hạn chót bạn nhắc tới.

Chúng nằm ngoài repo, dưới thư mục cấu hình Claude của bạn, mỗi thông tin một file ngắn kèm một header mô tả nó, cộng một file mục lục. Claude tự viết và tự đọc chúng; bạn không commit chúng, và chúng không đồng bộ giữa các máy.

Điểm khác với CLAUDE.md:

• CLAUDE.md là bạn nói cho Claude biết các quy tắc, ngay từ đầu, một cách có chủ đích.
• Bộ nhớ tự động là Claude ghi lại những gì nó nhặt được, trong lúc làm.

Chúng bổ trợ cho nhau. Nếu bạn thấy mình đưa ra cùng một chỉnh sửa hai lần, đó là dấu hiệu nó nên được "thăng cấp" từ một lời nói thoáng qua thành một dòng rõ ràng trong CLAUDE.md, nơi bạn kiểm soát nó và cả nhóm cùng thấy.

Ba cách thêm bộ nhớ

Bạn không phải tự tay viết mọi file:

• /init — chạy nó trong một repo mới và Claude đọc codebase, rồi soạn một CLAUDE.md khởi đầu với các lệnh build và quy ước mà nó tìm thấy. Một bản nháp chắc chắn để bạn cắt gọt lại.
• Phím tắt # — bắt đầu một tin nhắn bằng # và Claude lưu dòng đó vào bộ nhớ, hỏi bạn muốn để nó vào file nào. Tốt cho việc ghi lại một quy tắc ngay khoảnh khắc bạn nghĩ ra.
• /memory — mở các file bộ nhớ trong trình soạn thảo của bạn để chỉnh trực tiếp khi bạn muốn sắp xếp lại.

Cái bẫy từng vướng tôi: hãy gitignore các file local của bạn

Đây là điểm cần lưu ý. Tạo một CLAUDE.local.md hay một .claude/settings.local.json không tự động giữ nó ngoài git. Chữ .local. trong tên là một quy ước Claude Code hiểu — nó chẳng có ý nghĩa gì với git.

Tôi đã kiểm tra file .gitignore của repo này khi viết bài và thấy nó không nhắc tới file Claude nào cả. Nên nếu tôi bỏ vào đó một CLAUDE.local.md đầy đường dẫn cục bộ, git add . sẽ vui vẻ đưa nó vào staging, và những cái riêng của máy tôi sẽ rơi vào bản clone của mọi người.

Sửa nó một lần, ngay từ đầu. Thêm các dòng này vào .gitignore:

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

Rồi các file cá nhân của bạn ở yên phần cá nhân, các file dùng chung ở yên phần dùng chung, đúng như ý định. Lưu ý rằng bạn vẫn commit .claude/settings.json và bất kỳ .claude/rules/ nào — chỉ file .local. là bị bỏ qua.

Bố cục của tôi, trong một bức tranh

Đây là cách mọi thứ nằm chung với nhau trên máy tôi:

~/.claude/CLAUDE.md              # quy tắc user — văn phong, thói quen git của tôi (không ở repo nào)
~/.claude/settings.json          # cấu hình user — quyền hạn, hook, tắt ghi công

repo/CLAUDE.md                   # quy tắc project — lệnh, kiến trúc (đã commit)
repo/.claude/settings.json       # cấu hình project — dùng chung (đã commit)
repo/.claude/rules/              # quy tắc theo phạm vi đường dẫn — dùng chung (đã commit)
repo/CLAUDE.local.md             # quy tắc của tôi cho repo này (đã gitignore)
repo/.claude/settings.local.json # cấu hình của tôi cho repo này (đã gitignore)

# và, ngoài repo, các ghi chú riêng theo dự án mà Claude tự viết và tự đọc

Một checklist để lấy dùng

• Đặt quy tắc văn phong và an toàn cá nhân vào ~/.claude/CLAUDE.md. Đừng bao giờ commit nó.
• Đặt lệnh build dùng chung, kiến trúc, và quy ước vào ./CLAUDE.md. Commit nó.
• Đặt đường dẫn riêng của máy và dữ liệu tạm vào ./CLAUDE.local.md. Gitignore nó.
• Dùng import @~/.claude/... khi bạn muốn quy tắc cá nhân chia sẻ qua các worktree.
• Chia nhỏ một file cồng kềnh bằng @import, hoặc giới hạn phạm vi quy tắc bằng .claude/rules/.
• Dùng settings.json, không phải CLAUDE.md, khi bạn cần cưỡng chế thật sự.
• Thêm CLAUDE.local.md và .claude/settings.local.json vào .gitignore ngay hôm nay.

Hãy giữ mỗi file ngắn và cụ thể. Nói tại sao, không chỉ cái gì — một quy tắc có lý do sẽ sống lâu hơn một câu lệnh trơ trọi. Thỉnh thoảng rà lại chúng và xóa những quy tắc đã lỗi thời. Làm được vậy, Claude sẽ xuất hiện trong mỗi phiên làm việc mà đã biết sẵn cách bạn làm việc.

Tài liệu tham khảo

https://ledangtuanbk.vercel.app/article/how-i-manage-claude-code-memory