Tháng trước, tôi ngồi cạnh một senior engineer đã dùng Claude Code được ba tuần. Anh ấy frustrate lắm. “Tool này trả lời toàn rác,” anh nói. Tôi quan sát anh ấy làm việc 10 phút và nhận ra ngay 3 trong 5 lỗi dưới đây.

Anh ấy không phải engineer kém. Anh ấy rất giỏi. Nhưng Claude Code không giống những tool khác — cách bạn dùng nó quyết định hoàn toàn những gì bạn nhận lại. Sau khi làm việc với hàng trăm developer đang học Claude Code, tôi cứ thấy đi thấy lại cùng một pattern. Đây là 5 lỗi gây thiệt hại nhất, và cách sửa chỉ mất vài phút nhưng thay đổi kết quả hoàn toàn.

Lỗi 1: Đổ toàn bộ codebase vào context

Đây là lỗi phổ biến nhất, không ai thoát. Developer paste cả project vào prompt — hoặc reference mọi file trong repo — rồi thắc mắc sao Claude Code trả lời chung chung, không cụ thể.

Vấn đề nằm ở đây: Claude Code có context window. Lớn, nhưng không vô hạn. Càng nhiều noise, càng ít signal. Hãy nghĩ thế này — bạn có đưa cho đồng nghiệp 50,000 dòng code rồi bảo “fix bug đi” không? Tất nhiên không. Bạn sẽ chỉ cho họ file nào, function nào, thậm chí dòng nào.

Trên thực tế nó trông thế này:

❌ Prompt tệ:
"Đây là toàn bộ project. Có bug đâu đó trong auth flow. Fix đi."


✅ Prompt tốt:
"Xem @src/auth/login.ts — hàm handleLogin ở dòng 42.
Nó throw 500 khi email user có ký tự '+'.
Tôi nghĩ lỗi nằm ở regex dòng 58."

Chênh lệch chất lượng output rất lớn. Prompt tệ cho bạn một bài luận mơ hồ về authentication best practices. Prompt tốt cho bạn fix chính xác.

Cách sửa: Chính xác như phẫu thuật. Dùng @file để chỉ Claude Code vào đúng files cần thiết. Chỉ đưa 2-3 files liên quan đến task. Nếu cần context từ file khác, nói Claude Code xem function signatures hoặc types cụ thể — đừng đưa nguyên file.

Lỗi 2: Bỏ qua CLAUDE.md

Lỗi này đau nhất vì cách sửa quá dễ mà impact quá lớn.

Hãy tưởng tượng thuê một senior engineer tài năng mà không onboard gì cả. Không documentation. Không convention guide. Chỉ “đây là repo, bắt đầu code đi.” Mỗi pull request đều phải sửa — sai naming style, sai testing pattern, sai folder structure.

Đó chính xác là chuyện xảy ra khi bạn bỏ qua CLAUDE.md. Mỗi conversation mới, Claude Code bắt đầu từ con số 0. Nó không biết convention của project, preference của team, hay architectural decisions.

Không có CLAUDE.md:

Bạn: "Thêm endpoint mới cho user preferences"


Claude Code: *tạo route ở /routes/userPreferences.js
              dùng callbacks, khai báo var,
              đặt business logic thẳng trong route handler*

Có CLAUDE.md:

CLAUDE.md
## Conventions
- Files: kebab-case (user-preferences.ts)
- Routes → Services → Repositories pattern
- Business logic chỉ trong services/, không bao giờ trong routes/
- TypeScript strict mode, cấm `any`
- Tests mirror source: src/test/services/user-preferences.test.ts
Bạn: "Thêm endpoint mới cho user preferences"


Claude Code: *tạo route ở /routes/user-preferences.ts
              delegate sang UserPreferencesService,
              dùng TypeScript với types chuẩn,
              follow đúng patterns của project*

Cách sửa: Tạo file CLAUDE.md ở root project ngay bây giờ. Bắt đầu với 20 dòng — tech stack, top conventions, và một thứ Claude Code tuyệt đối không được làm. Mỗi lần Claude Code output sai, thêm correction vào CLAUDE.md. Sau một tháng, AI assistant sẽ hiểu project của bạn như một team member thực thụ.

Tôi viết chi tiết hơn ở đây: Tại sao CLAUDE.md là file quan trọng nhất.

Lỗi 3: Accept code mà không review

Claude Code rất giỏi. Giỏi đến mức tạo ra một cám dỗ nguy hiểm: cứ accept rồi đi tiếp.

Tôi đã thấy chuyện này burn developer theo 3 cách cụ thể:

  1. Edge cases tinh vi. Claude Code generate date parser hoạt động với format US nhưng âm thầm sai với format châu Âu. Tests pass vì data test toàn dùng US dates.

  2. Lỗ hổng bảo mật. Code chạy hoàn hảo nhưng không sanitize input, không check permissions, hoặc log data nhạy cảm. Nhìn qua thì đúng.

  3. Vi phạm patterns. Claude Code giải quyết đúng vấn đề nhưng theo cách khác với project — dùng state management khác, error handling style khác, file structure khác so với phần còn lại của codebase.

Không cái nào là bug của Claude Code. Chúng là giới hạn tự nhiên của bất kỳ AI nào không có đầy đủ context về requirements.

Cách sửa: Đối xử với output của Claude Code như pull request từ teammate tài năng nhưng mới vào team. Cụ thể:

  • Chạy tests. Nếu pass, viết thêm test cho edge case bạn lo ngại.
  • Check pattern. Code mới có follow cùng approach với code tương tự trong project không?
  • Review security. Input có được validate? Permissions có được check? Error handling có consistent không?

“Trust but verify” mất 2-3 phút mỗi task mà tiết kiệm hàng giờ debug. Senior engineer tôi kể ở đầu bài? Khi anh ấy bắt đầu review output trước khi accept, câu nói “tool này trả lời toàn rác” biến mất trong một ngày.

Lỗi 4: Viết prompt mơ hồ

“Fix login.”

Login nào? UI? API? Authentication flow? Session management? Error handling? Redirect sau login? Checkbox “nhớ mật khẩu”? OAuth integration?

Claude Code không đọc được suy nghĩ của bạn. Prompt mơ hồ → nó phải giả định. Đôi khi đúng. Thường thì sai. Rồi developer đổ lỗi cho tool.

Phổ chất lượng prompt:

❌ Tệ: "Fix login"


🟡 Tạm: "Fix login validation trong auth module"


✅ Tốt: "Trong src/auth/login.ts, hàm handleLogin không validate
email format trước khi gửi API. Thêm email validation dùng
regex pattern giống trong src/auth/register.ts dòng 23."


🌟 Xuất sắc: "Trong src/auth/login.ts, hàm handleLogin (dòng 42)
không validate email format trước khi gửi API.
Điều này gây lỗi 500 khi user nhập email sai format.
Thêm email validation dùng pattern giống register.ts (dòng 23).
Đồng thời thêm error message thân thiện matching
error toast pattern có sẵn trong src/components/ErrorToast.tsx."

Để ý: mỗi level thêm cái gì (email validation), ở đâu (file + dòng cụ thể), tại sao (gây lỗi 500), và làm thế nào (match patterns có sẵn).

Cách sửa: Trước khi gửi prompt nào, check xem bạn đã nói rõ cái gì, ở đâu, và tại sao chưa. Reference files cụ thể bằng @filename. Chỉ ra patterns bạn muốn follow. 30 giây viết prompt tốt hơn tiết kiệm 10 phút output sai và phải prompt lại.

Lỗi 5: Không dùng Plan Mode cho task phức tạp

Nhảy thẳng vào code generation cho refactoring phức tạp hay feature mới giống như xây nhà không có bản vẽ. Có thể may mắn. Nhưng khả năng cao là đập tường sửa lại sau.

Tôi học điều này theo cách đau nhất. Tôi bảo Claude Code “refactor payment system để support nhiều provider.” Nó lao thẳng vào code — thay đổi 12 files, break Stripe integration, và tạo ra circular dependency. Mất hai tiếng vứt đi.

Lần sau, tôi dùng Plan mode trước:

/plan Refactor payment system để support nhiều providers.
Hiện tại chỉ có Stripe (src/payments/stripe.ts).
Cần thêm PayPal và để mở cho providers khác.
Không đụng Stripe integration hiện tại cho đến khi
abstraction layer vững chắc.

Claude Code đưa ra plan 5 bước: tạo PaymentProvider interface, implement StripeProvider adapter đầu tiên, thêm PayPalProvider, tạo factory, rồi mới migrate code hiện tại. Nó nhận ra circular dependency risk trước khi viết một dòng code nào. Toàn bộ refactor mất 30 phút thay vì hai tiếng.

Khi nào dùng Plan mode:

  • Task ảnh hưởng hơn 2-3 files
  • Refactoring kiến trúc có sẵn
  • Feature mới tích hợp với nhiều phần của codebase
  • Bất cứ khi nào “sai hướng” sẽ tốn hơn 15 phút

Cách sửa: Tạo thói quen. Bắt đầu với Shift+Tab để vào Plan mode. Review plan. Điều chỉnh nếu cần. Rồi mới execute. Chỉ một thói quen này có thể tiết kiệm hàng giờ mỗi tuần.

Tổng kết

5 cách sửa này mất vài phút áp dụng nhưng thay đổi hoàn toàn chất lượng output:

  1. Chính xác với context — reference files cụ thể, không đưa cả project
  2. Tạo CLAUDE.md — 20 dòng tiết kiệm 20 giờ
  3. Review trước khi accept — đối xử output như PR từ teammate mới
  4. Viết prompt cụ thể — nói rõ cái gì, ở đâu, tại sao
  5. Dùng Plan mode — suy nghĩ trước khi code, đặc biệt với task phức tạp

Claude Code là force multiplier, nhưng chỉ khi bạn dùng đúng cách. Developer tận dụng tốt nhất không phải người nhiều kinh nghiệm nhất — mà là người xây đúng thói quen.

Muốn đi sâu hơn? Khóa học Claude Code Mastery cover tất cả — 16 phases, 64 modules, từ nền tảng đến full-auto multi-agent workflows. Phases 1-3 hoàn toàn miễn phí.

Nhận Claude Code Cheat Sheet miễn phí — 50+ commands trong một file PDF — khi đăng ký newsletter.