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!

Cập nhật bộ claudekit mới: Nhiều subcommand cũ (/fix:test, /cook:auto, /plan:fast, /design:good) đã bỏ. Skill giờ tự route — chỉ cần gõ /fix, /cook, /plan, /stitch. Xem tools-overview mapping.

1. Nguyên tắc vàng

5 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. `/investigate` prove root cause trước
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
5	Verify sau khi implement	`/verify` hoặc `/run` — chạy app kiểm chứng thay đổi thật sự work, không chỉ tin type-check

Không có ngoại lệ cho 5 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. `/vibe` tự plan + implement trong 1 lệnh
”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 `/investigate` — “no fix without root cause"
"Thử fix lần nữa” (lần thứ 3+)	3 lần fail = sai approach. Dừng lại, dùng `/brainstorm` hoặc `/plan-ceo-review`
”Skip test cho nhanh”	Nhanh hôm nay, chậm cả tuần khi bug lên production
”Type-check pass là done”	Type-check ≠ feature work. `/verify` hoặc `/run` mới chắc
”Dùng —no-verify cho nhanh”	Bypass hook = bypass safety. `/careful` cảnh báo trước lệnh phá hủy

Sai lầm theo từng nhóm lệnh (bộ mới)

Sai:

Skip validation → assumptions sai, phải rewrite
Plan quá rộng (8+ files trong 1 phase) → khó review, dễ conflict
Dùng /plan:fast (không còn tồn tại) — bộ mới chỉ còn /plan

Đúng:

/plan "mô tả" — skill tự chọn depth (fast/deep) theo task
Mỗi phase nên dưới 5 files
/vibe tự run validate + red-team plan trước khi cook

Sai:

Gõ /cook:auto (không còn tồn tại) hoặc /cook:auto:fast
Skip testing → bugs lọt vào staging
Không đọc plan trước khi cook → implement sai

Đúng:

/cook path/to/plan.md — pass plan explicit
/vibe --ship cho pipeline autonomous đầy đủ (plan→cook→PR→merge)
Đọc plan, confirm understanding trước khi bắt đầu

Sai:

Gõ /fix:test, /fix:ui, /fix:ci (đều KHÔNG còn tồn tại)
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:

/fix — skill auto-route theo loại (test/CI/UI/types/logs)
/investigate TRƯỚC /fix để prove root cause
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 /office-hours

Sai:

Gõ /design:good, /design:screenshot (đều KHÔNG còn tồn tại — old design commands)
Design AI mà không có DESIGN.md → output rời rạc, không consistent
Handoff Figma link mà thiếu component specs

Đúng:

/stitch "screen" — AI design generation
/design-shotgun — sinh nhiều variant để so sánh
/design-consultation TRƯỚC để tạo DESIGN.md cho project mới
/design-html finalize design → production HTML/CSS
/design-review visual QA + auto-fix sau implement

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
Skip /qa-full:tdd:verify sau /cook (verify tests thật sự PASS, không cheat)

Đú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
TDD flow: /qa-full:tdd → /cook → /qa-full:tdd:verify

Sai:

git push --force vào main → mất commit
Skip canary check sau deploy → bug production không biết
Deploy khi CI chưa xanh

Đúng:

/land-and-deploy — merge PR + chờ CI + deploy + canary verify
/canary post-deploy monitoring (screenshot + perf diff)
/careful mode khi làm gì nhạy cảm

3. Skill Combos — Workflow hiệu quả

Workflow theo tình huống

Chi tiết từng workflow (bộ mới)

Feature mới — Pipeline autonomous (khuyến nghị)

Một lệnh chạy full pipeline: worktree → plan → validate → cook → code-review → PR → merge → CI watch.

# Từ GitHub issue có sẵn:
/vibe --ship https://github.com/primeproduction/skils-hub-prime/issues/123

# Ship beta thay vì stable:
/vibe --ship --beta #123

# Bugfix (auto route sang /fix thay vì /cook):
/vibe --ship "sửa checkout không load tổng tiền"

Khi nào KHÔNG dùng:

Task cross-team cần Design handoff riêng
Refactor lớn cần Eng Manager approve trước → dùng /plan-eng-review
Task chưa rõ scope → dùng /plan-ceo-review trước

Feature mới — Manual step-by-step

/worktree                     # Isolated worktree
/plan "mô tả feature"         # Plan (skill tự chọn depth)
/plan validate <plan.md>      # Validate assumptions
/cook <plan.md>               # Implement với plan
/verify                       # Chạy app xác nhận work
/code-review                  # Local review pending
/ship official                # Ship PR về main
/review-pr <#PR> --fix --reply # Review + auto-fix + reply
/land-and-deploy              # Merge + deploy + canary

Fix bug — Root cause first

/investigate "mô tả bug"       # Root cause analysis (iron law: no fix without root cause)
/fix                          # Auto-route fix
/verify                       # Xác nhận fix work
/qa-full:regression src/file.ts # Verify không break gì

Nếu 3 lần fix fail:

/brainstorm "vấn đề X"        # Ideation
/office-hours                 # YC-style challenge premise
/codex challenge              # Adversarial review từ OpenAI Codex

Trước release

/qa-full:full                 # Full QA: unit + E2E + security + a11y
/security-scan                # Extra security scan
/cso daily                    # Chief Security Officer audit
/land-and-deploy              # Merge + deploy + canary
/health                       # Code quality dashboard 0-10
/canary                       # Post-deploy monitoring

Refactor lớn

/understand                   # Build knowledge graph của codebase
/repomix                      # Pack repo cho LLM context (nếu cần)
/plan "refactor X"
/plan-eng-review              # Lock architecture với Eng Manager
/worktree                     # Isolate refactor
/cook <plan.md>
/qa-full:check                # Bổ sung tests thiếu
/qa-full:regression           # Impact analysis

Task cross-team (PM → Design → Dev → QA → DevOps)

# PM
/prd "feature"                # Tạo PRD
/docs-project:full "feature"  # PRD → UI Specs → QA Plan

# Design
/design-consultation          # DESIGN.md nếu project mới
/stitch "screen"              # AI generate UI
/design-html                  # Finalize → HTML/CSS

# Dev
/vibe --ship #issue           # Full pipeline

# QA
/qa-full:tdd:verify           # Verify tests PASS sau cook
/qa-full:accept docs/prd/F*.md # Nghiệm thu theo PRD

# DevOps
/land-and-deploy              # Merge + deploy + canary

4. Quy tắc an toàn

Safety skills mới trong bộ claudekit

Skill	Bảo vệ khỏi	Khi dùng
`/careful`	`rm -rf`, `git reset --hard`, `force-push`, `DROP TABLE`	Debug prod, làm việc shared infra
`/freeze <dir>`	Edit ngoài folder chỉ định	Debug 1 module, không muốn accident sửa nơi khác
`/unfreeze`	Clear freeze boundary	Khi cần widen edit scope
`/guard`	Kết hợp `/careful` + `/freeze`	Full safety mode

Khi nào dùng autonomous vs manual

Tình huống	Recommend	Lý do
Feature đã có issue rõ + acceptance criteria	`/vibe --ship #N`	Full autonomous, an toàn nhờ gates
Feature mới, phức tạp, chưa rõ scope	`/plan-ceo-review` trước	Cần rethink scope
Bug fix đơn giản, root cause rõ	`/fix` + `/verify`	Skill tự route
Bug fix khó, chưa rõ nguyên nhân	`/investigate` bắt buộc trước	Iron law
Task nhỏ, rõ ràng, low-risk	`/cook "task"`	Đủ
Refactoring lớn	`/plan-eng-review` trước	Lock architecture
Production hotfix	`/investigate` + `/fix` + `/verify` + `/careful`	Extra careful
Debug prod / shared env	`/guard` mode	Chặn accidental damage

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
Root cause → Fix	`/investigate` phải prove root cause trước `/fix`
CI → Merge auto	`/vibe --ship` chờ CI xanh mới auto-merge

Rollback Strategy

Khi có vấn đề sau deploy:

Nếu biết nguyên nhân: Hotfix branch → /investigate prove → /fix → /land-and-deploy
Nếu chưa rõ: Revert commit → /canary verify version cũ → /investigate
Nếu data bị ảnh hưởng: Rollback migration (nếu có) → notify stakeholders → post-mortem

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

Đọc tài liệu

Tổng quan workflow — hiểu quy trình team
Tools Overview — bảng skills đầy đủ
Dev Overview — decision tree chọn lệnh
QA Overview — quy trình QA
Trang này — best practices

Thực hành với task nhỏ

/vibe "task đầu tiên"           # Thử full pipeline autonomous
# Hoặc từng bước:
/plan "task đầu tiên"
/cook
/verify

Tham gia sprint

Làm việc theo Sprint Workflow. Hỏi team khi unsure.

Sprint workflow integration (bộ mới)

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`, `/estimate`, `/gate-check`
Hàng ngày	`/vibe #N`, `/cook`, `/fix`, `/investigate`	`/qa-full:verify-issue`	`/sprint-status`, `/watzup`
Code xong	`/verify`, `/code-review`	`/qa-full:check`, `/qa-full:accept`	Review demo
Trước release	`/ship`, `/land-and-deploy`	`/qa-full:full`, `/qa-full security`	`/retro`, release approval

Cross-team handoff (bộ mới)

Handoff	Từ	Đến	Cách làm
Feature spec	PM	Dev	PM: `/prd` → Dev nhận issue từ GitHub Projects
Code complete	Dev	QC	Dev: `/ship official` → push to staging → QC: `/qa-full:verify-issue`
QA pass	QC	Dev	QC: label “ready to ship stable” → Dev: `/land-and-deploy`
Bug found	QC	Dev	QC: `/bug-report` → Dev: `/investigate` + `/fix`
Release	Dev	DevOps	Dev: PR staging→main → DevOps: `/land-and-deploy` + `/canary`

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 mới:
/watzup                            # Auto-generate handoff report từ git + worktrees
/checkpoint                        # Save state chi tiết để resume sau
# Sau đó:
/clear                             # Clear context
/cook plans/path/to/plan.md        # Resume từ plan (plan giữ state)
# Hoặc:
/checkpoint resume                 # Resume từ checkpoint đã save

Khi skill output không như mong đợi

Vấn đề	Giải pháp
Plan quá phức tạp	Chia nhỏ: `/plan` cho từng phần, mỗi phần < 5 files
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 `/investigate` trước `/fix` (bắt buộc)
Test coverage thấp	`/qa-full:check` để identify gaps
Code review quá strict	Điều chỉnh scope, fix critical issues trước
Skill không active	`/find-skills "mô tả task"` — đề xuất skill phù hợp

Khi tests flaky

# 1. Identify flaky tests (skill tự làm)
/test-flakiness                    # Aggregate pass rates, recommend quarantine

# 2. Investigate root cause
/investigate "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

/investigate "deploy fail: <error>" # Root cause first
/fix                               # Auto-route: /fix skill sẽ chọn CI/logs strategy
/verify                            # Xác nhận local fix work
/vibe --ship #hotfix-issue         # Ship hotfix qua vibe pipeline

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. /investigate tự làm bước này.

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
Dùng /vibe — pipeline có gate checks tự enforce từng bước

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
/checkpoint để save decision + remaining work

8. Checklists thực hành

Trước khi bắt đầu feature mới

cd vào đúng project folder
Đang dùng Claude Code CLI (không phải web/desktop)
Đã có GitHub issue (nếu dùng /vibe)
Đã có plan/PRD hoặc description rõ ràng
Branch đúng convention (feat/FXX-YY-*) hoặc dùng /worktree

Trước khi /cook

Có plan file (plans/*.md) đã review
PRD, QA, UI specs đã link trong plan
Database migration sẵn sàng (nếu schema change)
Đã chạy /plan validate (hoặc /vibe tự làm)

Trước khi /qa-full

Đã chạy /ck-scenario "feature" TRỰC TIẾP
Code pass lint + typecheck
Unit tests đã viết (TDD: /qa-full:tdd trước)
PRD path sẵn sàng (cho :accept)

Trước khi /ship

Đã chạy /code-review
Đã chạy /verify — xác nhận feature work thật
CI pass (lint + typecheck + test)
Test trên staging OK
PR title đúng Conventional Commits
No secrets in code (/security-scan)

Trước khi Design handoff → Dev

Figma link có đầy đủ screens + states
Component specs (spacing, colors, typography)
Responsive breakpoints defined
Error/empty/loading states có
DESIGN.md cho project mới (/design-consultation)
PM đã review + approve design

Trước khi /land-and-deploy

PR đã merged hoặc đã enable auto-merge
CI checks xanh (Vercel/GitHub Actions)
/canary đã cấu hình (screenshot baseline)
/setup-deploy đã chạy 1 lần (config platform)
Rollback plan sẵn sàng

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"`	`/prd` (hoặc `/docs-project:prd`)	Plan = how to build, PRD = what to build. PRD trước, plan sau
Predict vs Validate	`/ck-predict`	`/plan validate`	Predict = 5 personas AI debate. Validate = AI hỏi USER
QA Full vs QA vs Test	`/qa-full:full`	`/qa` (GStack)	`/test` chạy tests. `/qa` quick check + auto-fix. `/qa-full:full` = 6 bước toàn diện + security
Cook vs Vibe	`/cook`	`/vibe`	Cook = implement plan. Vibe = full pipeline (plan+cook+PR+merge)
Fix vs Investigate	`/fix "bug"`	`/investigate "bug"`	Fix = apply fix (yêu cầu root cause đã rõ). Investigate = chỉ diagnose, KHÔNG sửa
Debug vs Investigate	`/ck-debug`	`/investigate`	Ck-debug = systematic root cause + fix. Investigate = iron law “no fix without root cause”
Verify vs Run	`/verify`	`/run`	Verify = chạy app kiểm chứng change work. Run = launch app để screenshot/xem UI
Code Review vs Review PR	`/code-review`	`/review-pr`	Code-review = local pending changes. Review-pr = review PR trên GitHub với `--fix --reply`
Ship vs Land-and-deploy	`/ship official`	`/land-and-deploy`	Ship = tạo PR + push. Land-and-deploy = merge + deploy + canary verify
Scout vs Understand	`/scout`	`/understand`	Scout = tìm files nhanh. Understand = build knowledge graph queryable
Stitch vs Design-shotgun	`/stitch`	`/design-shotgun`	Stitch = generate 1 design. Design-shotgun = generate nhiều variants để so sánh
Careful vs Guard vs Freeze	`/careful`	`/guard` = careful + freeze	Careful = warn destructive. Freeze = restrict edit scope. Guard = cả 2

10. Skills mới cần biết (bộ claudekit mới)

/vibe — Autonomous pipeline

Full pipeline: worktree → plan → validate → cook/fix → code-review → ship PR → review-pr → merge → CI watch.Prefix: /vibe, /vibe --ship, /vibe --beta, /vibe --ship --beta

/vibe #123                    # Từ issue → PR ready (không merge)
/vibe --ship #123             # Full pipeline → merge → CI watch
/vibe --ship "feature request" # Natural language, tự tạo issue
/vibe --ship --beta #123      # Ship về beta thay vì stable

/investigate — Debug with iron law

Iron Law: no fix without root cause. 4 phases: investigate → analyze → hypothesize → implement.

/investigate "500 error /api/users"
/investigate "test X fails intermittently"
/investigate "checkout không load tổng tiền trên iOS Safari"

Thay thế cho /ck-debug khi cần iron law enforce.

/verify + /run — Confirm change works

/verify                       # Chạy app + kiểm chứng change work thật
/run                          # Launch app + drive nó để screenshot/xem UI

Bắt buộc sau khi implement UI/frontend feature. Type-check pass ≠ feature work.

/ghpm — GitHub project management

Bootstrap labels + Projects board + handoff status cho repo mới.

/ghpm bootstrap               # Setup labels + project board
/ghpm status                  # Xem in-progress work

/land-and-deploy — Merge + deploy + canary

Merge PR + chờ CI + deploy → canary verify. Đầy đủ safety net.

/setup-deploy                 # Chạy 1 lần: cấu hình platform
/land-and-deploy              # Sau khi PR ready

/stitch + /design-shotgun — AI design

Thay thế cho /design:good, /design:screenshot cũ.

/stitch "checkout screen"     # Generate 1 design
/design-shotgun               # Generate nhiều variants song song
/design-html                  # Finalize design → production HTML/CSS
/design-consultation          # Tạo DESIGN.md (design system source of truth)

/watzup + /checkpoint — Handoff / resume

/watzup                       # Auto handoff report từ git + worktrees + plans
/checkpoint                   # Save state chi tiết
/checkpoint resume            # Resume từ checkpoint

/cso + /cti-expert — Security

/cso daily                    # Zero-noise daily security audit
/cso comprehensive            # Monthly deep scan
/cti-expert                   # Cyber threat intel + OSINT report
/security-scan                # Secrets + dependency + OWASP scan

​Best Practices — Hướng dẫn thực hành

​1. Nguyên tắc vàng

​2. Anti-patterns — Sai lầm phổ biến

​Bảng suy nghĩ sai → thực tế

​Sai lầm theo từng nhóm lệnh (bộ mới)

​3. Skill Combos — Workflow hiệu quả

​Workflow theo tình huống

​Chi tiết từng workflow (bộ mới)

​4. Quy tắc an toàn

​Safety skills mới trong bộ claudekit

​Khi nào dùng autonomous vs manual

​Hard Gates — Không skip được

​Rollback Strategy

​5. Team Adoption — Áp dụng cho team

​Onboarding checklist cho thành viên mới

​Sprint workflow integration (bộ mới)

​Cross-team handoff (bộ mới)

​6. Troubleshooting — Xử lý sự cố

​Khi context hết giữa chừng

​Khi skill output không như mong đợi

​Khi tests flaky

​Khi deploy bị lỗi

​7. Giới hạn cần biết

​Claude có thể skip instructions

​Skill gọi skill khác → hay bị skip

​Context window dilution

​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

​Trước khi /land-and-deploy

​9. So sánh skills hay nhầm lẫn

​10. Skills mới cần biết (bộ claudekit mới)

Best Practices — Hướng dẫn thực hành

1. Nguyên tắc vàng

2. Anti-patterns — Sai lầm phổ biến

Bảng suy nghĩ sai → thực tế

Sai lầm theo từng nhóm lệnh (bộ mới)

3. Skill Combos — Workflow hiệu quả

Workflow theo tình huống

Chi tiết từng workflow (bộ mới)

4. Quy tắc an toàn

Safety skills mới trong bộ claudekit

Khi nào dùng autonomous vs manual

Hard Gates — Không skip được

Rollback Strategy

5. Team Adoption — Áp dụng cho team

Onboarding checklist cho thành viên mới

Sprint workflow integration (bộ mới)

Cross-team handoff (bộ mới)

6. Troubleshooting — Xử lý sự cố

Khi context hết giữa chừng

Khi skill output không như mong đợi

Khi tests flaky

Khi deploy bị lỗi

7. Giới hạn cần biết

Claude có thể skip instructions

Skill gọi skill khác → hay bị skip

Context window dilution

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

Trước khi /land-and-deploy

9. So sánh skills hay nhầm lẫn

10. Skills mới cần biết (bộ claudekit mới)