Team Memory trong Claude Code: Đồng bộ 'bộ não' AI cho cả nhóm

Cách thiết lập CLAUDE.md và hệ thống memory chia sẻ cho team 5-10 người, chuẩn hoá AI coding với directory-scoped context và progressive disclosure.

Định nghĩa

Team memory là hệ thống file CLAUDE.md và skill được đồng bộ qua Git, cho phép cả team chia sẻ cùng một "bộ não" AI về coding standards và kiến trúc hệ thống. Thay vì mỗi người phải dạy lại Claude từ đầu mỗi session, bạn biến kiến thức tác nghiệp thành "infrastructure as code" — version controlled, review được, và tự động inject vào context.

Giải thích chi tiết

Ba tầng memory và phân quyền cho team

Claude Code dùng ba tầng scope khác biệt. Trong môi trường team, ranh giới này quyết định sự hợp tác suôn sẻ hay hỗn loạn:

User scope (~/.claude/memory/): Chứa preferences cá nhân — theme, coding style riêng, alias shell. Mỗi dev tự quản lý, không commit lên Git.
Project scope (.claude/ hoặc CLAUDE.md ở root): Team memory chính. File này được commit vào repo, chứa stack, conventions và domain knowledge chung. Đây là "source of truth" cho cả nhóm.
Local scope: Session tạm thời, dùng cho dữ liệu nhạy cảm hoặc thử nghiệm không cần lưu.

Quy tắc vàng để không gây conflict: Personal ở local, Team ở Git, Session ở RAM.

Directory-scoped memory: Frontend vs Backend

Điểm mạnh của team memory là khả năng chia nhỏ theo thư mục (directory-scoped). Thay vì một file CLAUDE.md khổng lồ ở root, bạn tạo nhiều file nhỏ trong từng module — kiểu như cách Grab chia nhỏ context cho từng microservice:

vietqr-banking-app/
├── CLAUDE.md              # Team memory: API contracts chuẩn VietQR, auth flow
├── frontend/
│   └── CLAUDE.md          # Memory riêng: React hooks rules, Tailwind config, i18n
├── backend/
│   └── CLAUDE.md          # Memory riêng: FastAPI patterns, PostgreSQL migration rules
└── shared/
    └── CLAUDE.md          # Memory chung: Pydantic models, validation logic

Khi bạn chạy Claude trong thư mục frontend/, nó tự động load cả CLAUDE.md gốc lẫn frontend/CLAUDE.md, nhưng ưu tiên nội dung cục bộ. Dev không cần prefix mọi prompt bằng "nhớ rằng frontend dùng React còn backend dùng FastAPI" — AI tự hiểu ngữ cảnh từ vị trí thư mục.

Progressive disclosure: Không load thừa

Team memory dùng kiến trúc progressive disclosure (tiết lộ từ từ) để tránh nghẹt context window:

Level 1 (Metadata): Chỉ ~100 token mô tả skill có sẵn, luôn load để Claude biết "có gì trong nhà".
Level 2 (Instructions): Load khi cần. Ví dụ: khi dev gõ /security-review, Claude mới inject 5k token hướng dẫn audit vào context.
Level 3 (Resources): Script và template được gọi qua bash mà không cần đọc nội dung vào context.

Cách này giúp team có hàng chục quy trình phức tạp (coding standards, security checklist, deployment runbook) mà context window vẫn nhẹ nhàng, chỉ load đúng thứ cần dùng.

Chuẩn hoá với Slash Commands và Skills

Ngoài CLAUDE.md, team memory bao gồm Slash Commands trong .claude/commands/ và Skills trong .claude/skills/. Đây là cách "đóng gói" quy trình thành lệnh tái sử dụng:

/pr-review: Chạy checklist review chuẩn của team (AI đọc diff, check theo tiêu chí đã định sẵn trong skill).
/onboarding: Giải thích kiến trúc dự án cho thành viên mới dựa trên CLAUDE.md và code hiện tại.
/deploy-check: Xác nhận đã đủ test, migration, changelog trước khi merge.

Các file này được commit lên Git, đảm bảo dùng máy tính nào — từ laptop cá nhân đến máy ở công ty — cũng có cùng công cụ AI.

Ví dụ thực tế

Startup fintech 5 người: Đồng bộ ngay lập tức

Team bạn vừa tuyển thêm 2 dev mới cho app ví điện tử. Thay vì học "coding style của công ty" qua 10 buổi lunch-and-learn, bạn tạo file .claude/CLAUDE.md ở root:

# VietQR Payment SDK - Team Memory

## Stack
- Frontend: Next.js 14, Tailwind, Zod validation, React Query
- Backend: FastAPI, PostgreSQL, SQLAlchemy 2.0, Redis
- Auth: NextAuth v5 with JWT, refresh token rotation

## Conventions bắt buộc
- Tên bảng tiếng Việt không dấu trong DB (vi_don_hang), camelCase trong TypeScript
- Mọi API endpoint phải có Zod schema validation
- Không dùng `any` type, luôn define interface
- Logic tính phí giao dịch VietQR phải ở `backend/payments/vietqr.py`, không scatter
- Luôn log transaction_id cho debug

Dev mới clone repo, mở Claude Code, và ngay lập tức AI biết rằng "tên bảng là tiếng Việt không dấu" và "logic VietQR nằm ở đâu". Họ không cần hỏi lại senior dev về location của business logic hay cách đặt tên biến.

E-commerce nhiều module: Context phù hợp từng team

Dự án Tiki-like có 3 module: mobile-app/, seller-dashboard/, recommendation-engine/. Mỗi team dùng stack khác nhau (Flutter, React, Python/PyTorch).

Bạn tạo 3 file CLAUDE.md riêng biệt:

mobile-app/CLAUDE.md: "Sử dụng Flutter 3.22, state management Riverpod, không dùng setState trong production code, tuân thủ Material Design 3."
seller-dashboard/CLAUDE.md: "Dùng React Server Components mặc định, chỉ dùng 'use client' cho interactive elements, styling dùng Ant Design."
recommendation-engine/CLAUDE.md: "Python 3.11, Pydantic v2, logging dùng structlog, không print raw, model serving dùng FastAPI."

Khi ML engineer chuyển sang fix bug trên mobile, họ chỉ cần cd mobile-app và Claude tự điều chỉnh suggestions phù hợp với Flutter patterns thay vì gợi ý code Python hay hỏi "tại sao không dùng pandas".

Standardized code review qua Skill

Team tạo file .claude/skills/security-audit/SKILL.md với YAML frontmatter:

name: security-audit
description: Audit code cho SQL injection và XSS theo checklist OWASP Top 10 Việt Nam
autoInvoke: ["review", "check security"]

Nội dung skill chứa checklist 20 điểm kiểm tra bảo mật riêng của công ty — ví dụ "Kiểm tra xác thực VietQR signature", "Validate số tiền không âm", "Escape HTML trong description sản phẩm". Khi dev gõ /review hoặc đơn giản nhắc "check security", Claude tự động load toàn bộ checklist này vào context và scan code theo đúng tiêu chuẩn đã được lead engineer approve từ trước.

Ứng dụng

Team Lead / Tech Lead Dùng team memory để enforce architectural decisions mà không cần micromanage. CLAUDE.md đóng vai trò "senior dev ảo" luôn đứng bên cạnh junior, nhắc nhở conventions trước khi code được viết.

Senior Developers Encode tribal knowledge vào file memory thay vì giữ trong đầu. Khi bạn nghỉ phép Tết hoặc chuyển dự án, kiến thức vẫn nằm trong repo cho đồng đội query qua AI.

Junior Developers / Intern Onboarding nhanh gấp 3 lần. Thay vì đọc wiki dài 50 trang, họ dùng Claude để hỏi trực tiếp về codebase, với AI đã được "pre-load" context về kiến trúc và best practices của team.

Product Managers Handoff requirement hiệu quả hơn. PM viết context về user persona và business rules vào CLAUDE.md trong thư mục features/gio-hang/ (giỏ hàng), dev implement với AI luôn hiểu đúng "tại sao" đằng sau feature, không chỉ "cái gì".

DevOps / Platform Teams Chuẩn hoá deployment workflow. Tạo skill /deploy chứa toàn bộ runbook: check health, verify migration, rotate secrets. Mọi dev deploy đều tuân thủ cùng một quy trình được AI guide, tránh lỗi "trên máy tôi chạy được".

So sánh: Team Memory vs Individual Memory

Tiêu chí	Team Memory (Shared)	Individual Memory (Personal)
Location	`.claude/` trong Git repo	`~/.claude/` thư mục cá nhân
Scope	Dự án, chia sẻ giữa members	User, chỉ áp dụng cho cá nhân
Nội dung	Coding standards, API contracts, business logic	Editor preferences, aliases cá nhân, shell habits
Đồng bộ	Qua Git, version controlled	Không đồng bộ, local only
Ví dụ	"Luôn dùng Zod validate input", "BHXH tính theo công thức X"	"Tôi thích theme dark", "Dùng 2 spaces thay vì tab"

Kết luận: Team memory là "infrastructure as code" cho quy trình phát triển. Nó biến kiến thức tác nghiệp thành file có thể version control, review và tự động inject vào AI assistant, giúp team scale mà không lo về context switching hay kiến thức bị mất khi người rời đi.