Best Practices — Hướng dẫn thực hành
Tổng hợp kinh nghiệm sử dụng Claude Code skills hiệu quả — từ nguyên tắc cơ bản đến workflow nâng cao cho team.
Trang này là reference chính cho team mới onboarding và team hiện tại cải thiện workflow. Bookmark lại!
1. Nguyên tắc vàng
4 nguyên tắc bất di bất dịch khi dùng Claude Code:
| # | Nguyên tắc | Lý do |
|---|
| 1 | Luôn plan trước khi code | Plan mất 30 giây, skip plan mất 30 phút debug |
| 2 | Diagnose trước khi fix | Fix triệu chứng → bug quay lại. Fix root cause → xong hẳn |
| 3 | Test trước khi ship | Code không có test = code chưa xong |
| 4 | Review trước khi merge | Thêm 1 đôi mắt = bớt 10 bugs trên production |
Không có ngoại lệ cho 4 nguyên tắc trên — kể cả “hotfix gấp” hay “task nhỏ xíu”.
2. Anti-patterns — Sai lầm phổ biến
Bảng suy nghĩ sai → thực tế
| Suy nghĩ sai | Thực tế |
|---|
| ”Task đơn giản, khỏi plan” | Task đơn giản ẩn complexity. Plan mất 30 giây, tiết kiệm rất nhiều token |
| ”Biết rồi, code luôn” | Biết ≠ plan. Viết ra thì mới thấy thiếu sót |
| ”Để code xong rồi plan sau” | Đó không phải planning, đó là hy vọng |
| ”Fix thử cái này xem” | Đoán không bằng chẩn đoán. Dùng /ck-debug |
| ”Thử fix lần nữa” (lần thứ 3+) | 3 lần fail = sai approach. Dừng lại, bàn lại |
| ”Skip test cho nhanh” | Nhanh hôm nay, chậm cả tuần khi bug lên production |
Sai lầm theo từng nhóm lệnh
Sai:
- Dùng
/plan:fast cho feature phức tạp → thiếu research, plan sai
- Plan quá rộng (8+ files trong 1 phase) → khó review, dễ conflict
- Skip
/plan:validate → assumptions sai, phải rewrite
Đúng:
/plan:hard cho feature mới, /plan:fast cho task đã rõ requirements- Mỗi phase nên dưới 5 files
- Luôn validate plan trước khi cook
Sai:
- Dùng
/cook:auto cho task phức tạp → bỏ qua review gates
- Skip testing → bugs lọt vào staging
- Không đọc plan trước khi cook → implement sai
Đúng:
/cook --interactive (default) cho mọi feature quan trọng/cook:auto:fast chỉ cho task nhỏ, rõ ràng, low-risk- Đọc plan, confirm understanding trước khi bắt đầu
Sai:
- Fix triệu chứng thay vì root cause → bug quay lại
- Không viết regression test → same bug tái phát
- Retry 3+ lần cùng approach → tốn token, không hiệu quả
Đúng:
/scout → /ck-debug → xác định root cause → rồi mới fix- Luôn viết test case reproduce bug TRƯỚC khi fix
- Nếu 3 lần fail → dừng, dùng
/brainstorm hoặc hỏi team
Sai:
- Chạy test mà chưa hiểu cần test gì → coverage thấp
- Skip security scan trước deploy → vulnerability lọt production
- Không dùng
/qa-full:verify-issue → verify thủ công, bỏ sót
Đúng:
- Test strategy TRƯỚC, viết test SAU
/qa-full security bắt buộc trước mỗi release- Mỗi issue dev fix xong → QC verify bằng
/qa-full:verify-issue
3. Skill Combos — Workflow hiệu quả
Workflow theo tình huống
Chi tiết từng workflow
Feature mới (phức tạp)
/plan:hard "mô tả feature" # Research + plan chi tiết
/plan:validate # Validate assumptions
/cook # Implement (auto: plan, code, test, review)
/ship # Merge, push, tạo PR
Feature mới (đơn giản)
/cook "mô tả ngắn" # Plan + implement luôn
# Hoặc:
/cook:auto:fast "task nhỏ" # Nhanh nhất cho task rõ ràng
Fix bug
/scout "tìm file liên quan" # Tìm code liên quan
/ck-debug "mô tả bug" # Chẩn đoán root cause
/fix "mô tả fix" # Fix với regression test
/qa-full:regression src/file.ts # Verify không break gì
Trước release
/qa-full:full # Full QA: unit + E2E + security + a11y
/deploy-checklist # Checklist trước deploy
# Merge staging → main
/health-check # Verify sau deploy
4. Quy tắc an toàn
Khi nào dùng --auto vs --interactive
| Tình huống | Mode | Lý do |
|---|
| Feature mới, phức tạp | --interactive | Cần review gates ở mỗi bước |
| Bug fix đơn giản | --interactive (default) | Vẫn cần verify root cause |
| Task nhỏ, rõ ràng, low-risk | --auto hoặc --fast | OK skip review nếu confident |
| Refactoring lớn | --interactive | Cần approval trước khi thay đổi nhiều |
| Production hotfix | --interactive | Hotfix cần extra careful |
Hard Gates — Không skip được
| Gate | Ý nghĩa |
|---|
| Plan → Code | Không có plan thì không được code |
| Test → Ship | Tests phải PASS 100% mới được ship |
| Review → Merge | Code phải qua review mới merge |
| Security → Deploy | Security scan phải clean trước deploy |
Rollback Strategy
Khi có vấn đề sau deploy:
- Nếu biết nguyên nhân: Hotfix branch → fix → test → deploy
- Nếu chưa rõ: Revert commit → deploy lại version cũ → investigate
- Nếu data bị ảnh hưởng: Rollback migration (nếu có) → notify stakeholders
5. Team Adoption — Áp dụng cho team
Onboarding checklist cho thành viên mới
Cài đặt Claude Code CLI
npm install -g @anthropic-ai/claude-code
claude # Verify installation
Thực hành với task nhỏ
/plan:fast "task đầu tiên" # Thử plan
/cook # Thử implement
/test # Thử chạy tests
Sprint workflow integration
| Thời điểm | Dev dùng | QC dùng | PM dùng |
|---|
| Sprint planning | /plan cho assigned features | /qa-full:audit health check | /sprint-plan |
| Hàng ngày | /cook, /fix | /qa-full:verify-issue | /daily-standup |
| Code xong | /test, /code-review | /qa-full:check, /qa-full:accept | Review demo |
| Trước release | /ship | /qa-full:full, security | Release approval |
Cross-team handoff
| Handoff | Từ | Đến | Cách làm |
|---|
| Feature spec | PM | Dev | PM: /prd → Dev nhận issue từ GitHub |
| Code complete | Dev | QC | Dev: push to staging → QC: /qa-full:verify-issue |
| QA pass | QC | Dev | QC: label “QA-passed” → Dev: /ship |
| Bug found | QC | Dev | QC: /bug-report → Dev: /fix |
| Release | Dev | DevOps | Dev: PR staging→main → DevOps: /deploy-checklist |
6. Troubleshooting — Xử lý sự cố
Khi context hết giữa chừng
# Tình huống: Claude Code hết context window giữa task
# Giải pháp:
/watzup # Xem tóm tắt đã làm gì
# Sau đó:
/clear # Clear context
/cook plans/path/to/plan.md # Resume từ plan (plan giữ state)
Khi skill output không như mong đợi
| Vấn đề | Giải pháp |
|---|
| Plan quá phức tạp | Chia nhỏ: /plan:fast cho từng phần |
| Cook không follow plan | Kiểm tra plan file, /cook path/to/plan.md explicit |
| Fix không tìm root cause | Dùng /ck-debug trước /fix |
| Test coverage thấp | /qa-full:check để identify gaps |
| Code review quá strict | Điều chỉnh scope, fix critical issues trước |
Khi tests flaky
# 1. Identify flaky tests
/test # Chạy nhiều lần, note failing tests
# 2. Investigate
/ck-debug "test X flaky — fails intermittently"
# 3. Common causes:
# - Timing issues → thêm waitFor/retry
# - Shared state → isolate tests
# - External dependencies → mock external calls
# - Race conditions → ensure proper async/await
Khi deploy bị lỗi
/incident-response # Kích hoạt quy trình xử lý sự cố
# Hoặc nếu biết nguyên nhân:
/fix:ci # Fix CI/CD issues
Quy tắc vàng khi troubleshoot: Đọc error message kỹ TRƯỚC khi hỏi Claude. 80% câu trả lời nằm trong error message.
7. Giới hạn cần biết
Hiểu giới hạn để tránh bẫy — skills KHÔNG phải magic.
Claude có thể skip instructions
Skills là markdown text. Claude đọc nhưng có thể không làm (~20% skip rate).
Cách giảm thiểu:
- Dùng markers
MANDATORY, KHÔNG SKIP trong instructions
- Check output xem có đủ bước không
- Nếu skip → gõ lại lệnh, nhắc cụ thể bước bị thiếu
Skill gọi skill khác → hay bị skip
Khi skill A gọi /ck:scenario bên trong, Claude hay dùng Agent tool thay vì Skill tool → skill không chạy đúng.
Giải pháp: Luôn gõ TRỰC TIẾP mỗi skill:
# SAI: Để qa-full tự gọi ck:scenario bên trong
/qa-full:full "feature"
# ĐÚNG: Gọi riêng từng bước
/ck:scenario "feature" # Bước 1: USER gõ trực tiếp
/qa-full:full "feature" # Bước 2: USER gõ trực tiếp
Context window dilution
Plan lớn (4 sprints) → output ít chi tiết hơn per-sprint.
Giải pháp:
- Dùng
--sprint N cho per-sprint output
- Scout TRƯỚC rồi mới spawn agents (truyền context)
- KHÔNG dùng
/clear giữa chừng (mất context)
- Nếu context gần hết →
/watzup để save state → /clear → resume với plan path
8. Checklists thực hành
Trước khi bắt đầu feature mới
Trước khi /cook
Trước khi /qa-full
Trước khi /ship
Trước khi Design handoff → Dev
9. So sánh skills hay nhầm lẫn
| So sánh | Skill A | Skill B | Khác biệt chính |
|---|
| Plan vs PRD | /plan "task" | /docs-project:prd | Plan = how to build, PRD = what to build. PRD trước, plan sau |
| Predict vs Validate | /ck:predict | /plan:validate | Predict = AI tự hỏi AI (5 personas). Validate = AI hỏi USER |
| QA Full vs QA vs Test | /qa-full:full | /qa (GStack) | /test chạy tests. /qa quick check. /qa-full:full = 6 bước toàn diện + security |
| Cook vs Code | /cook | /code | Cook đọc plan + viết tests + review. Code = quick implementation |
| Fix vs Debug | /fix "bug" | /debug "error" | Fix = auto fix. Debug = chỉ diagnose, không sửa |
| Code Review vs Review | /code-review (CK) | /review (GStack) | CK = sâu, có agents. GStack = nhanh, structured |
| Scout vs Understand | /scout | /understand | Scout = tìm files nhanh. Understand = build knowledge graph |
