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.

Minh họa các worker phối hợp qua bộ điều phối, lưu trạng thái và kiểm tra bảo mật.

Đọc cùng AI

Chọn nội dung để sao chép và dán vào trợ lý AI. Không tự gửi dữ liệu. Nội dung CMS được chuyển sang Markdown; dùng Markdown gốc nếu có.

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_modules riê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.sh chạ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 check chạy qua trên main. 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.md do 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:

  1. 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.
  2. 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ó.
  3. 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.

Sơ đồ: nhánh main tách ra ba worktree (agent/0002-repo với Claude Code, agent/0002-route với Codex exec, agent/readme với model bất kỳ); mỗi worktree chạy pnpm check, thành một PR riêng, qua review chéo giữa hai họ model rồi mới đến người merge
Mỗi task một worktree và một branch. Mỗi branch phải qua check riêng, rồi review từ họ model còn lại, sau đó con người mới merge.

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 pipefail dừ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ô trong agent-runs/<name>/.
  • ${1:?usage: ...} bắt buộc phải có đủ ba tham số.
  • root là 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ột agent-runs/.
  • Worktree chỉ được tạo khi chưa tồn tại, và luôn tạo từ main cục bộ, nên hãy pull main trướ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-offline chạ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

FlagValue in scriptWhat it does
-ppromptChạ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.
--modelsonnetModel 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-modeacceptEditsTự chấp nhận việc sửa file. Các tool khác vẫn phải được cho phép.
--allowedToolsRead,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-turns40Giới hạn số lượt của agent, để một lượt chạy bị rối sẽ tự dừng.
--max-budget-usd3Dừ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-formatjsonCuố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

FlagValue in scriptWhat it does
execpromptChạy không tương tác. Sandbox mặc định của exec là read-only.
--sandboxworkspace-writeCho 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.mdDạ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:

FileToolContent
agent-runs/<name>/claude.jsonclaudeKết quả JSON thô: thông điệp cuối, chi phí ước tính, session id
agent-runs/<name>/codex.jsonlcodexLuồng event thô, mỗi dòng một object JSON
agent-runs/<name>/summary.mdbothBản tóm tắt cuối của agent cộng dòng check:
agent-runs/<name>/check.logbothToà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-repo trên branch agent/0002-repo, với một hoặc vài commit sửa src/db.ts, src/repo.ts và các test mà file task của bạn nêu.
  • .worktrees/0002-docs trên branch agent/0002-docs, với một commit sửa README.md.
  • agent-runs/0002-repo/ chứa claude.json, summary.md, check.log.
  • agent-runs/0002-docs/ chứa codex.jsonl, summary.md, check.log.
  • Không có gì được push. git branch -r khô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.sh ghi vào summary.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:

  1. Codex review trong sandbox read-only; thông điệp cuối ghi vào codex.md.
  2. 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.
  3. 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 FINDINGS cho 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.

Sơ đồ: Claude Code qua ANTHROPIC_BASE_URL, Codex CLI qua model_providers.litellm và các script riêng qua OpenAI SDK cùng gọi một proxy LiteLLM ở cổng 4000; proxy giữ key, ngân sách, log, fallback và định tuyến tới Anthropic, OpenAI, Google Gemini và model chạy cục bộ trên Ollama
Mọi client gọi một proxy; proxy giữ key của provider và quyết định mỗi request đi đâu.

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.

NeedOptionConfig
Một nơi giữ key, log, ngân sáchLiteLLM proxygateway/litellm.config.yaml, litellm --config ... --port 4000
Claude Code qua gatewayBase URL + token (chỉ model Claude)ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN
Codex qua gatewayProvider tuỳ chỉnh trong profile (Responses API)~/.codex/litellm.config.toml, codex --profile litellm
Claude trên AWS của công tyAmazon BedrockCLAUDE_CODE_USE_BEDROCK=1, AWS_REGION
Claude trên GCP của công tyGoogle Vertex AICLAUDE_CODE_USE_VERTEX=1, CLOUD_ML_REGION, ANTHROPIC_VERTEX_PROJECT_ID
Một hoá đơn cho nhiều nhà cung cấpOpenRouterANTHROPIC_BASE_URL=https://openrouter.ai/api, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY=""
Dữ liệu không được rời máyOllama, model cục bộcodex --oss, oss_provider = "ollama"; local-coder trong gateway
Review lượt hai mạnh hơnCodex profileexamples/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 typeModelWhy
Planner (spec sang bảng task)claude-opus-5-5 ở plan mode; claude-fable-5-2 cho những thiết kế khó nhấtSai ở đâ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 codexTask nhỏ và đã đặc tả rõ; một model tầm trung cộng với check cứng là đủ.
Reviewerclaude-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 reviewergpt-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.
Refuterclaude-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 gatewayKhối lượng lớn, rủi ro thấp; tốc độ và giá là quan trọng nhất.
Locallocal-coder (Ollama), codex --ossDữ 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, timeout theo 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.md cấ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.sh là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 check sau mỗi lần merge.

Những lỗi hay gặp

  • Link node_modules vào worktree. Trên Windows, link đó là junction, và git worktree remove sẽ 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 main cũ. Script tạo branch từ main cụ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ệnh git add -A thử 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ữ --allowedTools thậ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 remove và 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.sh từ thư mục chính, trong worktree và branch agent/ riêng.
  • Mỗi worktree có node_modules riêng; không có link.
  • Guard hook chạy được bên trong worktree (đã thử một lần).
  • Mọi summary.md kết thúc bằng check: PASS trướ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

  1. Kiến trúc và vai trò của các model
  2. Thiết lập repo cho Claude Code và Codex
  3. Spec, kế hoạch và task
  4. Chạy agent song song và phối hợp nhiều model, provider
  5. CI/CD với AI review
  6. Vận hành: chi phí, bảo mật, học hỏi
  7. 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ư.

← Về danh sáchRead in English