Skip to main content

Axis · Mistakes

🚫 Common Mistakes — 25 lỗi phổ biến + lesson tránh

Đọc trước khi học sâu. Tránh thắng đối thủ — bạn không phải người đầu tiên gặp những lỗi này.

Read before deep-diving. You're not the first to hit these.

🟢 Beginner-level (mistakes 1-8)

1. Hỏi câu cộc lốc, không context → output vô dụng

❌ "Viết email" ✅ "Viết email tiếng Việt formal cho khách hàng B2B, từ chối báo giá 3 tỷ vì vượt budget, vẫn giữ quan hệ cho lần sau, dài 4-6 câu"

2. Tin output ngay, không verify

AI hallucinate số liệu, citation, code. Phải đối chiếu nguồn.

3. Không upload file vào project

Bạn paste mỗi lần lại context dài → tốn token, dễ thiếu.

4. Dùng sai tool (Claude.ai cho task nhiều file)

Cần edit 20 file? Đừng copy-paste vào web — dùng Claude Code.

5. Hỏi "tại sao" trước "có thể không"

Hỏi Claude refine output trước, đừng tranh cãi với output đầu tiên.

6. Quên check Data & Privacy policy

Nhập data nhạy cảm vào free Claude.ai — Anthropic có thể dùng để train? (Không, nhưng nên đọc).

7. Không dùng Artifacts

Output dài, code → dùng artifacts để edit inline thay vì re-prompt.

8. Bỏ qua AI Fluency, nhảy thẳng vào tools

4D framework là khung tư duy. Skip = lặp lại sai lầm hệ thống.

🟡 Intermediate (Claude Code + light API)

9. Bỏ qua CLAUDE.md cho repo

Mỗi project khác → personality khác → CLAUDE.md per repo cứu bạn.

10. Dùng Claude Code không có git workflow

Không commit thường xuyên = mất rollback safety. Always commit before big refactor.

11. Skip "plan" step, vào code ngay

Plan trước = dev nhanh hơn. Skip plan → 3 lần fix wrong direction.

12. Hooks sai → run forever / chậm

Pre-commit hook chạy lint full repo = chậm. Scope đúng cần thiết.

13. Custom command không kebab-case → conflict

File naming inconsistent → Claude tìm không ra hoặc trùng.

14. Quên rate limit của API tier

Free tier có 5 RPM. Code synchronous loop → instant 429.

🟠 Advanced (API + Agents)

15. Không dùng prompt caching cho repeated context

Mỗi request resend system prompt 5K token = lãng phí 90% cost.

16. System prompt quá dài / quá generic

10K token system prompt làm Claude lú. Concise + role + constraints.

17. Tool definition mơ hồ → Claude gọi sai

JSON schema thiếu description, type → Claude guess.

18. Loop agentic không có exit condition

while-loop tool calls → infinite loop khi tool error. Phải có max_iterations.

19. RAG retrieve quá ít / quá nhiều chunk

Top-1 → miss context. Top-50 → noise. Sweet spot top-5 đến top-10 + rerank.

20. Không có eval, ship blind

Optimize prompt eyeballing → improve case A breaks case B. Cần test set.

21. Subagent dùng quá sớm

1 task đơn giản dùng subagent → overhead. Chỉ dùng khi context khổng lồ hoặc parallel.

22. Skill viết quá rộng, không reusable

"general-purpose-skill.md" 200 dòng → không ai dùng. Skill = 1 việc rõ ràng.

🔴 MCP-specific

23. Dùng stdio cho production multi-user

stdio = single process. Production cần HTTP/SSE.

24. MCP tool expose mà không auth → security hole

External MCP server → ai cũng gọi được tool nhạy cảm. Course không cover security riêng — đọc spec gốc.

25. Sampling không có rate limit guard

MCP server gọi Claude qua client → có thể loop infinite.

⚙️ Harness Engineering Mistakes

26. Viết một file instructions khổng lồ

  • Triệu chứng: Agent "lost in middle", bỏ sót quy tắc quan trọng
  • Fix: Progressive disclosure 3 tầng (entry 50-200 dòng → topic docs → inline comments)
  • Bài học: 19.04 Why One Giant Instruction File Fails

27. Chỉ dùng unit tests kiểm tra agent output

  • Triệu chứng: Mock tests pass nhưng integration/runtime fails
  • Fix: Three-layer validation (syntax → runtime → system-level) + E2E
  • Bài học: 19.09, 19.10

28. Tin agent khi nó nói "đã xong"

29. Cho agent làm 3+ tasks cùng lúc (WIP > 1)

  • Triệu chứng: 5 features started, 0 passing end-to-end
  • Fix: WIP=1 constraint + feature_list.json + completion evidence
  • Bài học: 19.07, 19.08

30. Không persist state giữa các phiên

  • Triệu chứng: Mỗi phiên mới phải re-explore project, mất thời gian
  • Fix: PROGRESS.md + DECISIONS.md + git checkpoints
  • Bài học: 19.05, 19.06

31. Bỏ qua cleanup cuối phiên

  • Triệu chứng: Build pass rate giảm 97%→68% sau 12 tuần, startup time tăng 5→60+ phút
  • Fix: Clean-state checklist, 5-dimension cleanup (build, tests, progress, artifacts, startup)
  • Bài học: 19.12 Why Every Session Must Leave Clean State

📋 Self-check: bạn có đang phạm lỗi nào không?

[ ] 1. Tôi viết prompt chi tiết hơn 30 từ?
[ ] 2. Tôi verify số liệu Claude trả về?
[ ] 3. Tôi dùng project + upload file thay vì paste?
[ ] 4. Tôi chọn tool dựa trên task (web/code/API)?
[ ] 5. Tôi lưu CLAUDE.md cho repo?
[ ] 6. Tôi commit trước khi cho Claude refactor lớn?
[ ] 7. Tôi dùng plan mode trước khi code?
[ ] 8. Tôi bật prompt caching cho repeated context?
[ ] 9. Tôi có eval pipeline?
[ ] 10. Tôi monitor rate limit + retry?

Càng nhiều check = càng productive với Claude.

🔁 Liên kết

Feedback / ReportSpotted an issue or have an improvement idea?