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

CLAUDE.md files

• 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

Auto Memory

• 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:

Scope	Vị trí	Mục đích	Chia sẻ với
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)

Thêm CLAUDE.local.md vào .gitignore — file này chứa preferences cá nhân, không nên commit.

Load order

Claude Code load CLAUDE.md theo thứ tự:

1. Parent directories trước — từ root đến working directory

2. CLAUDE.local.md sau CLAUDE.md —在同一 directory

3. 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

Nên đưa vào	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"

Target dưới 200 dòng mỗi file CLAUDE.md. File dài consuming more context và reduce adherence.

Ví dụ CLAUDE.md

CLAUDE.md

# Code style
- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible
- Use 2-space indentation

# Workflow
- Run `pnpm lint` before committing
- Run `pnpm typecheck` after code changes
- Prefer running single tests, not whole test suite

# Architecture
- Monorepo with apps/web and packages/core
- API handlers live in src/api/handlers/
- Use zod for validation

# Git
- Branch naming: feature/, fix/, chore/
- Commit: conventional commits format
- No console.log in production code

Import file với @ syntax

CLAUDE.md có thể import thêm files:

CLAUDE.md

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

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

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

Claude Code prompt

/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.

Set CLAUDE_CODE_NEW_INIT=1 để bật interactive multi-phase flow — /init sẽ hỏi cần setup artifact nào, explore codebase với subagent, và presentation proposal trước khi ghi file.

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.md acts 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

settings.json

{
  "autoMemoryEnabled": true
}

Hoặc dùng environment variable:

Terminal

CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude

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/:

Cấu trúc thư mục

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── security.md

Path-specific rules

Rules có thể scoped theo file paths bằng YAML frontmatter:

.claude/rules/api-design.md

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

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

Rules có paths chỉ load khi Claude làm việc với files match pattern. Rules không có paths load unconditionally.

Pattern	Match
**/*.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:

~/.claude/rules/

~/.claude/rules/
├── preferences.md
└── workflows.md

User-level rules load trước project rules — project rules có higher priority.

Troubleshoot

Claude không follow CLAUDE.md

1. Chạy /context để verify CLAUDE.md đã load

2. Kiểm tra file có ở đúng vị trí không

3. Instructions có quá vague không? Thay "Format code nicely" bằng "Use 2-space indentation"

4. Có conflicting instructions giữa các CLAUDE.md files không?

Nếu instruction phải chạy tại thời điểm nhất định (trước mỗi commit, sau mỗi file edit), dùng hooks thay vì CLAUDE.md. Hooks execute deterministic, không phụ thuộc Claude decide.

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 @path imports (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

• Memory Documentation

• Skills

• Settings

• Debug Your Config