Viết CLAUDE.md dưới 1000 token: AI nhớ chính xác, cập nhật liên tục cho team

Định nghĩa

CLAUDE.md là file bộ nhớ dự án (project-scoped memory) của Claude Code — nơi lưu trữ quy tắc coding, kiến trúc hệ thống và context quan trọng được load vào đầu mỗi session. Khác với system prompt dài vô tận, CLAUDE.md chỉ load khi cần và tồn tại xuyên suốt các session, giúp AI "nhớ" chính xác yêu cầu dự án ngay cả khi context window bị compaction.

Giải thích chi tiết

Nguyên tắc "Dưới 1000 token": Ngắn gọn để AI không bị "ngộp"

Trong kiến trúc Progressive Disclosure của Claude Code, context được load theo 3 cấp độ: metadata (~100 tokens) luôn load, instructions (< 5k tokens) load khi trigger, và resources (unlimited) load qua bash. CLAUDE.md đóng vai trò như Level 1 — "table of contents" và "critical constraints" luôn hiện diện trong mọi turn.

Nếu CLAUDE.md dài 5000 token, mỗi lần AI trả lời phải "đọc lại" 5000 token này, làm giảm hiệu suất reasoning và tốn kém API — điều đặc biệt nhạy cảm với startup Việt Nam chạy trên budget hạn chế. Dưới 1000 token (khoảng 700-800 từ tiếng Việt) đảm bảo:

• Load nhanh: AI không mất thời gian parse documentation dài
• Focus cao: Chỉ giữ lại "hard constraints" — những quy tắc nếu vi phạm sẽ gây lỗi nghiêm trọng
• Dễ maintain: File ngắn dễ đọc, dễ sửa, team không ngại cập nhật

Cấu trúc chuẩn cho 1000 token:

1. Identity (100-150 tokens): AI đóng vai trò gì? (Senior React dev, Security auditor...)
2. Tech Stack (200-300 tokens): Ngôn ngữ, framework, thư viện bắt buộc
3. Critical Rules (400-500 tokens): Những điều KHÔNG ĐƯỢC quên (security, performance, business logic)
4. Update Log (50-100 tokens): Lịch sử thay đổi để track evolution

Kỹ thuật cấp nhật liên tục: Memory là "context cache", không phải tài liệu tĩnh

LLM agents giống như "những chú vàng mới có trí nhớ dài hạn" — chat history bị lossy compression sau khoảng 20 phút hội thoại, nhưng file-based memory (CLAUDE.md) sống sót. Do đó, CLAUDE.md phải được coi là context cache thay vì documentation tĩnh.

Quy trình cập nhật liên tục (continuous update):

• Daily micro-update: Sau mỗi bug fix quan trọng, thêm 1 dòng ghi chú vào CLAUDE.md. Ví dụ: "2024-03-15: Không dùng any trong TypeScript sau incident #123"
• Weekly refactor: Mỗi thứ 6, dành 10 phút review CLAUDE.md — xóa rules đã lỗi thời, thêm patterns mới phát hiện trong tuần
• Event-driven update: Khi có breaking change (upgrade Next.js 13→14, thay đổi database schema), update CLAUDE.md ngay lập tức trước khi viết code

Kỹ thuật # prefix: Trong conversation, dùng lệnh # để thêm rule tạm thời vào memory (ví dụ: # Luôn validate input bằng Zod). Nếu rule này hiệu quả sau 3-5 lần áp dụng, "promote" nó vào CLAUDE.md để trở thành permanent constraint.

Directory-scoped Memory: Chia nhỏ như cách Grab tách app Driver và Customer

Thay vì một CLAUDE.md toàn cục dài ngoằng cho cả monolith, chia nhỏ theo thư mục để giảm cognitive load — giống như Grab có codebase riêng cho app Driver và app Customer:

project-root/
├── CLAUDE.md (global: identity, shared conventions)
├── frontend/
│   └── CLAUDE.md (React, TypeScript strict, Tailwind rules)
├── backend/
│   └── CLAUDE.md (tRPC, Prisma, PostgreSQL patterns)
└── shared/
    └── CLAUDE.md (TypeScript interfaces, utilities)

Claude Code tự động load CLAUDE.md gần nhất trong hierarchy. Khi bạn làm việc ở frontend/, AI chỉ "nhớ" rules của frontend, không bị nhiễu bởi backend context — giải quyết vấn đề "context pollution" khi project có nhiều module với tech stack khác nhau.

Lợi ích của directory-scoped:

• Team parallelization: Developer A làm frontend (rules về UI/UX), Developer B làm backend (rules về API security) — cả hai dùng CLAUDE.md riêng không conflict
• Tech stack isolation: Frontend dùng Prettier với single quotes, backend dùng Black với double quotes — mỗi file CLAUDE.md ghi rõ convention riêng
• Incremental adoption: Thêm module mới không làm tăng độ phức tạp của file memory chính

Progressive Disclosure: Tách metadata ra khỏi implementation

Áp dụng kiến trúc 3 tầng của Agent Skills vào CLAUDE.md:

• Level 1 (Metadata): File CLAUDE.md chính luôn load, chỉ chứa "if you need X, look at Y"
• Level 2 (Instructions): File CLAUDE-ARCHITECTURE.md chỉ load khi AI hỏi về system design
• Level 3 (Resources): Scripts, templates trong .claude/resources/ — AI gọi qua bash khi cần, không load vào context

Ví dụ thực tế: Thay vì paste cả API documentation dài 2000 tokens vào CLAUDE.md, chỉ ghi:

"Khi implement API endpoint mới, xem patterns trong .claude/resources/api-templates.md và validate bằng script .claude/resources/validate-api.sh."

Điều này giữ CLAUDE.md dưới 1000 token trong khi vẫn cung cấp unlimited depth qua resource files.

Ví dụ thực tế

CLAUDE.md cho team 5 người làm SaaS hóa đơn điện tử Việt Nam

File nằm ở root, dưới 1000 token, cover đủ để AI hiểu context thuế VAT và tích hợp VietQR:

# VietInvoice - Project Memory

## Identity
Senior full-stack dev chuyên Next.js 14 + Prisma + PostgreSQL. Ưu tiên performance và type safety.

## Tech Stack
- Frontend: Next.js 14 (App Router), Tailwind, shadcn/ui, React Hook Form + Zod
- Backend: tRPC, Prisma ORM, PostgreSQL, Redis cho Bull Queue
- Payment: Tích hợp VietQR cho chuyển khoản ngân hàng, Stripe cho thẻ quốc tế
- Ngôn ngữ: Code tiếng Anh, comments tiếng Việt, UI text tiếng Việt chuẩn Unicode

## Critical Rules (KHÔNG ĐƯỢC VI PHẠM)
1. **Security**: Không bao giờ expose `user.password` trong API response, dù có select *
2. **Database**: Mọi query Prisma phải có `where: { deletedAt: null }` (soft delete bắt buộc)
3. **Thuế VAT**: Luôn tính VAT 10% vào giá hiển thị, không để client tự tính. Format tiền: "100.000 ₫"
4. **Error Handling**: API trả về `{ success: false, message: "Lỗi..." }`, không throw raw error cho client
5. **Ngày tháng**: Format DD/MM/YYYY theo chuẩn Việt Nam, không dùng US format (MM/DD/YYYY)

## Update Log
- 2024-03-15: Thêm rule soft delete sau incident xóa nhầm data của khách hàng
- 2024-03-10: Chuyển từ REST sang tRPC, update tech stack

Directory-scoped cho micro-frontend giống Shopee

Structure cho project có nhiều module (Seller Center vs Buyer App):

# File: apps/seller-center/CLAUDE.md
## Seller Center Specific
- Charts: D3.js v7 thuần, không dùng Recharts/Chart.js (bundle size optimization)
- Performance: Mọi component chart phải implement `React.memo` với custom comparator
- Real-time: Dùng SWR với polling interval 30s cho dashboard doanh thu, không dùng WebSocket (đơn giản hóa infra)
- Constraints: Bundle size < 200KB initial, Lighthouse performance > 90

## Cross-boundary Rules
- Không import trực tiếp từ `apps/buyer-app/` — chỉ dùng packages từ `shared/`
- Types chia sẻ qua `shared/types.ts`, không duplicate interfaces giữa seller và buyer
- API endpoints cho seller có prefix `/api/seller/`, phân quyền strict qua middleware

Workflow cập nhật liên tục sau incident

Sau khi phát hiện lỗ hổng "quên validate email dẫn đến SQL injection attempt":

1. Immediate fix: Trong session Claude Code, gõ # Luôn validate email bằng Zod trước khi query DB
2. Verify: Claude áp dụng rule mới cho 2-3 API endpoints tiếp theo, xác nhận hiệu quả
3. Commit to memory: Thêm vào CLAUDE.md dòng: "Validate tất cả inputs bằng Zod schema trước khi vào Prisma query"
4. Git commit: git add CLAUDE.md -m "security: add input validation rule post-incident #45"
5. Broadcast: Team pull về, AI của mọi người đều "nhớ" rule mới này ngay lập tức

Ứng dụng

Developer cá nhân (Freelancer)

Dùng CLAUDE.md để duy trì "coding personality" xuyên suốt các dự án. File ~/.claude/CLAUDE.md (user-scoped memory) chứa preferences cá nhân: "Tôi thích functional programming, tránh class-based OOP", "Luôn thêm JSDoc cho public functions", "Ưu tiên thư viện có bundle size nhỏ". Khi chuyển sang dự án mới cho khách hàng như FPT hay Tiki, AI vẫn nhớ bạn là "ai" và "thích gì", đảm bảo consistency trong portfolio cá nhân.

Team 5-10 người (Startup Việt Nam)

CLAUDE.md đóng vai trò "team constitution" — bộ luật chung mà AI áp dụng đồng đều cho cả team. Senior dev viết rules, junior dev và AI tuân thủ. Giảm "tribal knowledge" — không còn tình trạng "chỉ anh A mới biết tại sao phải làm vậy" vì rules đã được encode trong file. Phù hợp cho team làm sản phẩm thuần Việt với business logic phức tạp (tính thuế, quản lý kho theo FIFO/LIFO, CSKH qua Zalo OA).

PM/Non-coder

Dùng CLAUDE.md để đảm bảo AI generate code đúng business logic mà không cần biết syntax. Ví dụ: thêm rule "Luôn tính thuế VAT 8% hoặc 10% vào giá hiển thị cuối cùng tùy loại hàng hóa", "Ngày hiển thị format DD/MM/YYYY theo chuẩn Việt Nam, không dùng US format", "Mã đơn hàng phải có prefix VN- để phân biệt với đơn quốc tế". PM có thể tự edit CLAUDE.md bằng tiếng Việt, AI sẽ tuân thủ business rules này trong mọi implementation phần mềm.

Doanh nghiệp/Enterprise

Thiết lập hierarchy: Enterprise CLAUDE.md (security policies, compliance SOC2), Team CLAUDE.md (tech stack cụ thể), Project CLAUDE.md (business logic). Kết hợp với team-memory-setup để đồng bộ quy trình trên toàn tổ chức, đảm bảo AI assistant tuân thủ ISO 27001 khi generate code.

So sánh

Kết luận: CLAUDE.md không phải là documentation để đọc — nó là context cache cho AI. Giống như CPU cache nhỏ nhưng nhanh, CLAUDE.md phải nhỏ (under 1000 tokens) và chỉ chứa "hot data" (rules thay đổi hiếm nhưng quan trọng). Việc cập nhật liên tục biến file tĩnh thành "living document", phản ánh chính xác trạng thái hiện tại của project thay vì trạng thái lúc khởi tạo.

Bài viết liên quan

Cùng cụm (memory-system):

• 7 loại Memory trong Claude Code — Hiểu rõ sự khác biệt giữa Project, User, Auto Memory và vị trí của CLAUDE.md trong hierarchy tổng thể
• Memory theo thư mục: Context chỉ load khi cần — Kỹ thuật directory-scoped chi tiết để scale cho project lớn với nhiều module
• Thiết lập Memory cho team: Chuẩn hoá quy trình — Cách triển khai CLAUDE.md cho team 5+ người với git workflow và code review

Đọc tiếp (theo đề xuất trong ngữ cảnh cụm):

• Tạo Custom Skill đầu tiên: SKILL.md từ A đến Z — Mở rộng từ CLAUDE.md sang Skills system với progressive disclosure 3 tầng
• Tạo Custom Agent: .claude/agents/ từ đầu — Dùng subagents để phân chia context cho các module khác nhau, giảm tải cognitive cho CLAUDE.md chính