BÀI VIẾT
Phần 4/6: Chạy agent song song và phối hợp nhiều model, provider
Mỗi task một git worktree và một branch, chạy Claude Code và Codex song song bằng agent-task.sh, review chéo hai họ model kèm lượt phản biện, rồi đưa mọi provider qua một gateway LiteLLM với chính sách định tuyến rõ ràng.

Trong bài viết
Muốn xem nhanh trước? Video tổng hợp cả series (21 phút) đi qua toàn bộ vòng lặp trên repo mẫu.
Kết thúc Phần 3, bạn đã có một spec được duyệt, một bảng task và một agent làm lần lượt từng task trong một thư mục. Khi agent viết tầng repository, bạn ngồi chờ; khi bạn review, agent lại chờ bạn. Hơn nữa, task nào cũng giao cho cùng một model, kể cả khi một model khác làm rẻ hơn hoặc bắt được những lỗi khác.
Phần này nói về việc chạy nhiều agent cùng lúc mà không để chúng giẫm chân nhau, và về việc chủ động dùng nhiều họ model, nhiều provider. Công cụ rất đơn giản: git worktree, hai shell script trong repo mẫu và một file cấu hình gateway LiteLLM. Phần khó là quyết định khi nào nên tách việc và đọc kết quả trả về như thế nào.
Cuối bài bạn sẽ có
- Một nguyên tắc để biết khi nào chạy agent song song thì tiết kiệm thời gian, khi nào thì không.
- Worktree được dựng sao cho mỗi task có thư mục, branch và
node_modulesriêng. - Hiểu rõ từng flag của
scripts/agent-task.sh, và chạy song song hai task của spec 0002: một bằng Claude Code, một bằng Codex. - Cách đọc output dạng máy đọc được từ cả hai công cụ, kể cả JSON có cấu trúc.
scripts/cross-review.shchạy review bằng hai họ model, kèm một lượt phản biện.- Một gateway LiteLLM đứng trước các provider, và hiểu rõ mỗi CLI làm được gì qua gateway đó.
- Một bảng chính sách định tuyến: model nào làm việc gì, và vì sao.
Chuẩn bị
- Repo mẫu đã clone về và đang xanh:
pnpm checkchạy qua trênmain. Cách cài đặt, kể cả bước trust workspace trong Claude Code và project trong Codex, xem ở Phần 2. - Spec 0002 đã được duyệt và có file task
docs/tasks/0002-daily-click-stats.mddo planner viết, như trong Phần 3. Repo có sẵn spec nhưng không có file task này; bạn tự tạo nó ở Phần 3. - Claude Code và Codex CLI đã cài và đăng nhập. Trên Windows, hãy chạy các script trong Git Bash.
- Cho phần gateway: Python có pip, và API key của các provider bạn muốn định tuyến tới.
Khi nào chạy song song có lợi, khi nào không
Chạy hai agent cùng lúc không làm agent nào nhanh hơn. Nó chỉ có ích khi các task không phụ thuộc nhau. Trong công việc hằng ngày của mình, điểm nghẽn hiếm khi nằm ở agent. Điểm nghẽn là thời gian mình review và khâu merge. Có ba câu hỏi quyết định:
- Các task có đụng tới những file khác nhau không? Đó là lý do bảng task ở Phần 3 có cột Files. Với spec 0001, planner đã ghi: “T1-T3 touch the same files, so they run in sequence in one worktree. T4 can run in parallel once T3’s response shape is fixed.” Hai agent cùng sửa một file trên hai branch sẽ để lại cho bạn một merge conflict phải gỡ bằng tay.
- Giao diện giữa chúng đã cố định chưa? Việc cập nhật README cho spec 0002 chạy song song được với phần code, vì bảng Behaviour của spec đã chốt hình dạng response. Ngược lại, không thể viết route song song với một hàm repository mà chưa ai quyết định chữ ký của nó.
- Bạn có đủ sức kiểm chứng cả hai không? Mỗi branch song song là thêm một diff phải đọc. Phần việc của máy thì rẻ: toàn bộ cổng kiểm tra (lint, typecheck, 13 test) chạy khoảng một giây trên máy. Thứ đắt là sự chú ý của bạn.
Nguyên tắc mình dùng: tách theo file, không tách theo bước. “Tầng repository” và “README” là hai task song song tốt. “Viết test” và “làm cho test chạy qua” thì không; đó là hai bước của cùng một task.

Git worktree: mỗi task một thư mục, một branch
Git worktree là một thư mục làm việc phụ gắn vào cùng một repository. Mọi worktree dùng chung một kho object .git, nên tạo mới rất nhanh. Mỗi worktree có branch, index và file trên đĩa riêng, nên hai agent ở hai worktree không thể ghi đè file của nhau.
Các lệnh cơ bản
# create a worktree in .worktrees/x on a new branch agent/x, starting from main
git worktree add .worktrees/x -b agent/x main
# see all worktrees and which branch each one has
git worktree list
# remove the folder when the branch is merged (or abandoned)
git worktree remove .worktrees/x
git branch -d agent/x
Vì sao mỗi task cần một branch riêng? Git không cho hai worktree cùng checkout một branch, và đó là điều tốt: mỗi task cho ra một diff để review, một PR ở Phần 5, và một cách sạch sẽ để bỏ task đi khi cần. Tiền tố agent/ cho bạn biết ngay branch nào vẫn đang chờ người xem.
Repo mẫu đặt worktree trong .worktrees/ và bỏ qua thư mục này trong .gitignore, cùng với agent-runs/ và .claude/worktrees/.
Worktree có sẵn trong Claude Code
Khi làm việc tương tác, bạn không cần gõ lệnh git. claude -w <name> tạo .claude/worktrees/<name> trên branch worktree-<name> và mở phiên làm việc ngay trong đó:
claude -w 0002-days
Mình dùng claude -w khi ngồi cùng agent làm một task trong một tab terminal riêng. Với các lượt chạy headless do script khởi động, mình dùng git worktree add thuần, để Claude Code và Codex dùng chung một quy ước đặt tên (.worktrees/<name>, agent/<name>). Mỗi repo chỉ nên có một quy ước để việc dọn dẹp luôn đơn giản.
Windows: đừng bao giờ dùng chung node_modules
Worktree mới chưa có node_modules. Lối tắt dễ bị cám dỗ là link node_modules của thư mục chính sang worktree. Đừng làm vậy. Trong Git Bash trên Windows, ln -s tạo ra một junction, và git worktree remove sẽ đi theo junction đó rồi xoá luôn thư mục thật mà nó trỏ tới. Bạn mất sạch dependency của thư mục chính.
Thay vào đó, hãy cài riêng cho từng worktree. pnpm giữ một kho nội dung chung cho cả máy và link từ kho đó, nên lần cài thứ hai chủ yếu là thao tác file cục bộ:
cd .worktrees/x
pnpm install --frozen-lockfile --prefer-offline
--frozen-lockfile báo lỗi thay vì âm thầm sửa pnpm-lock.yaml, nhờ vậy agent không bao giờ bắt đầu với phiên bản dependency khác main. --prefer-offline dùng kho cục bộ khi có thể.
Kiểm tra: tạo một worktree dùng thử, cài đặt, chạy cổng kiểm tra rồi xoá đi.
git worktree add .worktrees/try -b agent/try main
(cd .worktrees/try && pnpm install --frozen-lockfile --prefer-offline && pnpm check)
git worktree list
git worktree remove .worktrees/try
git branch -d agent/try
ls node_modules | head -3
Kết quả mong đợi: pnpm check chạy qua trong worktree, git worktree list in ra hai dòng (thư mục chính và .worktrees/try [agent/try]), và sau khi xoá worktree thì node_modules của thư mục chính vẫn còn nguyên.
scripts/agent-task.sh, từng dòng một
Script này là đơn vị công việc song song trong repo mẫu. Nó nhận một công cụ (claude hoặc codex), một tên task và một prompt, rồi chạy headless một task trong worktree riêng. Đây là toàn bộ nội dung.
scripts/agent-task.sh
#!/usr/bin/env bash
# Run one task headless in its own git worktree, with Claude Code or Codex.
#
# scripts/agent-task.sh claude 0002-repo "Do T1 and T2 from docs/tasks/0002-daily-click-stats.md"
# scripts/agent-task.sh codex 0002-docs "Update the README API section for spec 0002"
#
# Result: branch agent/<name>, worktree .worktrees/<name>, log and summary in agent-runs/<name>/.
# Nothing is pushed. Read agent-runs/<name>/summary.md, then review the branch.
set -euo pipefail
tool="${1:?usage: agent-task.sh claude|codex <name> <prompt>}"
name="${2:?missing task name}"
task="${3:?missing prompt}"
root="$(git rev-parse --show-toplevel)"
tree="$root/.worktrees/$name"
runs="$root/agent-runs/$name"
mkdir -p "$runs"
if [ ! -d "$tree" ]; then
git -C "$root" worktree add -q "$tree" -b "agent/$name" main
fi
cd "$tree"
pnpm install --frozen-lockfile --prefer-offline >/dev/null
prompt="$task
Follow AGENTS.md. Work only inside this worktree. Run the task's check command and then pnpm check.
Commit your work on this branch with a Conventional Commits message, staging files explicitly.
End with a summary in three sections: Done and verified (with commands), Done but not verified, Skipped."
case "$tool" in
claude)
claude -p "$prompt" \
--model sonnet \
--permission-mode acceptEdits \
--allowedTools "Read,Edit,Write,Glob,Grep,Bash(pnpm *),Bash(git status),Bash(git diff *),Bash(git add *),Bash(git commit *)" \
--max-turns 40 \
--max-budget-usd 3 \
--output-format json >"$runs/claude.json"
node -e 'const r=require(process.argv[1]);console.log(r.result);console.error(`cost_usd=${r.total_cost_usd}`)' \
"$runs/claude.json" >"$runs/summary.md"
;;
codex)
codex exec "$prompt" \
--sandbox workspace-write \
--json \
-o "$runs/summary.md" >"$runs/codex.jsonl"
;;
*)
echo "unknown tool: $tool (use claude or codex)" >&2
exit 1
;;
esac
if pnpm check >"$runs/check.log" 2>&1; then
echo "check: PASS" >>"$runs/summary.md"
else
echo "check: FAIL (see check.log)" >>"$runs/summary.md"
fi
echo "== agent/$name =="
cat "$runs/summary.md"
Phần chuẩn bị: tham số, đường dẫn, worktree, cài đặt
set -euo pipefaildừng script ở lệnh lỗi đầu tiên, ở biến chưa gán, hoặc khi một lệnh trong pipe thất bại. Nếu chính lệnh agent báo lỗi, bước check cuối sẽ không chạy; hãy xem output thô trongagent-runs/<name>/.${1:?usage: ...}bắt buộc phải có đủ ba tham số.rootlà gốc của repo nơi bạn chạy script. Hãy chạy từ thư mục chính để mọi lượt chạy ghi log vào cùng mộtagent-runs/.- Worktree chỉ được tạo khi chưa tồn tại, và luôn tạo từ
maincục bộ, nên hãy pullmaintrước. Chạy lại với cùng tên sẽ dùng lại worktree và branch cũ; đó là cách gửi thêm một yêu cầu cho cùng task. pnpm install --frozen-lockfile --prefer-offlinechạy bên trong worktree.
Prompt bọc nội dung task của bạn bằng vài chỉ dẫn cố định: làm theo AGENTS.md, chỉ làm trong worktree, chạy check của task rồi pnpm check, commit theo Conventional Commits và stage file tường minh, kết thúc bằng bản tóm tắt ba phần. AGENTS.md đã nói những điều này; nhắc lại chỉ tốn vài token nhưng giúp lượt chạy bớt phụ thuộc vào việc agent đọc file đó kỹ đến đâu.
Lệnh gọi Claude Code
| Flag | Value in script | What it does |
|---|---|---|
-p | prompt | Chạy headless: làm task rồi thoát, không có giao diện tương tác. Từ v2.1.302, mọi tool cần phê duyệt đều bị từ chối nếu không được cho phép. |
--model | sonnet | Model thực thi. Opus là mặc định của Claude Code; với một task được đặc tả rõ, Sonnet là đủ và rẻ hơn. |
--permission-mode | acceptEdits | Tự chấp nhận việc sửa file. Các tool khác vẫn phải được cho phép. |
--allowedTools | Read,Edit,Write,Glob,Grep,Bash(pnpm *),Bash(git status),Bash(git diff *),Bash(git add *),Bash(git commit *) | Toàn bộ danh sách việc agent được làm. Không có git push, không có curl, không có lệnh shell nào khác. Mọi thứ còn lại bị từ chối ở chế độ -p. |
--max-turns | 40 | Giới hạn số lượt của agent, để một lượt chạy bị rối sẽ tự dừng. |
--max-budget-usd | 3 | Dừng khi chi phí ước tính chạm 3 USD. Đây là ước tính phía client, không phải hạn mức thanh toán. |
--output-format | json | Cuối lượt chạy in ra một object JSON có .result, .total_cost_usd và .session_id, lưu vào claude.json. |
Bash(git add *) cũng khớp với git add -A; guard hook từ Phần 2 chặn lệnh đó, và cả git push, như một lớp phòng thủ thứ hai. Nhưng Claude Code đã bỏ qua toàn bộ .claude/settings.json, cả permission lẫn hook, cho tới khi workspace được trust. Worktree là một thư mục mới: hãy thử xem hook có chạy ở đó không trước khi dựa vào nó.
Sau lượt chạy, một dòng node -e đọc claude.json, ghi .result (thông điệp cuối của agent) vào summary.md và in cost_usd=... ra stderr. Nghĩa là chi phí hiện trên terminal nhưng không được lưu vào summary. Nếu cần xem lại, nó vẫn nằm trong claude.json.
Lệnh gọi Codex
| Flag | Value in script | What it does |
|---|---|---|
exec | prompt | Chạy không tương tác. Sandbox mặc định của exec là read-only. |
--sandbox | workspace-write | Cho Codex ghi bên trong thư mục làm việc, tức là worktree. Flag này thay cho --full-auto cũ, vốn không còn được hỗ trợ. |
--json | (on) | Phát các event JSONL ra stdout, lưu vào codex.jsonl. |
-o | $runs/summary.md | Dạng ngắn của --output-last-message: ghi thông điệp cuối của agent vào file. |
Ở đây không có --model. Codex lấy model từ .codex/config.toml của project (gpt-6.1-sol, effort medium, network_access = false) khi project được trust, nếu không thì từ ~/.codex/config.toml. Đường dẫn worktree có thể không được trust như thư mục chính, nên nếu model quan trọng với bạn, hãy thêm -c model=... vào script.
Giới hạn: số lượt, ngân sách, sandbox
Mọi lượt chạy không người trông đều cần một điều kiện dừng không phụ thuộc vào việc agent tự thấy nên dừng. Với Claude, script dùng 40 lượt và 3 USD ước tính. Với Codex, giới hạn là sandbox: chỉ ghi trong worktree và, khi cấu hình project được áp dụng, không có mạng; script không đặt giới hạn lượt hay chi phí cho Codex. Muốn giới hạn theo thời gian thực cho cả hai, hãy bọc lệnh gọi, ví dụ timeout 30m scripts/agent-task.sh .... Hãy đặt giới hạn theo kinh nghiệm: chạy một task với giới hạn rộng, xem nó thực sự dùng bao nhiêu, rồi đặt cao hơn một chút. Một lượt chạy chạm giới hạn thường có nghĩa là task quá lớn hoặc spec chưa rõ.
File summary và bước pnpm check cuối cùng
Khối cuối là phần mình tin nhất. Sau khi agent xong, chính script chạy pnpm check trong worktree và ghi thêm check: PASS hoặc check: FAIL (see check.log) vào summary.md. Bản tóm tắt của agent nói điều nó tin là đã làm. Dòng này nói điều cổng kiểm tra xác nhận, độc lập với agent. Khi hai bên mâu thuẫn, cổng kiểm tra thắng.
Mỗi lượt chạy để lại một thư mục:
| File | Tool | Content |
|---|---|---|
agent-runs/<name>/claude.json | claude | Kết quả JSON thô: thông điệp cuối, chi phí ước tính, session id |
agent-runs/<name>/codex.jsonl | codex | Luồng event thô, mỗi dòng một object JSON |
agent-runs/<name>/summary.md | both | Bản tóm tắt cuối của agent cộng dòng check: |
agent-runs/<name>/check.log | both | Toàn bộ output của pnpm check trong worktree |
Chạy song song hai task của spec 0002
Spec 0002 bổ sung thống kê lượt click theo ngày. Có hai phần độc lập nhau về file: phần lưu trữ (bảng link_clicks trong src/db.ts và câu upsert trong src/repo.ts) và mục API trong README. README có thể viết dựa trên bảng Behaviour của spec, vốn đã chốt request và hình dạng response. Phần chú thích cách dùng ở đầu script cũng lấy đúng hai việc này làm ví dụ.
Mở file task của bạn từ Phần 3 và dùng đúng số hiệu task trong đó. Nếu planner của bạn đánh số các task lưu trữ khác T1 và T2, hãy sửa prompt cho khớp. Sau đó, từ thư mục chính, mở hai terminal:
# terminal 1: storage layer with Claude Code (Sonnet)
scripts/agent-task.sh claude 0002-repo "Do T1 and T2 from docs/tasks/0002-daily-click-stats.md"
# terminal 2: README with Codex
scripts/agent-task.sh codex 0002-docs "Update the README API section for spec 0002"
Nếu muốn dùng một terminal, hãy cho cả hai chạy nền rồi chờ. Mỗi lượt chạy ghi vào file riêng nên output không lẫn vào nhau:
scripts/agent-task.sh claude 0002-repo "Do T1 and T2 from docs/tasks/0002-daily-click-stats.md" >/dev/null 2>&1 &
scripts/agent-task.sh codex 0002-docs "Update the README API section for spec 0002" >/dev/null 2>&1 &
wait
Sau khi chạy xong, bạn sẽ thấy:
.worktrees/0002-repotrên branchagent/0002-repo, với một hoặc vài commit sửasrc/db.ts,src/repo.tsvà các test mà file task của bạn nêu..worktrees/0002-docstrên branchagent/0002-docs, với một commit sửaREADME.md.agent-runs/0002-repo/chứaclaude.json,summary.md,check.log.agent-runs/0002-docs/chứacodex.jsonl,summary.md,check.log.- Không có gì được push.
git branch -rkhông có branch remote mới nào.
Sau đó review từng branch theo cùng một trình tự, bắt đầu từ summary và kết thúc ở diff:
cat agent-runs/0002-repo/summary.md
git log --oneline main..agent/0002-repo
git diff --stat main...agent/0002-repo
git diff main...agent/0002-repo
Hãy đọc mục “Done but not verified” và “Skipped” trước; chúng cho bạn biết cần soi kỹ ở đâu. Muốn agent sửa gì, hãy chạy lại script với cùng tên và một prompt mới. Với Codex, bạn cũng có thể tiếp tục phiên gần nhất ngay trong worktree bằng codex exec resume --last "<prompt>".
Kiểm tra:
tail -n 1 agent-runs/0002-repo/summary.md agent-runs/0002-docs/summary.md
git worktree list
git branch --list 'agent/*'
Kết quả mong đợi: dòng cuối của mỗi summary là check: PASS; git worktree list in ra thư mục chính cùng .worktrees/0002-repo [agent/0002-repo] và .worktrees/0002-docs [agent/0002-docs]; cả hai branch agent/ đều có ở local. Nếu summary kết thúc bằng check: FAIL (see check.log), hãy mở check.log đó trước khi đọc bất cứ thứ gì agent viết.
Việc push và mở PR vẫn do bạn làm; đó là nội dung Phần 5. Khi branch đã merge, dọn dẹp bằng git worktree remove .worktrees/0002-repo và git branch -d agent/0002-repo.
Đọc output headless trong script
Khi đã chạy agent bằng script, bạn cần output của chúng ở dạng dữ liệu chứ không phải chữ trên màn hình. Cả hai công cụ đều có dạng output cho máy đọc.
Claude Code: –output-format json
Với --output-format json, claude -p in ra một object JSON khi kết thúc. Ba trường mình hay dùng:
.result: thông điệp cuối của agent. Đây là thứagent-task.shghi vàosummary.md..total_cost_usd: chi phí ước tính phía client cho lượt chạy. Hữu ích để ghi log chi phí theo task, nhưng không thay được hoá đơn của provider..session_id: định danh của phiên. Mình lưu nó cạnh summary để lần ngược từ một branch về đúng lượt chạy đã tạo ra nó.
jq -r '.result' agent-runs/0002-repo/claude.json
jq '.total_cost_usd' agent-runs/0002-repo/claude.json
jq -r '.session_id' agent-runs/0002-repo/claude.json
Codex: –json và -o
codex exec --json ghi JSONL ra stdout, mỗi dòng một event JSON. Script lưu luồng này vào codex.jsonl và dùng -o cho thông điệp cuối. Mình đọc file -o, còn JSONL chỉ mở khi cần gỡ lỗi, chẳng hạn khi một lượt chạy lâu bất thường.
Kết quả có cấu trúc với –output-schema
Một bản tóm tắt dạng văn bản là đủ cho người đọc. Nếu một script khác phải quyết định bước tiếp theo (mở PR, chạy lại, báo cho bạn), hãy yêu cầu một cấu trúc cố định. Codex hỗ trợ trực tiếp: codex exec --output-schema <file> nhận một JSON Schema, và thông điệp cuối sẽ tuân theo schema đó.
Lưu ý: schema dưới đây là ví dụ cho bài viết, không phải file có trong repo. Hãy điều chỉnh các trường theo nhu cầu của bước tiếp theo.
task-result.schema.json (ví dụ)
{
"type": "object",
"properties": {
"status": { "type": "string", "enum": ["done", "partial", "blocked"] },
"check_passed": { "type": "boolean" },
"files_changed": { "type": "array", "items": { "type": "string" } },
"skipped": { "type": "array", "items": { "type": "string" } }
},
"required": ["status", "check_passed", "files_changed", "skipped"],
"additionalProperties": false
}
codex exec "Report on the work on this branch compared to main, per AGENTS.md" \
--sandbox read-only \
--output-schema task-result.schema.json \
-o agent-runs/0002-docs/result.json
jq -r '.status' agent-runs/0002-docs/result.json
Với Claude Code, .result vẫn là văn bản tự do. Nếu cần một hình dạng cố định, hãy yêu cầu JSON ngay trong prompt, parse .result bằng một parser thật, và coi việc parse thất bại là lượt chạy thất bại. Đừng bao giờ đưa output của agent sang bước sau mà không kiểm tra hợp lệ.
Review chéo giữa các model
Agent tự review việc của mình thường có xu hướng đồng ý với chính nó. Một model thứ hai cùng họ cũng hay có chung điểm mù. AGENTS.md của repo yêu cầu “AI review from two model families” cho thay đổi về schema, auth, workflow và dependency; spec 0002 thêm một bảng nên thuộc nhóm này. scripts/cross-review.sh chạy review đó ngay trên máy, trước khi bạn mở PR.
scripts/cross-review.sh
#!/usr/bin/env bash
# Review the current branch with two model families, then keep only findings both can defend.
#
# scripts/cross-review.sh # reviews main...HEAD
# scripts/cross-review.sh origin/main
#
# Output: agent-runs/review-<branch>/{codex.md,claude.md,final.md}
set -euo pipefail
base="${1:-main}"
branch="$(git rev-parse --abbrev-ref HEAD)"
out="agent-runs/review-${branch//\//-}"
mkdir -p "$out"
review_prompt="Review the changes in 'git diff $base...HEAD' in this repo.
Follow the 'Code Review Rules' section of AGENTS.md and the spec the change implements in docs/specs/.
Output one finding per line: [high|medium|low] file:line: problem. Failure scenario: input -> wrong output.
If there are no findings, output exactly: NO FINDINGS. Do not edit any file."
codex exec "$review_prompt" --sandbox read-only -o "$out/codex.md" >/dev/null
claude -p "$review_prompt" \
--model opus \
--permission-mode plan \
--allowedTools "Read,Glob,Grep,Bash(git diff *),Bash(git log *)" \
--max-turns 20 \
--output-format text >"$out/claude.md"
claude -p "Two reviewers from different model families reviewed 'git diff $base...HEAD'.
Codex findings:
$(cat "$out/codex.md")
Claude findings:
$(cat "$out/claude.md")
For each finding, read the code and try to refute it. You may run 'pnpm vitest run <file>' to check.
Output only findings you could not refute, merged and de-duplicated, highest severity first,
each with the model(s) that raised it. Then one line per refuted finding with the reason." \
--model opus \
--allowedTools "Read,Glob,Grep,Bash(git diff *),Bash(pnpm vitest *)" \
--max-turns 30 \
--output-format text >"$out/final.md"
cat "$out/final.md"
Script chạy ba lượt:
- Codex review trong sandbox read-only; thông điệp cuối ghi vào
codex.md. - Claude Opus review cùng diff với cùng prompt, ở plan mode với các tool chỉ đọc, ghi vào
claude.md. - Lượt phản biện: Opus nhận cả hai danh sách và cố bác bỏ từng phát hiện bằng cách đọc code và, nếu cần, chạy
pnpm vitest run <file>. Những phát hiện đứng vững được đưa lên đầu, gộp lại, xếp theo mức độ nghiêm trọng, kèm tên model đã nêu ra; sau đó là mỗi dòng một phát hiện bị bác bỏ kèm lý do. Đó làfinal.md.
Vì sao cần hai họ model và thêm lượt phản biện? Hai reviewer độc lập tìm ra nhiều lỗi thật hơn một người, nhưng cũng nhiều báo động giả hơn. Lượt phản biện là bộ lọc: câu hỏi “bạn có chứng minh được điều này không sai không?” được model trả lời cẩn thận hơn nhiều so với “có thể sai ở đâu?”. Vì prompt bắt buộc mỗi phát hiện phải có một kịch bản lỗi cụ thể, bên phản biện luôn có thứ cụ thể để kiểm chứng. Trong Claude Code, ý tưởng này cũng có sẵn trong phạm vi một họ model qua hai subagent reviewer và refuter.
Hai chi tiết đáng chú ý. Lượt phản biện có Bash(pnpm vitest *) nhưng không có Write, nên khác với subagent refuter, nó chạy được test có sẵn nhưng không viết được test tạm. Và phát hiện của hai reviewer được dán vào prompt thứ ba như những nhận định cần kiểm chứng, không phải chỉ dẫn; nếu bạn sửa prompt, hãy giữ nguyên tinh thần đó.
Chạy script từ bên trong worktree có branch bạn muốn review. Worktree có bản sao script riêng, và đường dẫn output là tương đối, nên các file sẽ nằm trong agent-runs/ của chính worktree đó (ở đó git cũng bỏ qua thư mục này):
cd .worktrees/0002-repo
scripts/cross-review.sh
ls agent-runs/review-agent-0002-repo/
Cách mình đọc final.md:
- Một phát hiện mức high mà cả hai model cùng nêu gần như chắc chắn là thật. Sửa nó trước tiên.
- Một phát hiện chỉ một model nêu nhưng vẫn đứng vững sau lượt phản biện thì đáng đọc kỹ dòng code được trích. Đây là chỗ review chéo giữa hai họ model đáng đồng tiền nhất.
- Lướt qua các dòng bị bác bỏ. Nếu lý do là “already handled in X”, hãy tự kiểm tra X.
- Cả hai cùng trả về
NO FINDINGScho một thay đổi có thêm bảng thì nên khiến bạn nghi ngờ. Hãy kiểm tra xem diff có bị rỗng vì so sai base không.
Kiểm tra:
ls agent-runs/review-agent-0002-repo/
wc -l agent-runs/review-agent-0002-repo/*.md
Kết quả mong đợi: ba file claude.md, codex.md và final.md, không file nào rỗng. Mỗi dòng trong hai file đầu hoặc là một phát hiện theo định dạng [severity] file:line:, hoặc đúng chuỗi NO FINDINGS.
Nhiều provider qua một gateway
Đến giờ mỗi công cụ tự gọi nhà cung cấp của nó bằng key riêng. Khi có cả nhóm, nhiều máy và các script gọi model trực tiếp, bạn cần một nơi duy nhất giữ key, khống chế chi tiêu, ghi log mọi request và chuyển sang provider khác khi một provider lỗi. Repo mẫu dùng một proxy LiteLLM cho việc này.

gateway/litellm.config.yaml
# One gateway for every agent and script: keys stay here, budgets and logs in one place.
# Run: pip install 'litellm[proxy]' && litellm --config gateway/litellm.config.yaml --port 4000
# Model ids change often: check each provider's model page and update the right-hand side.
model_list:
- model_name: claude-opus-5-5
litellm_params:
model: anthropic/claude-opus-5-5
api_key: os.environ/ANTHROPIC_API_KEY
- model_name: claude-sonnet-5-5
litellm_params:
model: anthropic/claude-sonnet-5-5
api_key: os.environ/ANTHROPIC_API_KEY
- model_name: claude-haiku-5-5
litellm_params:
model: anthropic/claude-haiku-5-5
api_key: os.environ/ANTHROPIC_API_KEY
- model_name: gpt-6.1-sol
litellm_params:
model: openai/gpt-6.1-sol
api_key: os.environ/OPENAI_API_KEY
- model_name: gemini-flash
litellm_params:
model: gemini/gemini-3.8-flash
api_key: os.environ/GEMINI_API_KEY
- model_name: local-coder
litellm_params:
model: ollama_chat/qwen3-coder
api_base: http://localhost:11434
router_settings:
fallbacks:
- claude-sonnet-5-5: [gpt-6.1-sol]
- gemini-flash: [claude-haiku-5-5]
general_settings:
master_key: os.environ/LITELLM_MASTER_KEY
Mỗi mục trong model_list ánh xạ một tên mà client dùng (bên trái, model_name) sang một model thật của provider (bên phải, litellm_params.model). Key lấy từ biến môi trường trên máy chạy gateway, không bao giờ từ client. router_settings.fallbacks chỉ định model dự phòng khi một model lỗi. master_key là token mà client trình cho gateway. Như phần đầu file đã ghi, model id thay đổi thường xuyên; hãy xem trang model của từng provider và cập nhật vế phải.
pip install 'litellm[proxy]'
litellm --config gateway/litellm.config.yaml --port 4000
Trước đó, hãy đặt ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY và LITELLM_MASTER_KEY trong môi trường của gateway. Chỉ cho gateway lắng nghe trên localhost hoặc mạng nội bộ; nó đang giữ mọi key bạn có.
Kiểm tra:
curl -s localhost:4000/v1/models -H "Authorization: Bearer $LITELLM_MASTER_KEY" | jq -r '.data[].id'
Kết quả mong đợi: sáu tên trong model_list: claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5, gpt-6.1-sol, gemini-flash, local-coder.
Claude Code qua gateway
Claude Code đọc hai biến môi trường cho gateway: ANTHROPIC_BASE_URL (gửi request tới đâu) và ANTHROPIC_AUTH_TOKEN (token gửi kèm).
export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_AUTH_TOKEN="$LITELLM_MASTER_KEY"
claude -p "Which command is the full gate in this repo?" --model sonnet
Lưu ý: Anthropic không hỗ trợ việc cho Claude Code chạy trên model không phải Claude thông qua gateway. Hãy dùng gateway để định tuyến giữa các model họ Claude, ghi log, đặt ngân sách và quản lý key. Điều này ảnh hưởng trực tiếp đến cấu hình của repo: fallback claude-sonnet-5-5: [gpt-6.1-sol] sẽ chuyển một request lỗi của Claude Code sang GPT. Fallback đó dành cho các script của riêng bạn. Nếu Claude Code dùng chung gateway, hãy bỏ fallback đó hoặc cho Claude Code một bộ tên model riêng chỉ trỏ tới Claude.
Kiểm tra: lệnh trên phải trả lời pnpm check. Để chắc request thực sự đi qua gateway, hãy dừng tiến trình LiteLLM rồi chạy lại: lần này lệnh phải báo không kết nối được. Sau đó khởi động lại gateway.
Codex qua gateway
Codex không nhận provider từ cấu hình project (.codex/config.toml không được đặt model_provider, model_providers hay base URL). Phần này phải nằm trong một file profile.
examples/codex/litellm.config.toml
# Codex profile that sends requests through a local LiteLLM proxy (gateway/litellm.config.yaml).
# Copy to ~/.codex/litellm.config.toml, then run
# LITELLM_KEY=sk-... codex --profile litellm
# Codex only speaks the OpenAI Responses API (wire_api = "responses"); test that your
# gateway route supports it before relying on it.
model = "gpt-6.1-sol"
model_provider = "litellm"
[model_providers.litellm]
name = "LiteLLM gateway"
base_url = "http://localhost:4000/v1"
env_key = "LITELLM_KEY"
wire_api = "responses"
Chép file này sang ~/.codex/litellm.config.toml rồi chạy codex --profile litellm với LITELLM_KEY là một key của gateway. Dòng quan trọng là wire_api = "responses": đây là giá trị duy nhất được hỗ trợ, nên provider phải nói được OpenAI Responses API. Không phải route nào của gateway cũng làm được. Hãy thử bằng một câu hỏi nhỏ trước khi đưa vào script; nếu thất bại, hãy dùng Codex trực tiếp với tài khoản đăng nhập của nó cho model đó.
Kiểm tra: chạy LITELLM_KEY=... codex --profile litellm trong repo và hỏi “Which command is the full gate, and which file holds all SQL?”. Kết quả mong đợi: pnpm check và src/repo.ts, đúng câu trả lời Codex đã đưa ra khi dùng tài khoản riêng, tốn khoảng 8.5k token. Nếu báo lỗi trong lúc gateway vẫn đang chạy, nghĩa là route đó không hỗ trợ Responses API.
Bedrock, Vertex và OpenRouter
Nếu công ty bạn đã mua model qua một tài khoản cloud, Claude Code có thể dùng trực tiếp mà không cần gateway riêng:
# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id
# OpenRouter
export ANTHROPIC_BASE_URL=https://openrouter.ai/api
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
export ANTHROPIC_API_KEY=""
Giá trị region và project ở trên chỉ là ví dụ; hãy dùng giá trị mà tài khoản của bạn đã được bật. Với OpenRouter, ANTHROPIC_API_KEY phải được đặt tường minh là chuỗi rỗng, để một key còn sót trong shell không bị dùng thay. Lưu ý tương tự như với LiteLLM: chỉ trỏ Claude Code tới model Claude.
Model cục bộ cho dữ liệu nhạy cảm
Có những đoạn code hoặc dữ liệu hoàn toàn không được rời khỏi máy. Khi đó, hãy chạy một model open-weight bằng Ollama. Codex hỗ trợ việc này qua codex --oss (với oss_provider = "ollama" trong cấu hình); nên cho model context window từ 64k token trở lên. Mục local-coder trong gateway trỏ tới cùng Ollama ở localhost:11434 để các script của bạn dùng.
Cái giá phải trả là có thật: model cục bộ trên laptop chậm hơn và yếu hơn các model hàng đầu chạy trên cloud. Mình dùng nó khi quy định về dữ liệu quan trọng hơn chất lượng, ví dụ tóm tắt log có chứa dữ liệu khách hàng, chứ không dùng cho phần triển khai chính.
| Need | Option | Config |
|---|---|---|
| Một nơi giữ key, log, ngân sách | LiteLLM proxy | gateway/litellm.config.yaml, litellm --config ... --port 4000 |
| Claude Code qua gateway | Base URL + token (chỉ model Claude) | ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN |
| Codex qua gateway | Provider tuỳ chỉnh trong profile (Responses API) | ~/.codex/litellm.config.toml, codex --profile litellm |
| Claude trên AWS của công ty | Amazon Bedrock | CLAUDE_CODE_USE_BEDROCK=1, AWS_REGION |
| Claude trên GCP của công ty | Google Vertex AI | CLAUDE_CODE_USE_VERTEX=1, CLOUD_ML_REGION, ANTHROPIC_VERTEX_PROJECT_ID |
| Một hoá đơn cho nhiều nhà cung cấp | OpenRouter | ANTHROPIC_BASE_URL=https://openrouter.ai/api, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY="" |
| Dữ liệu không được rời máy | Ollama, model cục bộ | codex --oss, oss_provider = "ollama"; local-coder trong gateway |
| Review lượt hai mạnh hơn | Codex profile | examples/codex/deep-review.config.toml, codex --profile deep-review |
Chính sách định tuyến: model nào làm việc gì
Có nhiều model trong tay chỉ có ích khi bạn quyết định trước model nào làm việc gì. Nếu không, mọi task sẽ rơi vào model mặc định, hoặc tệ hơn, vào model mà ai đó vừa thử gần nhất. Phần 1 đã giới thiệu các vai trò. Dưới đây là chính sách cụ thể mình dùng với repo mẫu. Cột “Why” là lập luận của mình, không phải kết quả benchmark.
| Task type | Model | Why |
|---|---|---|
| Planner (spec sang bảng task) | claude-opus-5-5 ở plan mode; claude-fable-5-2 cho những thiết kế khó nhất | Sai ở đây sẽ nhân lên ở mọi task; đáng dùng model mạnh nhất, và plan mode không sửa được file. |
| Executor (một task trong một worktree) | claude-sonnet-5-5 qua agent-task.sh claude, hoặc gpt-6.1-sol qua agent-task.sh codex | Task nhỏ và đã đặc tả rõ; một model tầm trung cộng với check cứng là đủ. |
| Reviewer | claude-opus-5-5 (subagent reviewer, cross-review.sh) | Tìm lỗi thật cần chiều sâu; review chỉ chạy một lần mỗi branch nên chi phí vẫn trong tầm kiểm soát. |
| Second reviewer | gpt-6.1-sol, effort high (profile deep-review) | Họ model khác có điểm mù khác; AGENTS.md bắt buộc cho thay đổi về schema, auth, workflow và dependency. |
| Refuter | claude-sonnet-5-5 (subagent) hoặc claude-opus-5-5 (script) | Bác bỏ một nhận định cụ thể là việc hẹp hơn việc tìm ra nó. |
| Triage (gắn nhãn, tóm tắt, phân luồng) | claude-haiku-5-5 hoặc gemini-flash qua gateway | Khối lượng lớn, rủi ro thấp; tốc độ và giá là quan trọng nhất. |
| Local | local-coder (Ollama), codex --oss | Dữ liệu không được rời khỏi máy. |
Hãy ghi phiên bản bảng này của bạn vào repo và đưa lựa chọn model vào script, như agent-task.sh và cross-review.sh đang làm. Một chính sách chỉ nằm trong đầu sẽ không sống sót qua một tuần bận rộn.
Thực hành tốt khi chạy song song
- Mỗi worktree một task. Một branch, một diff, một summary. Task thứ hai không liên quan thì mở worktree thứ hai.
- Giới hạn mọi lượt chạy không người trông. Số lượt và ngân sách cho Claude, sandbox cho Codex,
timeouttheo thời gian thực cho các lượt chạy qua đêm. - Không bao giờ để agent push. Danh sách tool cho phép không có
git push, hook chặn nó,AGENTS.mdcấm nó. Push là lúc một con người nói “tôi đã đọc”. - Summary phải tự đứng được. Bạn sẽ đọc năm bản liên tiếp mà không có lịch sử hội thoại. Định dạng ba phần và dòng
check:tồn tại vì lý do đó. - Dựng lại môi trường bằng script. Worktree, cài đặt và check đều do
agent-task.shlàm, nên một lượt chạy hỏng có thể xoá đi và chạy lại từ đúng điểm xuất phát. - Merge theo thứ tự phụ thuộc. Phần lưu trữ trước route, rebase các branch còn lại, và chạy
pnpm checksau mỗi lần merge.
Những lỗi hay gặp
- Link
node_modulesvào worktree. Trên Windows, link đó là junction, vàgit worktree removesẽ xoá thư mục thật phía sau. - Tách những task dùng chung file. Thời gian tiết kiệm được lại đổ vào gỡ conflict. Hãy xem cột Files trước.
- Bắt đầu từ một
maincũ. Script tạo branch từmaincục bộ. Hãy pull trước. - Tin vào hook mà không thử trong worktree. Khi dựng repo này, Claude Code đã bỏ qua toàn bộ
.claude/settings.json, cả permission lẫn hook, cho tới khi workspace được trust; một lệnhgit add -Athử nghiệm đã chạy qua. Sau khi trust, hook chặn được nó. Worktree là thư mục mới, nên hãy kiểm tra lại, và giữ--allowedToolsthật chặt. - Thử hook với input sai. Hook format không làm gì khi nhận đường dẫn kiểu Git Bash (
/d/...), nhưng chạy đúng với đường dẫn mà Claude thực sự gửi. Hãy thử bằng đúng JSON mà công cụ gửi. - Đọc summary thay vì đọc kết quả cổng kiểm tra. Câu “All tests pass” chẳng có nghĩa gì khi bên cạnh là
check: FAIL. - Cho Claude Code chạy trên model không phải Claude qua gateway. Anthropic không hỗ trợ; hãy để ý các fallback kiểu
claude-sonnet-5-5: [gpt-6.1-sol]. - Cho rằng Codex chạy được với mọi route của gateway. Nó cần Responses API. Hãy thử một lần.
- Để worktree cũ nằm lại. Sau khi merge, chạy
git worktree removevàgit branch -d.
Checklist
- Các task chạy song song đụng tới những file khác nhau và có giao diện cố định giữa chúng.
mainđã được pull và đang xanh trước khi bắt đầu.- Mỗi task chạy qua
scripts/agent-task.shtừ thư mục chính, trong worktree và branchagent/riêng. - Mỗi worktree có
node_modulesriêng; không có link. - Guard hook chạy được bên trong worktree (đã thử một lần).
- Mọi
summary.mdkết thúc bằngcheck: PASStrước khi bạn đọc diff. - Thay đổi cần review hai họ model có
final.md, và mọi phát hiện còn đứng vững đều đã được sửa hoặc trả lời. - Không branch nào do agent push.
- Gateway: Claude Code chỉ đi tới model Claude; route của Codex đã được thử.
- Chính sách định tuyến đã được ghi lại và các script tuân theo nó.
- Worktree và branch đã merge đều được dọn đi.
Ở Phần 5, các branch sẽ rời khỏi máy của bạn: CI chạy cùng cổng kiểm tra, còn Claude và Codex review từng pull request trong GitHub Actions.
Trong series này
- Kiến trúc và vai trò của các model
- Thiết lập repo cho Claude Code và Codex
- Spec, kế hoạch và task
- Chạy agent song song và phối hợp nhiều model, provider
- CI/CD với AI review
- Vận hành: chi phí, bảo mật, học hỏi
- Phần 7: Áp dụng quy trình agent vào một dự án thật
Repo mẫu cho cả series nằm ở github.com/luonghongthuan/agentic-shortlink. Hãy clone về và tự làm từng bước; lời giải tham khảo cho spec 0002 nằm trên branch solution/0002-daily-stats.

Thảo luận
Bình luận được duyệt trước khi công khai. Email của bạn được giữ riêng tư.