Directory-scoped Memory trong Claude Code: Context chỉ load khi cần

Định nghĩa

Directory-scoped memory là cơ chế để Claude Code tự động thay đổi tính cách tùy theo thư mục bạn đang đứng. Vào frontend/ thì nó là chuyên gia React, sang backend/ thì hóa thành Pythonista — chỉ bằng cách load CLAUDE.md khác nhau cho từng nơi, đảm bảo context chỉ xuất hiện khi cần thiết thay vì nhồi nhét toàn bộ dự án vào prompt.

Giải thích chi tiết

Nguyên lý Progressive Disclosure

Claude Code sử dụng kiến trúc three-level loading để quản lý memory hiệu quả như một thủ thư tổ chức sách:

• Level 1 (Metadata): Tên và mô tả skill/memory luôn sẵn sàng (chỉ ~100 tokens), đóng vai trò như "mục lục" để Claude biết có gì trong thư viện.
• Level 2 (Instructions): Nội dung chi tiết của CLAUDE.md chỉ load khi bạn làm việc trong thư mục đó (dưới 5k tokens).
• Level 3 (Resources): Script, template, hoặc file reference được gọi qua bash tool khi thực sự cần thiết, không chiếm chỗ trong context window.

Điều này khác biệt với cách "mega-prompt" truyền thống — nơi toàn bộ quy tắc dự án được dump vào system prompt, làm loãng attention mechanism của model và khiến AI dễ "lú" giữa các tech stack khác nhau.

Cấu trúc Hierarchy

Directory-scoped memory hoạt động theo thứ tự ưu tiên như một bộ lọc thông minh:

1. Directory scope: ./frontend/CLAUDE.md hoặc ./backend/CLAUDE.md — context đặc thù cho module
2. Project scope: ./CLAUDE.md (root) — quy tắc chung cho cả dự án
3. User scope: ~/.claude/CLAUDE.md — preference cá nhân xuyên suốt các project

Khi bạn cd vào ./frontend/, Claude chỉ load memory của frontend + project root + user scope. Nếu chuyển sang ./backend/, context frontend tự động "biến mất" khỏi working memory, được thay thế bởi backend patterns. Không cần restart, không cần gõ lệnh — chỉ cần di chuyển thư mục.

Tác dụng của Context Isolation

Mỗi thư mục con có thể định nghĩa quy tắc riêng biệt:

• Tech stack riêng: React hooks patterns trong frontend/ vs FastAPI dependency injection trong backend/
• Coding standards khác nhau: CamelCase cho JavaScript, snake_case cho Python, PascalCase cho Go
• Safety rules: backend/ cho phép migration scripts, frontend/ chỉ cho phép styling changes, infra/ yêu cầu double-check terraform plan

Điều này ngăn chặn hiện tượng "context pollution" — khi Claude đang debug CSS lại nhớ nhầm quy tắc SQL từ phần backend, gây ra suggestions lẫn lộn như gợi ý dùng map() trong Python hoặc list comprehension trong React.

Ví dụ thực tế

Monorepo sàn thương mại điện tử (Shopee/Tiki style)

ecommerce-platform/
├── CLAUDE.md              # Architecture: micro frontend, event-driven, Conventional Commits
├── mobile-app/
│   ├── CLAUDE.md          # Flutter 3.16+, Riverpod, BLoC pattern, VietQR integration
│   └── src/
├── seller-center/
│   ├── CLAUDE.md          # React 18, Ant Design, Upload component xử lý ảnh >10MB, i18n (vi/en/zh)
│   └── src/
└── logistics-api/
    ├── CLAUDE.md          # Go 1.21+, Gin framework, giao tiếp với đơn vị vận chuyển (Giao Hàng Nhanh, Viettel Post)
    └── src/

Kết quả: Developer làm tính năng "Flash Sale" trong ./mobile-app/ không bao giờ thấy context về API logistics phức tạp. Claude chỉ tập trung vào Flutter animations và state management. Khi chuyển sang sửa API tích hợp đơn vị vận chuyển trong ./logistics-api/, context mobile app tự động ẩn, thay vào là Go error handling patterns và cấu trúc webhook.

Hệ sinh thái Fintech đa tầng (MoMo/ViettelPay style)

Dự án ví điện tử với yêu cầu bảo mật và compliance khác nhau giữa các tầng:

• ./mobile-banking/CLAUDE.md: "Flutter, bắt buộc biometric auth cho transfer >2 triệu, offline-first với SQLite encryption, tuân thủ SBV (State Bank of Vietnam) mobile banking guidelines"
• ./core-banking/CLAUDE.md: "Java Spring Boot, ACID transactions bắt buộc, audit log không được xóa, integration với NAPAS, ISO 8585 message format"
• ./fraud-detection/CLAUDE.md: "Python 3.11, scikit-learn/pandas, real-time inference pipeline, feature engineering cho transaction velocity, không được log sensitive PII"

Developer mobile không bị "ngộp" bởi ràng buộc ACID phức tạp khi làm UI. Data scientist trong ./fraud-detection/ không thấy Flutter widget rules mà chỉ thấy ML pipeline patterns.

Studio phát triển đa dự án

Freelancer hoặc agency tại TP.HCM quản lý nhiều client trong cùng một workspace:

~/workspace/
├── client-fintech/
│   ├── CLAUDE.md          # Next.js 14, Prisma, PostgreSQL, strict TypeScript, deployment trên Vercel
│   └── src/
├── client-ecommerce/
│   ├── CLAUDE.md          # Laravel 10, MySQL, jQuery legacy + Vue 3 migration, deployment trên cPanel Việt Nam
│   └── src/
└── client-blog/
    ├── CLAUDE.md          # Astro, MDX, Tailwind, static export, Cloudflare Pages
    └── src/

Chuyển đổi giữa các dự án chỉ bằng cd ../client-fintech hoặc cd ../client-ecommerce. Directory-scoped memory tự động swap context — bạn không cần nhớ lại "client này dùng Vue hay React" vì CLAUDE.md đã nói hộ bạn, ngăn lỗi "nhầm nhà" như gợi ý dùng Laravel Eloquent trong project Next.js.

Ứng dụng

Developer đơn lẻ (Indie hacker) Tổ chức side projects khác nhau trong cùng một ~/projects lớn. Mỗi thư mục con có CLAUDE.md riêng định nghĩa tech stack (Django vs Node.js vs Rust), tránh nhầm lẫn cú pháp khi chuyển nhanh giữa các ý tưởng startup khác nhau.

Tech Lead quản lý monorepo Thiết lập "cognitive boundaries" cho từng squad. Frontend squad nhìn thấy design system tokens, backend squad nhìn thấy API contracts, DevOps squad nhìn thấy Terraform modules — nhưng không ai bị overload bởi context của squad khác. Giảm thiểu lỗi "dùng nhầm convention" khi developer rotate giữa các module.

Freelancer làm việc với nhiều client Không còn tình trạng nhớ nhầm "client A dùng camelCase hay snake_case" hay "client B yêu cầu semicolon hay không". Mỗi dự án là một thư mục với personality riêng, giúp chuyển context nhanh chóng giữa các công nghệ và quy ước khác nhau mà không cần đọc lại documentation.

So sánh

Kết luận: Directory-scoped memory là giải pháp trung gian hoàn hảo giữa "quá ít context" (session-only) và "quá nhiều context" (global everything). Nó cho phép dự án scale lên hàng chục module với các tech stack khác nhau mà không làm đầy context window 200k tokens của Claude, đồng thời giữ cho AI "tập trung" vào đúng vấn đề hiện tại.

Bài viết liên quan

Cùng cụm

• 7 loại Memory trong Claude Code — Hiểu rõ hơn về hierarchy memory từ Project đến User scope
• CLAUDE.md best practices — Cách viết file memory hiệu quả, dưới 1000 token, cập nhật liên tục
• Thiết lập Memory cho team — Chuẩn hóa quy trình cho team 5 người trở lên

Đọc tiếp

• Tạo Custom Skill đầu tiên — Kết hợp directory memory với skills để tạo workflow chuyên biệt cho từng module
• Tạo Custom Agent — Dùng subagents với directory-scoped memory riêng để xử lý task song song mà không pollute main context