CHƯƠNG 16 / 16

Công thức thực chiến

Ghép CLAUDE.md, Hooks, MCP, subagents và Skills thành workflow dùng hằng ngày.

Cập nhật 21 tháng 7, 202612 phút đọc

Các chương trước giới thiệu từng tính năng riêng lẻ: CLAUDE.md, hooks, MCP, subagent, skill, slash command, plan mode. Chương này ghép chúng lại thành các công thức thực chiến cho những tình huống bạn gặp hằng ngày. Mỗi recipe nêu rõ mục tiêu → thành phần dùng → cấu hình/lệnh → mẹo, và bạn có thể trộn các mảnh giữa các recipe để hợp với dự án của mình.

Nền tảng chung của mọi recipe là một CLAUDE.md sạch sẽ. File này load ở đầu mọi session, nên chỉ đưa vào những thứ áp dụng rộng và Claude không thể tự suy ra từ code. Chạy /init để tạo bản khởi đầu, rồi cắt tỉa dần:

# Code style
- Dùng ES modules (import/export), không dùng CommonJS (require)
- Destructure imports khi có thể

# Workflow
- Luôn typecheck sau khi hoàn tất một loạt thay đổi
- Ưu tiên chạy test đơn lẻ thay vì cả suite (nhanh hơn)
- Branch naming: feature/<ticket>, fix/<ticket>

Với mỗi dòng hãy tự hỏi: "Bỏ dòng này đi thì Claude có mắc lỗi không?". Nếu không, cắt. CLAUDE.md phình to khiến Claude bỏ qua chính những rule quan trọng. Kiến thức chỉ đôi khi cần thì để trong skill (.claude/skills/), không nhét vào CLAUDE.md.

Recipe 1 — Review PR tự động

Mục tiêu: Mỗi khi có thay đổi code, một reviewer chạy trong context sạch (không thiên vị code nó vừa viết) và trả về danh sách vấn đề để bạn xử lý trước khi merge.

Thành phần: custom subagent + built-in /code-review skill + gh CLI + (tuỳ chọn) SubagentStop hook.

Cấu hình. Tạo .claude/agents/security-reviewer.md để dùng đi dùng lại trong dự án:

---
name: security-reviewer
description: Reviews code for security vulnerabilities. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: opus
memory: project
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling

Provide specific line references and suggested fixes.
Update your agent memory with recurring issues you discover in this codebase.

Vì subagent chạy trong context window riêng, output review dài dòng không làm ngập conversation chính; chỉ phần tóm tắt findings quay về. memory: project cho reviewer tích luỹ kinh nghiệm về codebase qua nhiều session (lưu tại .claude/agent-memory/security-reviewer/, commit được vào git).

Lệnh dùng trong session:

Có PR #1234 cần review. Dùng gh pr checkout 1234, rồi @security-reviewer
soi các thay đổi. Sau đó chạy /code-review để kiểm tra lỗi correctness
trên diff hiện tại.

/code-review là skill có sẵn, review diff hiện tại tìm bug trong một subagent context tách biệt rồi trả findings về session. @security-reviewer (dạng @-mention) đảm bảo đúng subagent đó chạy thay vì để Claude tự chọn.

Mẹo:

Reviewer được yêu cầu "tìm gap" thường sẽ luôn báo vài gap kể cả khi code ổn. Dặn nó chỉ flag gap ảnh hưởng tới correctness hoặc requirement đã nêu, phần còn lại coi là optional — tránh over-engineering.
Muốn review chạy tự động sau mỗi PR mở, xem Recipe 8 (chạy theo lịch / GitHub Actions).

Recipe 2 — TDD workflow (test trước, code sau)

Mục tiêu: Buộc Claude viết test thất bại trước, rồi mới code cho tới khi test xanh — đóng vòng verify để bạn có thể rời máy.

Thành phần: prompt có tiêu chí verify + Stop hook (deterministic gate) hoặc /goal.

Cấu hình prompt. Điểm mấu chốt của best-practice là cho Claude một thứ có thể chạy để tự kiểm tra:

Users báo login fail sau khi session timeout. Kiểm tra auth flow trong
src/auth/, đặc biệt phần token refresh. Viết một test THẤT BẠI tái hiện
bug trước, sau đó fix, rồi chạy lại test suite và sửa tới khi xanh.
Xử lý gốc rễ, đừng che lỗi.

Gate cứng bằng Stop hook. Nếu muốn turn không được kết thúc khi test còn đỏ, thêm vào .claude/settings.json một agent-based hook — nó spawn subagent chạy suite thật rồi quyết định:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Hook trả về {"ok": false, "reason": "..."} khi test còn fail, và reason được đẩy lại cho Claude làm chỉ dẫn tiếp theo. Claude Code giới hạn tối đa 10 continuation do Stop hook kích hoạt trong một turn, nên hook không kẹt vô hạn.

Mẹo:

Với task đơn giản hơn, dùng type: "prompt" (một lần gọi model Haiku) thay cho type: "agent" — rẻ và nhanh hơn khi chỉ cần đánh giá dựa trên dữ liệu hook, không cần chạy lệnh.
Biến thể Writer/Reviewer: một session viết test, session thứ hai viết code để pass. Context tươi giúp reviewer không thiên vị.

Recipe 3 — Refactor / migrate codebase lớn

Mục tiêu: Chuyển đổi hàng chục tới hàng trăm file (đổi framework, gỡ deprecated API) song song mà edit không đè lên nhau.

Thành phần: dynamic workflow (ultracode) HOẶC fan-out claude -p, + isolation: worktree cho subagent.

Cách A — dynamic workflow. Để Claude tự viết script orchestrate nhiều subagent. Chỉ cần đưa từ khoá ultracode (hoặc "dùng workflow") vào prompt:

ultracode: migrate mọi component dưới src/components/ từ styled-components
sang Tailwind, làm từng file trong một bản sao repo tách biệt, và verify
mỗi kết quả bằng cách chạy build.

Workflow giữ vòng lặp, nhánh rẽ và kết quả trung gian trong biến script, nên context của Claude chỉ chứa báo cáo cuối. Runtime cho tối đa 16 agent chạy đồng thời, trần 1.000 agent/run. Xem tiến trình bằng /workflows. Nếu kết quả tốt, mở /workflows, chọn run, nhấn s để lưu thành command /<name> tái dùng.

Cách B — fan-out headless khi bạn muốn kiểm soát vòng lặp bằng shell:

for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

--allowedTools giới hạn Claude được làm gì khi chạy không giám sát. Test trên 2-3 file trước để tinh chỉnh prompt, rồi mới chạy full set.

Cách ly bằng worktree. Cho subagent bản sao repo riêng để refactor không đụng checkout chính:

---
name: migrator
description: Migrates one file in an isolated worktree
isolation: worktree
---

Mẹo: Chạy thử workflow trên một thư mục nhỏ trước để ước lượng token; /workflows hiển thị token từng agent và bạn dừng được bất cứ lúc nào mà không mất phần đã xong. Đặt Dynamic workflow size trong /config (small/medium) để mặc định giữ run nhỏ.

Recipe 4 — Tự động format & lint qua hooks

Mục tiêu: Format và bảo vệ file luôn xảy ra một cách tất định, không phụ thuộc việc Claude có nhớ chạy hay không.

Thành phần: PostToolUse hook (format) + PreToolUse hook (chặn file nhạy cảm).

Auto-format sau mỗi edit. Thêm vào .claude/settings.json ở gốc dự án:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Matcher Edit|Write khiến hook chỉ chạy sau tool sửa file. Lệnh trích file_path từ JSON đầu vào (qua jq) và đưa cho Prettier. Đổi prettier --write thành lệnh linter của bạn nếu muốn.

Chặn edit vào file được bảo vệ. Dùng PreToolUse hook gọi script; script exit code 2 để chặn và gửi lý do lại cho Claude:

#!/bin/bash
# .claude/hooks/protect-files.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }
        ]
      }
    ]
  }
}

Mẹo:

Nhớ chmod +x .claude/hooks/protect-files.sh — hook script phải executable.
PreToolUse hook trả deny chặn được tool kể cả ở bypassPermissions. Hook có thể siết chặt nhưng không nới lỏng quá permission rule.
Claude cũng tạo/sửa file qua Bash. Nếu cần bắt mọi thay đổi file (audit), thêm một Stop hook quét working tree một lần mỗi turn thay vì chỉ match Edit|Write.

Recipe 5 — Custom slash command cho quy trình lặp

Mục tiêu: Đóng gói một quy trình nhiều bước bạn chạy hoài (ví dụ fix một GitHub issue) thành lệnh /fix-issue 1234 gọi bằng tay.

Thành phần: skill với $ARGUMENTS và disable-model-invocation: true.

Cấu hình. Tạo .claude/skills/fix-issue/SKILL.md:

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.

1. Dùng `gh issue view` để lấy chi tiết issue
2. Hiểu vấn đề mô tả trong issue
3. Tìm các file liên quan trong codebase
4. Thực hiện thay đổi cần thiết để fix
5. Viết và chạy test để verify
6. Đảm bảo pass linting và type checking
7. Tạo commit message mô tả rõ ràng
8. Push và tạo PR

Gọi bằng /fix-issue 1234; $ARGUMENTS được thay bằng 1234. disable-model-invocation: true dành cho workflow có side effect (push, tạo PR) mà bạn muốn tự trigger, không để Claude tự động gọi.

Khác biệt skill vs subagent: skill chạy trong context conversation chính (Claude làm theo hướng dẫn), còn subagent chạy trong context tách biệt. Dùng skill cho prompt/quy trình tái sử dụng; dùng subagent khi muốn cô lập output dài dòng hoặc siết tool.

Mẹo: Skill có side effect nên dựa vào gh CLI (context-efficient hơn gọi GitHub API trực tiếp và tránh rate limit của request chưa auth). Đảm bảo gh đã đăng nhập.

Recipe 6 — Subagent nghiên cứu song song

Mục tiêu: Điều tra nhiều vùng độc lập của codebase cùng lúc mà không nhét hàng loạt file-read vào context chính.

Thành phần: nhiều subagent chạy song song (thường là built-in Explore hoặc general-purpose).

Lệnh:

Research song song bằng các subagent riêng: (1) auth system xử lý token
refresh thế nào, (2) database module dùng những pattern gì, (3) API layer
validate input ra sao. Tổng hợp lại thành một bản tóm tắt.

Mỗi subagent đọc file trong context riêng và chỉ trả về tóm tắt; Claude tổng hợp. Cách này hiệu quả nhất khi các hướng nghiên cứu không phụ thuộc nhau.

Chuỗi subagent (chain) khi các bước phụ thuộc nhau:

Dùng subagent code-reviewer tìm vấn đề performance, rồi dùng subagent
optimizer để fix chúng.

Mẹo:

Built-in Explore là read-only, tối ưu cho tìm kiếm/phân tích; Write và Edit bị chặn. Nói rõ độ sâu: "quick" cho tra cứu nhanh, "very thorough" cho phân tích toàn diện.
Chạy quá nhiều subagent mà mỗi cái trả kết quả chi tiết vẫn tốn context chính. Yêu cầu chúng "report only the failing tests with error messages" thay vì đổ toàn bộ log.
Cần song song bền hơn context một session, xem agent teams / workflows (Recipe 3).

Recipe 7 — Plan mode cho task phức tạp

Mục tiêu: Với thay đổi động tới nhiều file hoặc vùng code bạn chưa quen, tách research + plan khỏi implement để tránh giải sai vấn đề.

Thành phần: plan mode (read-only) + built-in Plan subagent + checkpoint.

Quy trình 4 pha:

# 1. Explore (bật plan mode: Shift+Tab, hoặc claude --permission-mode plan)
read /src/auth và hiểu cách ta xử lý session và login. Xem cả cách quản
lý biến môi trường cho secrets.

# 2. Plan (vẫn trong plan mode)
Tôi muốn thêm Google OAuth. Cần đổi những file nào? Session flow thế nào?
Tạo một plan chi tiết.

# 3. Implement (thoát plan mode)
Implement OAuth flow theo plan. Viết test cho callback handler, chạy suite
và fix mọi failure.

# 4. Commit
commit với message mô tả rõ và mở PR

Trong plan mode Claude đọc file và đề xuất plan nhưng không ghi ra disk cho tới khi bạn duyệt; status bar hiển thị ⏸ plan mode on. Nhấn Ctrl+G để mở plan trong text editor sửa trực tiếp trước khi Claude thực thi. Khi cần research, Claude uỷ cho Plan subagent để output exploration nằm ở context tách biệt.

Mẹo:

Plan mode có overhead. Với việc scope rõ và fix nhỏ (sửa typo, thêm log, đổi tên biến) — bảo Claude làm thẳng. Nếu diff mô tả được trong một câu, bỏ qua plan.
Với feature lớn, để Claude phỏng vấn bạn trước bằng AskUserQuestion rồi viết ra SPEC.md, sau đó mở session mới với context sạch để implement theo spec.
Muốn khỏi bị hỏi duyệt mỗi lần plan sẵn sàng, dùng PermissionRequest hook auto-approve riêng ExitPlanMode (matcher hẹp, đừng để trống matcher).

Recipe 8 — Kết nối MCP + chạy theo lịch

Mục tiêu: Cho Claude làm việc với hệ thống ngoài (issue tracker, database, monitoring) và tự chạy định kỳ (review PR mỗi sáng, audit dependency hằng tuần).

Thành phần: MCP server + subagent với mcpServers scope + tuỳ chọn scheduling.

Kết nối MCP. Thêm server dùng chung:

# HTTP server
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

# stdio server
claude mcp add playwright -- npx -y @playwright/mcp@latest

Hoặc scope MCP server chỉ cho một subagent (giữ tool description khỏi ngốn context của conversation chính) — khai báo inline trong frontmatter:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github
---
Use the Playwright tools to navigate, screenshot, and interact with pages.

Inline server (playwright) chỉ kết nối khi subagent chạy và ngắt khi xong; tham chiếu theo tên (github) tái dùng connection sẵn có của session.

Chạy theo lịch. Chọn nơi task chạy tuỳ nhu cầu:

Tuỳ chọn	Chạy ở đâu	Hợp cho
Routines	Hạ tầng Anthropic quản lý	Task cần chạy cả khi máy tắt; trigger theo lịch, API call, hoặc GitHub event
Desktop scheduled tasks	Máy bạn, qua desktop app	Task cần truy cập file local hoặc thay đổi chưa commit
GitHub Actions	CI pipeline	Task gắn với repo event (PR mở) hoặc cron sống cạnh config workflow
`/loop`	Session CLI hiện tại	Poll nhanh khi session đang mở

Mẹo: Prompt cho task chạy theo lịch phải nói rõ success trông thế nào và làm gì với kết quả — task chạy tự động nên không hỏi lại được. Ví dụ: "Review các PR gắn nhãn needs-review, để lại inline comment ở chỗ có vấn đề, và post tóm tắt vào Slack channel #eng-reviews."

Xem thêm

content/en/docs/claude-code/common-workflows.md — recipe prompt cho explore, debug, refactor, test, PR
content/en/docs/claude-code/best-practices.md — quản lý context, verify, CLAUDE.md, Writer/Reviewer, fan-out
content/en/docs/claude-code/hooks-guide.md — mọi hook event, JSON I/O, prompt/agent/HTTP hook
content/en/docs/claude-code/sub-agents.md — frontmatter đầy đủ, memory, isolation, nested/parallel subagent
content/en/docs/claude-code/workflows.md — dynamic workflow, ultracode, save & rerun, giới hạn
Chương liên quan: Chapter về CLAUDE.md, Hooks, Subagents, MCP, Skills & Slash Commands, Plan Mode