loc. logo

Cách Claude Code 'đọc' codebase

#Vấn đề: Agent không phải "thần" — nó không thấy hết code của bạn

Nhiều người mới dùng Claude Code cứ nghĩ agent đã "nhớ" toàn bộ codebase ngay từ đầu. Thực tế hoàn toàn khác.

Claude Code không load toàn bộ source code vào bộ nhớ. Khi bạn mở một session, agent chỉ biết những gì bạn mô tả trong prompt ban đầu — và nó sẽ đọc file theo nhu cầu khi bạn yêu cầu một task cụ thể.

Ví dụ, khi bạn hỏi:

Sửa bug trong hàm calculateTotal ở file order.ts

Agent sẽ lần theo file order.ts, đọc nội dung, rồi quyết định có cần đọc thêm file nào không (ví dụ types.ts để xem interface, hoặc utils.ts để xem helper). Nó không tự động đọc 500 file trong project của bạn.

Điều này có nghĩa: nếu bạn không cung cấp đủ context, agent sẽ "mù" — nó không biết file nào quan trọng, cấu trúc project ra sao, hay business logic nằm ở đâu.

#Context window là gì và tại sao nó quan trọng

Context window là lượng text tối đa mà Claude có thể "nhìn thấy" trong một lượt hội thoại. Think of nó như RAM — có giới hạn cứng.

Mỗi lần agent đọc một file, nội dung file đó chiếm chỗ trong context window. Mỗi lần bạn gửi tin nhắn, cả lịch sử hội thoại cũng chiếm chỗ. Càng nhiều file được đọc, càng nhiều message qua lại, context window càng đầy.

Đây là lý do vì sao một session dài (30+ phút, nhiều task) sẽ bắt đầu có hiện tượng:

  • Agent "quên" những gì bạn nói ở đầu session
  • Agent nhắc lại lỗi mà bạn đã sửa rồi
  • Agent gợi ý giải pháp mà bạn đã reject trước đó

Đây không phải bug — đó là context window bị đầy.

#Cách agent đọc file: on-demand reading

Claude Code sử dụng chiến lược đọc file on-demand (theo nhu cầu). Quy trình điển hình:

  1. Bạn gửi prompt: "Refactor hàm parseCSV trong src/data/parser.ts"
  2. Agent dùng tool Read để đọc parser.ts
  3. Agent thấy parseCSV import DataRecord từ types.ts → đọc thêm types.ts
  4. Agent thấy có test file parser.test.ts → có thể đọc để hiểu behavior
  5. Agent viết giải pháp, chỉ sửa file cần thiết

Agent không đọc README.md, package.json, hay 200 file khác không liên quan đến task.

Đây là điểm mạnh nhưng cũng là điểm yếu. Nếu bạn không nói rõ file nào cần sửa, agent phải tự "đoán" — và có thể đọc sai file hoặc bỏ sót file quan trọng.

#Anti-pattern: Paste toàn bộ file vào chat

Một sai lầm phổ biến của người mới: copy-paste toàn bộ nội dung file lớn (500+ dòng) vào prompt.

❌ ĐỪNG làm vậy:
"Đây là file database.ts (800 dòng). Hãy tìm và sửa bug trong phần connection pooling."
 
✅ NÊN làm vậy:
"Sửa bug connection leak trong file src/db/database.ts. Pool không release connection sau query timeout."

Khi bạn paste 800 dòng vào prompt, bạn đã tự tay lấp đầy context window của chính mình. Agent phải đọc lại 800 dòng đó mỗi khi bạn gửi message mới — context window phình to rất nhanh.

Thay vào đó, hãy để agent tự đọc file bằng tool Read. Agent chỉ đọc phần cần thiết, và bạn giữ được context window cho những message tiếp theo.

#Làm sao để prompt hiệu quả với codebase lớn

Nguyên tắc vàng: càng cụ thể, càng tốt.

Nói rõ file nào:

✅ "Sửa type error trong src/components/UserProfile.tsx, dòng 45"
❌ "Có lỗi ở đâu đó trong phần user"

Nói rõ hành động:

✅ "Thêm field `avatarUrl: string` vào interface User trong src/types/user.ts"
❌ "Cập nhật type cho phần user"

Nói rõ ràng scope:

✅ "Chỉ sửa file parser.ts, không đụng test"
❌ "Refactor phần parser"

Khi bạn cụ thể, agent biết chính xác cần đọc file nào, sửa ở đâu, và không lãng phí context vào những file không liên quan.

#Demo: Chạy thử trên một project mẫu

Hãy thử ngay. Mở terminal, vào một project bất kỳ, chạy Claude Code:

cd ~/my-project
claude

Thử prompt đầu tiên:

Đọc file package.json và cho biết project dùng framework gì, version bao nhiêu

Agent sẽ dùng tool Read để đọc đúng file package.json — không đọc thêm file nào khác. Bạn có thể thấy trong output rằng nó chỉ fetch đúng file bạn yêu cầu.

Giờ thử prompt rộng hơn:

Tìm tất cả file có chứa hàm validateEmail trong src/

Agent sẽ dùng tool Grep hoặc Glob để search, rồi lần lượt đọc các file match. Lúc này context window bắt đầu chứa nhiều nội dung hơn.

⚠️ Cẩn thận: Nếu project của bạn có file lớn (generated code, lock files, minified JS), hãy thêm chúng vào .gitignore hoặc .claudeignore để agent không vô tình đọc phải. File generated 10.000 dòng sẽ nuốt chửng context window của bạn trong một nốt nhạc.

#Một số mẹo giữ context window sạch

  1. Mỗi session chỉ nên giải quyết 1-2 task liên quan. Đừng cố làm "tất cả trong một session."

  2. Sau khi hoàn thành task, dùng /clear để reset context trước khi chuyển sang task mới (bài tiếp theo sẽ nói kỹ hơn).

  3. Đừng hỏi lại agent về code mà bạn đã paste trước đó. Nếu cần tham khảo, hãy nói "đọc lại file X" thay vì paste lại nội dung.

  4. Sử dụng CLAUDE.md để ghi lại những thông tin quan trọng về project — agent sẽ tự động đọc file này mỗi session mà không tốn context window của bạn (vì nó được load ở system prompt).

  5. Tránh commit message dài khi dùng agent — mỗi lần commit, message cũng chiếm context.

#Bài tập thực hành

#Bài tập 1: Quan sát cách agent đọc file

Mở Claude Code trong một project bất kỳ. Gửi prompt sau:

Đọc file tsconfig.json (hoặc package.json nếu không có tsconfig) và tóm tắt nội dung chính

Quan sát output: agent dùng tool gì? Đọc bao nhiêu file? Ghi lại kết quả.

#Bài tập 2: So sánh prompt cụ thể vs mơ hồ

Thử hai prompt trong cùng một session (dùng /clear giữa hai lần):

  • Lần 1 (mơ hồ): "Có lỗi type ở phần nào đó trong src/"
  • Lần 2 (cụ thể): "Tìm lỗi TypeScript trong src/components/ và liệt kê file + dòng bị lỗi"

So sánh: lần nào agent đọc ít file hơn? Lần nào cho kết quả chính xác hơn?

#Bài tập 3: Test với file lớn

Tìm một file lớn trong project (200+ dòng). Paste toàn bộ nội dung vào prompt, rồi hỏi agent sửa một lỗi nhỏ trong đó. Ghi lại: context window tăng bao nhiêu? (Nếu dùng Claude Max, bạn có thể thấy indicator ở cuối terminal.)

Sau đó dùng /clear, và lần này chỉ nói "Sửa lỗi X trong file Y, dòng Z" — không paste gì cả. So sánh hiệu quả.

#Tổng kết

Claude Code đọc codebase theo nhu cầu, không load tất cả cùng lúc. Context window là tài nguyên hữu hạn — mỗi file đọc, mỗi message gửi, đều chiếm chỗ. Cách tốt nhất để làm việc hiệu quả: cụ thể trong prompt, để agent tự đọc file, và quản lý context window chủ động.

Bài tiếp theo sẽ đi sâu vào các công cụ cụ thể để quản lý context: /clear, /compact, và cách chia task lớn thành nhiều session nhỏ.