4.6 · Thêm context với CLAUDE.md

Mở đầu: Cái giá của "quên việc"

Thêm một endpoint mới GET /users/:id/invoices trả về 20 hóa đơn gần nhất của user.

Claude trả lời sau 45 giây. Code chạy. Test pass. Nhưng reviewer PR gắn 6 comment:

• "Dùng Drizzle ORM, sao lại import Prisma?"
• "Folder này phải có file .schema.ts kèm theo mỗi route — convention của team."
• "Bọn mình pascal-case cho DTO, không phải camelCase."
• "Response đã có helper paginated() rồi, sao viết lại pagination tay?"
• "Bạn chưa add vào openapi.yaml — CI sẽ fail."
• "Comment in-line dạng // get user id — thừa."

Không phải Claude viết sai. Claude viết chính xác theo default — nhưng default không phải là convention của team bạn. Claude không có cách nào biết team dùng Drizzle, không biết bạn có helper paginated(), không biết quy tắc comment.

Cách đắt nhất để giải quyết

mỗi lần gõ prompt, copy-paste lại toàn bộ convention → 200 dòng boilerplate mỗi request, tốn token, còn dễ quên.

Cách chuẩn

ghi những thứ này đúng một lần vào file CLAUDE.md. Mỗi lần Claude mở project, file đó được "nhét thẳng vào prompt" như một system message ngầm. Từ prompt tiếp theo trở đi, Claude mặc định biết team bạn dùng Drizzle, biết paginated() tồn tại, biết đừng comment thừa.

Đây là bài học tối quan trọng: trong Claude Code, context management là kỹ năng cao nhất. File CLAUDE.md là công cụ cơ bản nhất để làm điều đó.

CLAUDE.md là gì?

Định nghĩa ngắn: CLAUDE.md là file markdown chứa hướng dẫn dành riêng cho Claude, được tự động chèn vào mọi request bạn gửi trong project.

Nói cách khác, nó hoạt động như "system prompt" nhưng cho project cụ thể, và được chia sẻ dưới dạng text thuần — bạn commit vào Git, team cùng sửa, review như code.

Luồng hoạt động

┌─────────────────────────────────────────────────────────┐
│                                                         │
│  Bạn gõ: "Thêm endpoint GET /users/:id/invoices"        │
│                     │                                   │
│                     ▼                                   │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Claude Code nội bộ ghép:                        │  │
│  │   1. Nội dung CLAUDE.md (luôn có)                │  │
│  │   2. Tool definitions (Read/Write/Bash...)       │  │
│  │   3. Prompt của bạn                              │  │
│  └──────────────────────┬───────────────────────────┘  │
│                         ▼                               │
│                  ┌─────────────┐                        │
│                  │  Claude API │                        │
│                  └──────┬──────┘                        │
│                         ▼                               │
│           Response tuân theo convention                 │
│                                                         │
└─────────────────────────────────────────────────────────┘

Hai vai trò chính

CLAUDE.md phục vụ hai mục đích đồng thời:

1. Định hướng Claude qua codebasechỉ rõ architecture, command quan trọng, file nào đáng đọc trước
2. Đưa hướng dẫn riêng của bạnstyle code, convention đặt tên, cấm làm gì, thích làm gì

Lệnh /init — Sinh CLAUDE.md tự động

Khi bạn mở Claude Code trong một project lần đầu, luôn chạy /init trước.

Lệnh này ra lệnh cho Claude:

1. Quét toàn bộ codebase (dùng Glob + Grep + Read)
2. Hiểu: — Mục đích & kiến trúc project — Command quan trọng (build, test, lint, dev server) — File trung tâm (schema, config, entry point) — Coding pattern phổ biến (class vs function, naming, folder layout)
3. Viết kết quả thành CLAUDE.md ở root project

Khi Claude xin permission

Trong quá trình /init, Claude sẽ gọi Write tool và hỏi bạn approve. Có hai cách:

Với /init, thường chỉ có 1 file được tạo (CLAUDE.md) nên Enter là đủ. Với task phức tạp (refactor nhiều file), Shift + Tab tiết kiệm thời gian — nhưng phải trả bằng rủi ro: Claude có thể đi sai hướng mà bạn không kịp chặn.

Ví dụ output điển hình sau /init

Overview

Next.js 14 app that generates React UI components via Claude API. Uses Prisma + SQLite for local persistence.

Key Commands

• npm run setup — install deps + init DB
• npm run dev — start dev server (port 3000)
• npm run test — Vitest + React Testing Library
• npm run db:push — push schema changes to SQLite

Architecture

• src/app/ — App Router pages & API routes
• src/components/ — shared React components
• src/lib/prompts/ — prompt templates sent to Claude API
• prisma/schema.prisma — DB schema source of truth

Conventions

• TypeScript strict mode
• Use @/ path alias for imports
• Test files in __tests__/ next to source

30 dòng, mất 20 giây generate. Đây chính là "bản tóm tắt" mà Claude cần để hành xử như senior đã làm trong project 6 tháng — thay vì intern mới toanh.

---

Ba vị trí của CLAUDE.md

Claude Code nhận diện file CLAUDE.md ở ba nơi khác nhau, mỗi nơi phục vụ một mục đích:

┌──────────────────────────────────────────────────────────┐
│                                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │  1.  <project>/CLAUDE.md                         │   │
│  │      → Commit vào Git, chia sẻ cho team          │   │
│  │      → Quy ước chung: style, architecture        │   │
│  └──────────────────────────────────────────────────┘   │
│                                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │  2.  <project>/CLAUDE.local.md                   │   │
│  │      → .gitignore — KHÔNG commit                 │   │
│  │      → Preference cá nhân, secret path, note     │   │
│  └──────────────────────────────────────────────────┘   │
│                                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │  3.  ~/.claude/CLAUDE.md                         │   │
│  │      → Global, áp dụng mọi project trên máy      │   │
│  │      → Dùng cho habit cá nhân xuyên project      │   │
│  └──────────────────────────────────────────────────┘   │
│                                                          │
└──────────────────────────────────────────────────────────┘

Quy tắc phân loại nội dung

Sai lầm phổ biến

❌ Ghi đường dẫn tuyệt đối /Users/john/Projects/app/... vào project CLAUDE.md rồi commit — Khi teammate pull về, path sai, Claude rối loạn.

✅ Dùng relative path hoặc đưa hardcoded path xuống CLAUDE.local.md.

CLAUDE.md không phải silver bullet — vẫn có giới hạn

Đây là chỗ cần thành thật.

• Context cost: CLAUDE.md "plop vào prompt" mỗi request. Nội dung càng dài, càng tốn token, càng dễ đẩy prompt đến giới hạn 200K token. Thực tế: giữ file dưới 500 dòng là an toàn. Trên 1000 dòng, Claude bắt đầu bỏ qua những gì nằm sâu.
• Model tuân thủ tùy version: Model cũ (Claude 3.5 Sonnet) thường "quên" instruction dù ghi rõ (ví dụ: vẫn thêm comment in-line dù đã cấm). Từ Claude 4 trở đi, khả năng follow instruction tốt lên rõ rệt. Nếu bạn đang dùng model mới, có thể rà lại CLAUDE.md và trim bớt những hướng dẫn "workaround cho model cũ".
• Không phải noise collector: Đừng biến CLAUDE.md thành nơi chứa mọi note hay ý tưởng. Mỗi dòng phải có lý do tồn tại — nếu xóa đi không ảnh hưởng hành vi Claude, nên xóa.

Thêm hướng dẫn tùy chỉnh qua memory mode (#)

Giả sử bạn đang chat với Claude, nó lại thêm comment kiểu // increment counter by 1 cho một dòng counter++ (vô nghĩa). Bạn có thể:

• Cách cũ: mở CLAUDE.md, gõ thêm câu "Use comments sparingly...", save, quay lại Claude.
• Cách memory mode: gõ ngay trong prompt:

Dấu # ở đầu dòng kích hoạt memory mode. Claude sẽ:

1. Đọc hướng dẫn đó
2. Tự phân tích xem nên append vào file CLAUDE.md nào (project / local / global) — hoặc hỏi bạn
3. Merge thông minh: nếu đã có section "Comments", thêm dòng vào section đó; nếu chưa, tạo mới
4. Save, report lại cho bạn

Kết quả: file CLAUDE.md vừa được update mà bạn không phải rời khỏi terminal.

Khi nào nên dùng memory mode?

✅ Khi bạn phát hiện một lỗi lặp lại (Claude vừa mắc → rút kinh nghiệm ngay) ✅ Khi bạn vừa giải thích một convention dài trong chat — muốn lưu lại ✅ Khi đang trong flow và không muốn mất context để edit file thủ công

❌ Không dùng cho "vibe note" không rõ ràng (chi phí re-read sau này cao) ❌ Không dùng cho secret/credential — memory mode không biết cái gì là secret

Ví dụ conversation thực tế

You:  Tại sao bạn lại viết lại hàm formatDate? 
      Mình đã có helper @lib/utils/date.ts rồi.

Claude: Bạn nói đúng — tôi đã tạo hàm trùng lặp. Để tôi xóa và 
        dùng lại helper có sẵn.

You:  # Before creating any utility function, search in lib/utils/ 
      first to check if an equivalent exists.

Claude: Đã thêm vào project CLAUDE.md, section "Code Style".

Lần sau khi Claude định tạo util mới, nó sẽ tự grep lib/utils/ trước khi viết — không phải vì nó nhớ từ conversation (conversation sẽ hết sau khi bạn exit), mà vì dòng đó đã nằm vĩnh viễn trong CLAUDE.md.

Cú pháp @ — Mention file cụ thể

Khi bạn cần Claude nhìn vào file cụ thể, gõ @ rồi tên file/folder:

Giải thích flow auth của project, tập trung vào @src/lib/auth/

Claude sẽ:

1. Suggest autocomplete (giống Git Tab): hiện list file matching
2. Bạn chọn file → nội dung file được tự động include vào request
3. Claude trả lời với ngữ cảnh đầy đủ

Khác biệt với CLAUDE.md

Dùng @ bên trong CLAUDE.md

Đây là kỹ thuật nâng cao rất hữu ích. Bạn có thể viết trong CLAUDE.md:

Database

The database schema is defined in @prisma/schema.prisma. Reference it anytime you need to understand the structure of data stored in the database.

API Conventions

All API routes must follow the pattern defined in @src/app/api/_example/route.ts. Use this as template for new endpoints.

Khi Claude load `CLAUDE.md`, nó sẽ **tự động đọc luôn** `prisma/schema.prisma` và `src/app/api/_example/route.ts` vào context. Bạn không phải mention lại mỗi lần hỏi về DB.

**Trade-off:** Hai file đó luôn nằm trong prompt — tốn token. Chỉ làm khi file đó **thực sự** cần cho hầu hết câu hỏi (ví dụ: schema là trung tâm của project).

---

Ví dụ thực chiến: Onboard một team 8 engineer

Tình huống

Bạn là tech lead team 8 người ở công ty fintech. Team vừa merge PR gộp ba microservices thành monorepo. Ai cũng đang loay hoay vì Claude Code (mới rollout) hành xử khác nhau trên máy mỗi người — người bảo "Claude cứ dùng callback thay vì async/await", người than "Claude tự thêm console.log khắp nơi".

Bước 1: Mở repo, chạy /init

Claude quét, viết CLAUDE.md đầu tiên:

Three services in one repo: payments, ledger, reporting.

Structure

• services/payments/ — Fastify + Drizzle
• services/ledger/ — Fastify + Drizzle
• services/reporting/ — Next.js + tRPC
• packages/common/ — shared types, utils
• packages/sdk-* — client SDKs

Commands

• pnpm install — at root
• pnpm --filter payments dev
• pnpm --filter reporting test

### Bước 2: Thêm team conventions (viết tay)

Bạn edit `CLAUDE.md`, append:

Code Style

• Async/await ONLY. Never use raw Promise.then chains or callbacks.
• No console.log in committed code. Use pino logger (see @packages/common/logger.ts).
• All money amounts stored as BigInt (minor units). Never Number.
• Error handling: throw typed AppError (see @packages/common/errors.ts).

Testing

• Unit tests colocated: foo.ts + foo.test.ts
• Integration tests in __integration__/ folder
• Use describe/it (Vitest), not test()

Git

• Conventional Commits required
• PR titles: <type>(<scope>): <summary>
• Branch names: feat/<ticket-id>-slug

### Bước 3: Commit & broadcast

git add CLAUDE.md git commit -m "chore: add Claude Code project instructions" git push

Slack message cho team: "Vừa push `CLAUDE.md`. Pull về, Claude Code của mọi người sẽ đồng bộ convention."

### Bước 4: Mỗi dev tự customize local

Một dev Python-first (mới chuyển sang TS) tạo `CLAUDE.local.md`:

Personal preferences

• Explain TypeScript concepts in terms of Python equivalents when I ask about types (I'm more familiar with Python typing).
• Verbose error messages preferred over terse ones.

File này không commit. Chỉ dev đó được hưởng.

### Kết quả sau 2 tuần

- **Review time PR giảm 40%** — convention comment giảm từ ~8/PR xuống ~2/PR
- **Claude output nhất quán** trên 8 máy — không còn "case by case"
- **Onboard dev mới:** chỉ cần `git pull` + `/init` → Claude hiểu codebase ngay

**Tiết kiệm thực tế:** ~3 giờ/tuần/dev × 8 dev = **24 giờ team/tuần**.

---

Case studies theo ngành

Finance Engineer — Compliance-aware Claude

Trước: "Claude cứ suggest dùng float cho số tiền. Compliance flag mỗi PR. Mình phải sửa tay."

Với CLAUDE.md:

CRITICAL: Money representation

• NEVER use float/double for monetary values
• Use decimal.Decimal (Python) or BigInt (TS) with minor units
• All amounts must include Currency enum reference
• See @src/finance/types.ts for canonical types

- **Kết quả:** 0 compliance flag liên quan money type trong 90 ngày, tiết kiệm ~5 giờ/tuần review.

### ⚖️ Legal Tech — Dữ liệu nhạy cảm không leak

**Trước:** "Claude thỉnh thoảng log SSN/PII vào debug output khi generate test data."

**Với `CLAUDE.md`:**

Data handling

• NEVER generate realistic PII in test fixtures (no real SSN patterns, no real emails, no real addresses)
• Use faker library with faker.seed(42) for reproducibility
• Any field marked @sensitive in schema must never appear in logs
• See @security/data-policy.md for full rules

- **Kết quả:** Security audit pass clean — không có incident generated PII leak trong 6 tháng.

### 🏥 Healthcare SaaS — HIPAA boundary

**Trước:** "Team dev ở 3 múi giờ. Mỗi người giải thích HIPAA cho Claude khác nhau."

**Với `CLAUDE.md` chia sẻ:**

HIPAA boundaries

• Patient data only in services/phi-vault — never in services/reporting
• If Claude detects PHI field name (see @common/phi-schema.ts list) being imported outside phi-vault, refuse and flag
• All audit logs via @common/audit-logger.ts (no console.log)

- **Kết quả:** Zero cross-boundary PHI leak trong Claude-generated code, pass SOC 2 audit.

### 📣 Marketing Agency — Brand voice consistency

**Trước:** "Claude viết microcopy cho landing page mỗi lần một kiểu — lúc formal, lúc casual."

**Với `~/.claude/CLAUDE.md` (global cho designer):**

Brand voice (Acme Agency)

• Tone: confident but humble, no hype
• Words to avoid: "revolutionary", "game-changing", "cutting-edge"
• Words to prefer: "practical", "direct", "tested"
• CTA style: verb-first, imperative, max 4 words
• See @brand/voice-examples.md for before/after samples

- **Kết quả:** 3-4 rounds review → 1 round, giao client 2x nhanh.

### 🛠️ Product Engineer — Migration dần dần

**Trước:** "Team đang migrate từ Prisma sang Drizzle nhưng Claude vẫn mặc định suggest Prisma pattern."

**Với `CLAUDE.md`:**

Database migration in progress

Status: migrating Prisma → Drizzle (tracker @docs/migration.md)

• Files in services/payments/: Drizzle ONLY (migration complete)
• Files in services/ledger/: Prisma allowed (migration pending)
• New code: ALWAYS Drizzle, even in ledger/
• Never write new Prisma schema — edit @drizzle/schema.ts instead

- **Kết quả:** Migration hoàn thành 2 tuần sớm, không có PR "chống migration" từ Claude.

---

Prompt templates cho CLAUDE.md

Dưới đây là 5 template bạn có thể copy-adapt cho project của mình.

1. Bootstrap một CLAUDE.md mới (ngoài /init)

Đọc toàn bộ codebase này, đặc biệt @package.json, @tsconfig.json, 
các file README, và 3-5 file source đại diện nhất. Sau đó viết một 
file CLAUDE.md với các section:

1. Project Overview (1-2 câu)
2. Key Commands (build/dev/test/lint)
3. Architecture (folder structure chính, không quá chi tiết)
4. Conventions đã phát hiện (naming, testing pattern, error handling)
5. Files to always reference (dùng @)

Giữ dưới 200 dòng. Ưu tiên hướng dẫn có actionable behavior hơn 
là description.

2. Audit CLAUDE.md đang có

Review @CLAUDE.md hiện tại. Với mỗi instruction, đánh giá:

- Nó có thực sự thay đổi hành vi của Claude không? Hay chỉ là 
  description?
- Có lặp với convention đã có trong eslint/prettier/tsconfig không?
- Có outdated (ví dụ: mention package cũ đã thay thế) không?

Output: danh sách instruction đề xuất (a) giữ, (b) xóa, (c) rewrite 
cho rõ hơn. KHÔNG tự sửa file.

3. Trích xuất conventions từ existing code

Đọc 10 file random trong @src/. Phát hiện các pattern lặp lại không 
có trong @CLAUDE.md hiện tại (naming, error handling, import order, 
comment style). Liệt kê và đề xuất add vào CLAUDE.md.

4. Migrate convention khi chuyển tech stack

Team đang migrate từ [X] sang [Y]. Đọc @CLAUDE.md hiện tại, tìm 
tất cả instruction còn tham chiếu [X]. Suggest update để:
- Nêu rõ trạng thái migration (in progress / complete)
- Rule cho code mới vs code cũ
- Reference doc migration plan nếu có

5. Sync CLAUDE.md với documentation người

So sánh @CLAUDE.md với @docs/CONTRIBUTING.md và @docs/ARCHITECTURE.md. 
Tìm:
- Convention trong docs nhưng thiếu trong CLAUDE.md → nên add
- Instruction trong CLAUDE.md mâu thuẫn với docs → flag
- Thông tin duplicate cần consolidate

Output: markdown report, không auto-edit.

Anti-patterns — Những sai lầm cần tránh

Viết CLAUDE.md như brochure giới thiệu sản phẩm

Biểu hiện: dòng kiểu "This project is a revolutionary platform that empowers users to..."

Tại sao sai

Claude không cần marketing. Tốn token, không thay đổi hành vi.

Cách đúng

Văn phong "imperative" — câu lệnh ngắn, rõ: "Use pnpm, not npm. Tests live in __tests__/ folder."

Nhồi quá nhiều rule — không ưu tiên

Biểu hiện: CLAUDE.md 1200 dòng, bao gồm cả "lịch sử dự án", "kế hoạch roadmap Q3"...

Tại sao sai:

• Tốn 10-15% context window mỗi request
• Model có xu hướng bỏ qua instruction ở giữa file dài
• Update khó, ai cũng ngại sửa

Cách đúng:

• Giữ dưới 500 dòng (ideal 200-300)
• Priority: rule CRITICAL (security, compliance) → convention → preference
• Đẩy context dài xuống file riêng, dùng @ mention

Rule "negative" không có alternative

Biểu hiện: "Don't use callbacks." — dừng ở đó.

Tại sao sai

Claude biết không được dùng callback, nhưng giờ dùng gì? Promise? async/await? Generator?

Cách đúng

"Don't use callbacks. Use async/await. See @common/async-patterns.ts for examples."

Commit secrets hoặc path cá nhân

Biểu hiện: Project CLAUDE.md chứa /Users/john/.secrets/api.key hoặc DB password.

Tại sao sai: Commit vào Git = public với team. Với public repo = public với Internet.

Cách đúng:

• Secret/path cá nhân → CLAUDE.local.md (đã .gitignore)
• Mention vị trí secret chung → môi trường biến: "API key in env var ANTHROPIC_API_KEY"

Không update khi codebase thay đổi

Biểu hiện: CLAUDE.md vẫn nói "use React Router v5" trong khi team đã chuyển TanStack Router 3 tháng trước.

Tại sao sai: Claude làm theo rule cũ, bạn tốn thời gian sửa từng PR.

Cách đúng:

• Coi CLAUDE.md như code — đưa vào review checklist của PR lớn
• Khi migration xong, thêm task "update CLAUDE.md" vào định nghĩa "Done"
• Chạy định kỳ /review @CLAUDE.md để audit

Giả định model hiểu implicit

Biểu hiện: "Follow the standard pattern." (pattern nào?!)

Tại sao sai

"Standard" với team A khác team B. Claude đoán sai.

Cách đúng

Dẫn chứng cụ thể: "Follow the pattern in @src/api/users/route.ts as canonical example."

Mẹo nâng cao

Mẹo 1: Dùng section heading cho Claude scan nhanh

Thay vì block text dài, dùng heading ## Testing, ## Error Handling. Model tìm section liên quan dễ hơn, output focus hơn.

Mẹo 2: Versioning nhẹ

Thêm dòng đầu file: <!-- Last reviewed: 2026-04 — TL: @jimmy -->. Mỗi quý review lại, update ngày. Team biết file còn "sống".

Mẹo 3: Test CLAUDE.md như test code

Sau khi edit CLAUDE.md, restart Claude Code và chạy 2-3 prompt cụ thể để verify rule có được tuân không. Ví dụ:

Prompt test: "Thêm một endpoint CRUD cho entity Product."
Kỳ vọng: Claude dùng Drizzle (vì CLAUDE.md), không tự thêm comment 
thừa (vì CLAUDE.md), có test file colocated (vì CLAUDE.md).

Nếu Claude vi phạm → rule viết chưa đủ rõ, cần sửa.

Mẹo 4: Phân tầng rule theo độ nghiêm ngặt

CRITICAL (security/compliance — must not violate)

• ...

STRONG (team convention — violate only with approval)

• ...

PREFERENCE (stylistic — suggest but negotiable)

• ...

Giúp Claude biết rule nào "không được phép sai" vs "có thể uyển chuyển".

---

Áp dụng ngay

Bài tập 1: Bootstrap CLAUDE.md cho project thật của bạn (15 phút)

Bước 1

Mở một project đang làm trong Claude Code.

Bước 2

Chạy /init. Đợi Claude sinh CLAUDE.md.

Bước 3

Review file — trả lời trong note:

• Có rule nào thiếu mà bạn thường xuyên phải nhắc Claude không? ________
• Có thông tin nào sai/lỗi thời không? ________
• File dài bao nhiêu dòng? ________

Bước 4

Dùng memory mode (#) để bổ sung ít nhất 2 rule bạn nghĩ sẽ thay đổi hành vi Claude:

Bước 5

Thử prompt test — yêu cầu Claude làm việc tương tự trước khi và sau khi thêm rule. So sánh output.

Ghi lại:

• Rule có tác dụng ngay không: Có Không
• Thời gian trung bình cho 1 prompt task: _____ phút (trước) → _____ phút (sau)
• Số comment review cần sửa: _____ (trước) → _____ (sau)

Bài tập 2 (optional, 30 phút): Audit CLAUDE.md cũ

Nếu team bạn đã có CLAUDE.md vài tháng rồi, chạy prompt template #2 "Audit CLAUDE.md đang có" phía trên.

Output nên chứa:

• Danh sách instruction đề xuất xóa (duplicate, outdated, không actionable)
• Danh sách rewrite (vague → specific)
• Danh sách gap (convention team có nhưng CLAUDE.md chưa ghi)

Tạo một PR nhỏ để update. Commit message: docs(claude): audit and trim CLAUDE.md.

Tóm tắt bài học

Tài liệu tham khảo

• Claude Code quickstart — Anthropic Docs
• Claude Code best practices — Cal Rueb talk, Code w/ Claude 2025
• CLAUDE.md memory documentation
• Bài 4.4 — Cài đặt Claude Code (nếu chưa cài)
• Bài 4.8 — Điều khiển context (bổ sung kỹ năng quản lý context)