CLAUDE.md — Bộ nhớ dự án và Auto Memory
Cách viết CLAUDE.md hiệu quả, quản lý auto memory, tổ chức rules với .claude/rules/ và troubleshoot khi Claude không follow instructions.
Mỗi session Claude Code đều bắt đầu với context window mới. Hai cơ chế mang kiến thức xuyên suốt các session: CLAUDE.md files (bạn viết) và Auto Memory (Claude tự ghi). Hiểu và tận dụng hai cơ chế này giúp Claude làm việc chính xác hơn đáng kể.
Tổng quan
Ai viết: Bạn
Nội dung: Instructions và rules
Scope: Project, user, hoặc org
Load vào: Mỗi session
Dùng cho: Coding standards, workflows, architecture
Ai viết: Claude
Nội dung: Learnings và patterns
Scope: Per repository, share qua worktrees
Load vào: Mỗi session (200 dòng đầu hoặc 25KB)
Dùng cho: Build commands, debugging insights, preferences
Vị trí CLAUDE.md
CLAUDE.md có thể đặt ở nhiều vị trí, mỗi vị trí có scope khác nhau:
Managed policy
/Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux)
Company-wide instructions
Tất cả users trong org
User
~/.claude/CLAUDE.md
Personal preferences
Chỉ bạn (mọi project)
Project
./CLAUDE.md hoặc ./.claude/CLAUDE.md
Team-shared instructions
Team qua git
Local
./CLAUDE.local.md
Personal project notes
Chỉ bạn (project hiện tại)
Load order
Claude Code load CLAUDE.md theo thứ tự:
Parent directories trước — từ root đến working directory
CLAUDE.local.md sau CLAUDE.md —在同一 directory
Subdirectories on-demand — chỉ khi Claude đọc file trong thư mục đó
Cách viết CLAUDE.md hiệu quả
Nên và không nên đưa vào
Bash commands Claude không guess được
Anything Claude tự đọc code biết được
Code style rules khác defaults
Standard language conventions
Testing instructions, preferred test runners
Detailed API documentation
Repo etiquette (branch naming, PR conventions)
Information thay đổi thường xuyên
Architecture decisions đặc thù project
Long explanations, tutorials
Developer environment quirks
File-by-file descriptions
Common gotchas, non-obvious behaviors
"Write clean code"
Ví dụ CLAUDE.md
Import file với @ syntax
CLAUDE.md có thể import thêm files:
Import được expand và load vào context khi session start. Hỗ trợ relative và absolute paths, max depth 4 hops.
Tạo CLAUDE.md với /init
/init phân tích codebase và tự tạo CLAUDE.md với build commands, test instructions, và project conventions. Nếu đã có CLAUDE.md, nó gợi ý improvements thay vì overwrite.
Auto Memory
Auto Memory cho phép Claude tích lũy kiến thức xuyên suốt các session mà bạn không cần viết gì.
Cách hoạt động
Claude tự quyết định gì值得记忆 dựa trên corrections và preferences
Lưu tại
~/.claude/projects/<project>/memory/MEMORY.mdacts as index, được load mỗi session (200 dòng đầu)Topic files (debugging.md, patterns.md...) chỉ load on-demand
Bật/tắt Auto Memory
Hoặc dùng environment variable:
Audit và edit memory
Gõ /memory trong session để:
Liệt kê tất cả CLAUDE.md và memory file locations
Toggle auto memory on/off
Mở auto memory folder để edit thủ công
Auto memory files là plain markdown — bạn có thể edit hoặc delete bất cứ lúc nào.
Tổ chức rules với .claude/rules/
Cho projects lớn, organize instructions thành nhiều files trong .claude/rules/:
Path-specific rules
Rules có thể scoped theo file paths bằng YAML frontmatter:
Rules có paths chỉ load khi Claude làm việc với files match pattern. Rules không có paths load unconditionally.
**/*.ts
Tất cả file TypeScript
src/**/*
Tất cả files trong src/
*.md
Markdown files trong project root
User-level rules
Personal rules tại ~/.claude/rules/ apply cho mọi project:
User-level rules load trước project rules — project rules có higher priority.
Troubleshoot
Claude không follow CLAUDE.md
Chạy
/contextđể verify CLAUDE.md đã loadKiểm tra file có ở đúng vị trí không
Instructions có quá vague không? Thay
"Format code nicely"bằng"Use 2-space indentation"Có conflicting instructions giữa các CLAUDE.md files không?
CLAUDE.md quá lớn
Target dưới 200 dòng
Dùng path-scoped rules để load instructions only khi cần
Split content với
@pathimports (nhưng imported files vẫn load vào context)
Instructions mất sau /compact
Project-root CLAUDE.md survives compaction — Claude re-reads từ disk sau /compact. Nhưng nested CLAUDE.md files trong subdirectories không re-inject tự động — chúng reload khi Claude đọc file trong thư mục đó.
Tài liệu tham khảo
Cập nhật lần cuối