Cách sử dụng Claude Code với nhiều repository mà không mất ngữ cảnh

Nếu bạn làm việc trên nhiều repository — một frontend, một backend, một thư viện dùng chung — bạn chắc chắn đã trải qua sự khó chịu này: Claude Code bị mất dấu dự án bạn đang làm, quên các quy ước từ repository khác, và bạn dành nửa thời gian phiên làm việc để giải thích lại những thứ nó đã biết.

Dưới đây là cách khắc phục vấn đề này.

Vấn đề cốt lõi: Claude Code chỉ có một cửa sổ ngữ cảnh

Claude Code không có bộ nhớ liên tục (persistent memory) giữa các phiên làm việc hoặc giữa các repository. Khi bạn mở một dự án mới, nó bắt đầu lại từ đầu. Khi bạn chuyển từ repository API sang repository frontend giữa chừng, ngữ cảnh từ repository đầu tiên không tự động chuyển sang.

Vấn đề này trở nên nghiêm trọng khi:

• API và frontend của bạn chia sẻ các kiểu dữ liệu (types) nhưng nằm ở các repository khác nhau.
• Bạn cần thực hiện các thay đổi phối hợp trên cả hai repository cùng lúc.
• Quy ước của backend khác với quy ước của frontend.
• Bạn đang thực hiện việc di chuyển (migration) chạm đến nhiều codebase.

Giải pháp 1: Chiến lược chia sẻ CLAUDE.md

Tạo một tệp CLAUDE.md ở cấp độ gốc (root-level) trong mỗi repository để tham chiếu chéo đến repository kia:

# API Repo - CLAUDE.md

## Dự án này
REST API sử dụng Node.js + Express + PostgreSQL
Auth: JWT tokens, 15min access / 7day refresh

## Đi kèm với: frontend repo tại ../frontend
Frontend mong đợi:
- Tất cả phản hồi API: { data: ..., error: null } hoặc { data: null, error: "message" }
- Định dạng ngày: Chuỗi ISO 8601 (không dùng timestamp)
- Header xác thực: Bearer {accessToken}

## Các kiểu dữ liệu chia sẻ
Xem ../shared-types/index.ts cho các giao diện TypeScript
Bất kỳ thay đổi API nào ảnh hưởng đến hình dạng phản hồi PHẢI cập nhật shared-types trước

Và trong phần frontend:

# Frontend Repo - CLAUDE.md

## Dự án này
Next.js 14 + TypeScript + Tailwind

## Đi kèm với: API repo tại ../api
URL cơ sở của API: http://localhost:3001
Tất cả lệnh fetch sử dụng: src/lib/api.ts (không gọi fetch trực tiếp)
Xử lý lỗi: kiểm tra trường error trên phản hồi, không bao giờ dùng .catch() một mình

## Khi thực hiện thay đổi API
1. Kiểm tra ../api/CLAUDE.md để biết định dạng phản hồi
2. Cập nhật src/types/ để khớp với bất kỳ thay đổi schema nào
3. Cập nhật src/lib/api.ts nếu thêm endpoint mới

Bây giờ khi Claude Code đọc tệp CLAUDE.md của bạn, nó sẽ ngay lập tức hiểu mối quan hệ chéo giữa các repository.

Giải pháp 2: Tệp chuyển giao ngữ cảnh (context handoff)

Khi bạn đang tích cực làm việc trên nhiều repository, hãy tạo một tệp tạm thời CONTEXT.md tại gốc không gian làm việc (workspace root):

workspace/
  CONTEXT.md      ← Claude đọc cái này đầu tiên
  api/
  frontend/
  shared-types/

# Ngữ cảnh công việc đang hoạt động - 2026-04-08

## Nhiệm vụ hiện tại
Thêm tính năng tải lên ảnh đại diện người dùng
- Thay đổi API: POST /api/users/avatar, trả về { avatarUrl: string }
- Thay đổi Frontend: ProfilePage.tsx cần nút tải lên + xem trước
- Cơ sở dữ liệu: Đã thêm cột avatar_url vào bảng users (migration đã chạy)

## Trạng thái
- [x] Migration cơ sở dữ liệu xong
- [x] Endpoint API xong (api/src/routes/users.js)
- [ ] Component tải lên frontend (tiếp theo: frontend/src/components/AvatarUpload.tsx)
- [ ] Kết nối đến ProfilePage

## Các ràng buộc cần nhớ
- Kích thước tệp tối đa: 5MB (thực thi trong API, cũng xác thực trong frontend)
- Các loại được chấp nhận: chỉ image/jpeg, image/png, image/webp
- Mẫu URL CDN: https://cdn.example.com/avatars/{userId}.{ext}

Bắt đầu mỗi phiên Claude Code bằng lệnh: "Đọc CONTEXT.md trước, sau đó chúng ta tiếp tục".

Giải pháp 3: Chạy các phiên bản song song với ranh giới rõ ràng

Đối với các nhiệm vụ chéo nhiều repository lớn, hãy chạy hai phiên Claude Code đồng thời:

# Terminal 1 - Công việc API
cd /workspace/api
claude

# Terminal 2 - Công việc Frontend  
cd /workspace/frontend
claude

Gán cho mỗi phiên một trách nhiệm duy nhất:

• Phiên bản API: "Bạn chịu trách nhiệm cho các thay đổi backend. Xuất ra hình dạng phản hồi chính xác khi bạn xong."
• Phiên bản Frontend: "API sẽ trả về hình dạng X. Bạn chịu trách nhiệm cho frontend. Đừng sửa tệp API."

Sau đó tổng hợp bằng cách đưa đầu ra từ cái này sang cái kia.

Giải pháp 4: Mẫu tệp hợp đồng (contract file)

Đối với các dự án nhiều repository đang diễn ra, hãy tạo một tệp hợp đồng API rõ ràng mà cả hai repository đều tham chiếu:

// shared-types/contract.ts
// NGUỒN CHÂN LÝ - cả hai repo đều nhập từ đây

export interface ApiResponse {
  data: T | null;
  error: string | null;
  timestamp: string; // ISO 8601
}

export interface User {
  id: string;
  email: string;
  avatarUrl: string | null;
  createdAt: string;
}

export interface AuthTokens {
  accessToken: string;  // hết hạn: 15 phút
  refreshToken: string; // hết hạn: 7 ngày
}

Cả hai tệp CLAUDE.md đều tham chiếu hợp đồng này:

## Hợp đồng chia sẻ
Xem ../shared-types/contract.ts — đây là nguồn chân lý.
Không bao giờ nhân bản định nghĩa kiểu. Nhập từ shared-types.

Khi Claude Code đọc tệp CLAUDE.md của bạn và sau đó kiểm tra shared-types/contract.ts, nó sẽ hiểu toàn bộ hệ thống mà bạn không cần giải thích bất cứ điều gì.

Vấn đề giới hạn tốc độ (Rate limit)

Thách thức thực sự với công việc đa repository: bạn tiêu thụ ngữ cảnh RẤT NHANH.

Giải thích hai repository, quy ước của chúng, các kiểu chia sẻ, nhiệm vụ đang hoạt động — đó là rất nhiều token trước khi bạn viết một dòng code. Khi bạn làm việc trên 3+ repository, bạn có thể chạm đến giới hạn tốc độ giữa chừng nhiệm vụ.

Biến môi trường ANTHROPIC_BASE_URL cho phép bạn trỏ Claude Code đến một endpoint API khác:

export ANTHROPIC_BASE_URL=https://simplylouie.com/api/proxy
claude

SimplyLouie hoạt động với giá khoảng 2$/tháng (so với 200$ cho Claude Max) và được xây dựng đặc biệt cho các nhà phát triển chạy các phiên dài với ngữ cảnh nặng. Proxy này xử lý trần giới hạn tốc độ để các phiên đa repository của bạn không bị cắt đứt giữa chừng.

Quy trình làm việc thực tế hiệu quả

1. Trước khi bắt đầu: Viết CONTEXT.md với nhiệm vụ hiện tại, trạng thái, ràng buộc.
2. Mỗi phiên: claude → "Đọc CONTEXT.md và CLAUDE.md trước".
3. Khi chuyển repository: Cập nhật CONTEXT.md với những gì bạn vừa hoàn thành.
4. Đối với các thay đổi phối hợp: Chạy các phiên song song với ranh giới rõ ràng.
5. Đối với các kiểu chia sẻ: Giữ một tệp hợp đồng mà cả hai CLAUDE đều tham chiếu.

2 phút thêm dành cho việc viết CONTEXT.md sẽ tiết kiệm 20 phút giải thích lại. Và với một endpoint API ổn định không giới hạn tốc độ giữa phiên, bạn thực tế có thể hoàn thành các nhiệm vụ chéo repository trong một lần ngồi.