BÀI VIẾT

Phần 7: Áp dụng quy trình agent vào một dự án thật

Mình đem quy trình của series vào LingoLive AI, một repo đang chạy thật, bằng tool agent-repo-setup: audit, apply, verify trong sáu bước. Có hai bất ngờ: merge vào main là deploy production, và security review tìm ra ba lỗ trong chính các hook.

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ó.

Sáu phần trước, mình làm mọi thứ trên agentic-shortlink. Repo đó nhỏ, sạch, do mình tự viết từ đầu, nên cái gì cũng vừa khít: một lệnh pnpm check, Biome lo format, CI chạy trên runner của GitHub. Repo thật thì không như vậy. Nó có lịch sử vài trăm commit, có PR người khác đang mở, có workflow ai đó viết từ năm ngoái mà không ai đọc lại, và có những thứ bạn không biết là tồn tại cho tới khi nó gây chuyện.

Phần thêm này kể lại một buổi chiều mình đem quy trình của series vào LingoLive AI. Đây là sản phẩm của chính mình: app luyện nói tiếng Anh bằng cách nói chuyện với một gia sư AI. Stack gồm Next.js 15, React 19, Firebase, Vitest, Playwright và một voice agent viết bằng Pipecat. Repo private nên mình không để link, nhưng mọi lệnh, output và đoạn config trong bài đều lấy từ lần chạy thật hôm đó.

Mình không muốn copy tay từng file như ở phần 2 nữa. Nên mình gom các bước lại thành một tool nhỏ tên agent-repo-setup, đặt ở tools/agent-repo-setup trong repo mẫu. Tool có ba script: audit.mjs đọc repo và đoán lệnh, apply.mjs thêm phần còn thiếu, verify.mjs kiểm tra lại. Nghe thì gọn. Thực tế buổi chiều đó vẫn có hai cú bất ngờ: CI deploy production mỗi lần merge vào main, và một lượt security review tìm ra ba lỗ hổng trong chính mấy cái hook mình viết.

Cuối bài bạn sẽ có

  • Sáu bước để đưa một repo đang chạy về cùng cách làm của series, không đụng vào main của ai.
  • Tool agent-repo-setup với ba script audit, apply, verify, và cách đọc output của từng cái.
  • Cách nhận ra repo nào merge là deploy, và những chốt chặn nên có cho loại repo đó.
  • Ba lỗi bảo mật thật trong hook và permission rule, cách sửa, và giới hạn của hook.
  • Một kế hoạch đưa quy trình ra nhiều repo: repo cá nhân trước, repo công ty sau.

Chuẩn bị

  • Bạn nên đọc phần 2 (thiết lập repo) và phần 5 (CI/CD với AI review). Bài này giả định bạn đã biết AGENTS.md, hook, subagent và skill dùng để làm gì.
  • Node 22, git, gh đã đăng nhập, Claude Code đã cài.
  • Một bản clone của repo mẫu. Ba script chỉ dùng thư viện có sẵn của Node, không cần pnpm install.
  • Một repo thật của bạn. Lần đầu nên chọn repo cá nhân, ít người đụng vào.

Mọi lệnh node tools/agent-repo-setup/... bên dưới mình chạy từ thư mục gốc của repo mẫu, còn repo đích nằm ở một thư mục khác.

Bước 1: Làm trong một worktree mới từ origin/main

Mình không đụng vào checkout đang có trên máy. Checkout local của LingoLive lúc đó chậm 17 commit so với origin/main. Nếu audit trên bản cũ, tool sẽ đọc package.json cũ, đoán sai lệnh, và PR mở ra sẽ conflict ngay. Nên mình fetch trước, rồi tạo một worktree mới từ origin/main trên branch chore/agent-repo-setup.

Trước khi tạo branch, mình xem repo có PR nào đang mở và có ai vừa push gì không. Bộ setup này sửa .github/ và .gitignore, hai chỗ rất dễ đụng nhau với PR của người khác. Hôm đó repo không có PR mở và cũng không có commit mới, nên mình làm tiếp.

cd ~/projects/LingoLiveAI
git fetch origin
git rev-list --count HEAD..origin/main
gh pr list --state open
git log origin/main -5 --format='%h %ar %an %s'
git worktree add ../lingolive-agent-setup -b chore/agent-repo-setup origin/main

Kiểm tra: git -C ../lingolive-agent-setup status -sb in ra ## chore/agent-repo-setup...origin/main và không có file nào thay đổi. Lệnh git rev-list ở trên cho bạn biết checkout cũ chậm bao xa; với mình là 17.

Bước 2: Audit để biết repo đang có gì

Audit chỉ đọc, không ghi gì. Nó tìm package manager từ lockfile, ghép lệnh gate từ các script trong package.json, xem test runner nào có trong dependency, đọc tất cả workflow để lấy danh sách runner, rồi đánh dấu từng mảnh của bộ setup agent là có hay chưa.

node tools/agent-repo-setup/scripts/audit.mjs ../lingolive-agent-setup

Với LingoLive, bản audit hiện tại in ra như sau:

repo: ../lingolive-agent-setup  pm: npm  gate: npm run typecheck && npm test  test one: npx vitest run <file>
runners: ct240-ci, [self-hosted, lxc-prod], ubuntu-latest, macos-15  formatter: -
prod commands to guard: firebase deploy, scripts/deploy, ssh to prod hosts
  NOTE a push to main deploys to production (deploy job in CI)
  - agentsMd
  - claudeMd
  - claudeImportsAgents
  - settings
  - denyRules
  - preToolUseHook
  - subagents
  - skills
  - specs
  - codexConfig
  - aiReviewWorkflow
  - dependabotActions
  Y gitattributes

Đọc từng dòng thì thấy khá nhiều chuyện:

  • Gate là npm run typecheck && npm test. Repo không có script check và cũng không có lint, nên audit ghép hai script còn lại. Agent sẽ chạy đúng lệnh này trước khi báo xong.
  • Test một file là npx vitest run <file>. Vitest có trong devDependencies. Đây là lệnh agent dùng liên tục khi làm, nên nó phải nhanh.
  • Không có formatter. Repo không dùng Biome hay Prettier, nên apply sẽ không tạo format hook. Mình không muốn tool tự thêm formatter vào một repo đang chạy, vì lần format đầu tiên sẽ đổi hàng trăm file.
  • Runner: ct240-ci là runner self-hosted của mình. Repo nằm trên tài khoản GitHub cá nhân, không có ngân sách cho hosted runner, nên CI chạy trên máy nhà. ubuntu-latest và macos-15 chỉ dùng cho workflow build bản native demo. Còn lxc-prod là runner nằm ngay trên máy production.
  • Phần agent thì trống trơn: không có AGENTS.md, CLAUDE.md, settings, hook, subagent, spec, config Codex, AI review hay Dependabot.

Dòng NOTE a push to main deploys to production là cú bất ngờ đầu tiên, và lần audit đầu tiên của mình đã bỏ sót nó. Mình kể chi tiết ở phần sau.

Cách audit ghép lệnh gate khá thẳng: có check thì dùng check, không thì nối lint, typecheck, test theo thứ tự, script nào có thì lấy.

tools/agent-repo-setup/scripts/audit.mjs

const run = (s) => (pm === "npm" ? (s === "test" ? "npm test" : `npm run ${s}`) : `${pm} ${s}`);
const scripts = pkg?.scripts ?? {};
const gateParts = [];
if (scripts.check) gateParts.push(run("check"));
else {
  for (const s of ["lint", "typecheck", "test"]) if (scripts[s]) gateParts.push(run(s));
}

Kiểm tra: chạy thêm --json và lọc hai khoá quan trọng nhất.

node tools/agent-repo-setup/scripts/audit.mjs ../lingolive-agent-setup --json | grep -E '"(gate|deploysOnMain)"'
  "gate": "npm run typecheck && npm test",
  "deploysOnMain": true,

Nếu gate ra null, repo của bạn không có script nào trong ba cái trên. Bạn cần tự quyết lệnh gate trước khi đi tiếp, vì mọi thứ phía sau đều dựa vào nó.

Bước 3: Dry run, rồi apply

Mình luôn chạy dry run trước. Nó in danh sách file sẽ tạo hoặc sửa mà không ghi gì xuống đĩa.

node tools/agent-repo-setup/scripts/apply.mjs ../lingolive-agent-setup --dry-run
agent-repo-setup (dry run) for ../lingolive-agent-setup  [gate: npm run typecheck && npm test] [runner: ct240-ci]
created  AGENTS.md
created  CLAUDE.md
created  .claude/settings.json
created  .claude/hooks/guard-bash.mjs
created  .claude/agents/reviewer.md
created  .claude/agents/refuter.md
created  .claude/skills/new-spec/SKILL.md
created  .claude/skills/implement-spec/SKILL.md
created  docs/specs/TEMPLATE.md
created  .codex/config.toml
created  .github/workflows/ai-review-claude.yml
created  .github/workflows/ai-review-codex.yml
created  .github/workflows/claude-mention.yml
created  .github/dependabot.yml
appended .gitignore
Next: fill the AGENTS.md Project section, run verify.mjs, open the repo in Claude Code once and accept the trust dialog.

Hai chỗ mình đọc kỹ nhất là gate và runner. Gate sai thì agent sẽ báo xong khi chưa xong. Runner sai thì tệ hơn: AI review có thể chạy trên đúng cái máy production. Apply chọn runner đầu tiên không chứa chữ prod, và bạn có thể ép bằng --runs-on.

tools/agent-repo-setup/scripts/apply.mjs

const runsOn = opt("--runs-on", audit.runsOn.find((r) => !/prod/.test(r)) ?? "ubuntu-latest");

Khi danh sách đã ổn, mình apply thật, ghi rõ runner cho chắc:

node tools/agent-repo-setup/scripts/apply.mjs ../lingolive-agent-setup --runs-on ct240-ci

Apply có một luật cứng: không bao giờ ghi đè. File nào chưa có thì tạo. AGENTS.md có rồi thì chỉ nối thêm những section còn thiếu. CLAUDE.md có rồi thì chỉ chèn dòng @AGENTS.md lên đầu. .claude/settings.json có rồi thì gộp các rule allow, ask, deny vào, không xoá rule nào của bạn. Ba workflow AI review sinh ra đều tắt sẵn, chỉ chạy khi repo có biến ENABLE_AI_REVIEW=true, và chỉ chạy cho PR từ chính repo, không chạy cho PR từ fork.

Phần Safety trong AGENTS.md lấy thẳng từ kết quả audit. Repo nào merge là deploy sẽ có thêm một dòng cảnh báo, và lệnh deploy nào tìm thấy cũng có tên trong đó:

tools/agent-repo-setup/scripts/apply.mjs

  PROD_SAFETY:
    (audit.deploysOnMain
      ? `\n- A push or merge to \`${base}\` deploys to production through CI. Treat every merge as a release.`
      : "") +
    (audit.prodCommands.length
      ? `\n- Deploy commands (${audit.prodCommands.map((p) => `\`${p.name}\``).join(", ")}) are run by a human, never by an agent; the guard hook blocks them.`
      : ""),

Kiểm tra: git -C ../lingolive-agent-setup status --short chỉ có một dòng M là .gitignore, còn lại là file mới (??). Nếu thấy một file cũ nào khác bị sửa, dừng lại và đọc diff. Bảng Commands trong AGENTS.md mới sẽ trông thế này:

| Purpose | Command |
| --- | --- |
| Install | `npm ci` |
| One test file | `npx vitest run <file>` |
| Full gate (run before saying done) | `npm run typecheck && npm test` |

Bước 4: Tự tay viết phần Project

Section ## Project trong AGENTS.md là chỗ duy nhất tool cố tình để trống, với một dòng TODO(agent-repo-setup). Lý do đơn giản: script không đọc ra được sản phẩm làm gì, thư mục nào nguy hiểm, test nào CI chạy mà gate không chạy. Mấy thứ đó chỉ người làm repo mới biết, và nó lại là phần agent cần nhất.

Với LingoLive, mình viết ba thứ. Một là sản phẩm và stack trong hai câu. Hai là bản đồ thư mục, có ghi rõ chỗ nào rủi ro cao (security rules của Firestore và Storage, thư mục deploy). Ba là hai lưu ý mà không tool nào đoán ra: CI còn chạy test của tools/lesson-mcp và contract test của Pipecat, và bộ E2E live (RUN_LIVE=1) gọi API trả tiền nên agent không bao giờ tự chạy.

Đây là phần Project trong AGENTS.md của LingoLive sau khi mình viết xong:

## Project

LingoLive AI: practise English by talking with an AI tutor (Gemini Live or Grok Voice through Pipecat), with gentle inline corrections, AI-graded session reports and a fluency dashboard. Next.js 15 App Router, React 19, TypeScript, Firebase (Auth, Firestore, Storage, Cloud Functions), Vitest and Playwright.

```
app/                 Next.js routes (learner app, lessons, kids, admin, api/)
components/          React components
lib/                 domain logic and service clients (Gemini, Firebase, allowance, i18n...)
functions/src/       Firebase Cloud Functions (Gemini Live token broker)
agents/pipecat-agent Python voice agent; provider and ticket contracts in test_providers.py
tools/lesson-mcp/    lesson authoring MCP server with its own tests
firestore.rules, storage.rules   security rules (high-risk changes)
tests/               Vitest unit tests and Playwright E2E
scripts/deploy/      production deploy scripts (humans only)
```

CI also runs `npm test --prefix tools/lesson-mcp` and the Pipecat contract tests; run them when you touch those folders. Live E2E (`RUN_LIVE=1`) calls paid APIs: never run it unless asked.

Mình giữ nó ngắn. AGENTS.md là thứ agent đọc mỗi lần mở phiên, nên mỗi dòng thừa là token thừa nhân với số phiên. Cái gì agent tự tìm ra bằng một lệnh ls thì không cần ghi.

Kiểm tra: grep -c "TODO(agent-repo-setup)" ../lingolive-agent-setup/AGENTS.md trả về 0.

Bước 5: Verify, rồi thử thật với Claude Code

verify.mjs kiểm tra những thứ mà nhìn bằng mắt rất dễ sót: settings có parse không, CLAUDE.md có import @AGENTS.md không, frontmatter của subagent và skill có nằm ở dòng 1 không, còn placeholder {{...}} nào chưa điền không. Quan trọng nhất, nó đưa từng lệnh nguy hiểm vào guard hook bằng đúng dạng JSON mà Claude Code gửi, và xem hook có chặn không.

node tools/agent-repo-setup/scripts/verify.mjs ../lingolive-agent-setup
ok   .claude/settings.json parses
ok   CLAUDE.md imports @AGENTS.md
ok   AGENTS.md has Code Review Rules and Review levels
ok   AGENTS.md Project section filled in
ok   no unfilled {{placeholders}}
...
ok   guard blocks: git -C . push
ok   guard blocks: bash -c "git push"
ok   guard blocks: rm -r -f dist
...
ok   guard blocks: npx firebase deploy --only hosting
ok   guard blocks: bash scripts/deploy/lxc-deploy.sh
ok   deny rule for .env
ok   deny rule for git diff/log --output
ok   ai-review-claude.yml: every action pinned to a SHA
ok   ai-review-claude.yml: off by default, same-repo PRs only
...
all checks passed

Verify qua chưa có nghĩa là Claude Code dùng tới mấy file đó. Ở phần 2 mình đã dính một lần: workspace chưa trust thì Claude Code bỏ qua toàn bộ .claude/settings.json, cả permission lẫn hook. Nên mình mở worktree trong Claude Code, chấp nhận hộp thoại trust, rồi thử hai câu với Haiku cho rẻ:

cd ../lingolive-agent-setup
claude --model haiku
> List the skills and subagents in this project.
> Run: npx firebase deploy --only hosting

Câu đầu, Claude liệt kê đủ hai skill new-spec, implement-spec và hai subagent reviewer, refuter. Câu hai thì bị chặn ngay ở hook:

PreToolUse:Bash hook error: ... Blocked by .claude/hooks/guard-bash.mjs: firebase deploy is run by a human, not an agent

Kiểm tra: verify.mjs in all checks passed và thoát với mã 0; trong Claude Code, lệnh deploy hiện dòng Blocked by .claude/hooks/guard-bash.mjs. Nếu lệnh deploy chạy luôn, gần như chắc chắn workspace chưa trust.

Bước 6: Mở PR, nhưng không để agent merge

Mình stage từng đường dẫn, đọc lại diff, rồi commit. Push thì mình tự làm từ terminal của mình, vì guard hook chặn git push trong phiên agent, và đó là chủ ý.

cd ../lingolive-agent-setup
git add AGENTS.md CLAUDE.md .claude .codex .github docs/specs/TEMPLATE.md .gitignore
git diff --cached --stat
git commit -m "chore: agent workflow setup (AGENTS.md, guardrails, reviewer subagents, specs, AI review CI)"
git push -u origin chore/agent-repo-setup
gh pr create --base main --fill

Repo ra PR #5. Trên PR, job test của CI cũ chạy như mọi khi. Ba job AI review mới hiện trạng thái skipping, đúng như mong đợi vì ENABLE_AI_REVIEW chưa bật. Repo vốn đã có CodeRabbit review PR, và mình giữ nguyên nó. Hai workflow mới bổ sung chứ không thay thế: chúng đọc Code Review Rules trong AGENTS.md và spec trong docs/specs/, còn CodeRabbit vẫn làm phần việc nó vốn làm.

Luồng pull request: CI chạy gate, AI review từ hai họ model, rồi người duyệt và merge
Luồng PR từ phần 5. Ở LingoLive, bước merge cuối cùng cũng là bước deploy.

Mình không để agent merge PR này, và cũng không merge ngay. Ở repo này, merge vào main là deploy production. Một PR chỉ toàn file cấu hình và tài liệu vẫn kéo theo một lần deploy thật.

Kiểm tra: gh pr checks 5 cho thấy test pass và các job AI review ở trạng thái skipping. Không có job nào chạy trên runner lxc-prod, vì job deploy chỉ chạy khi có push vào main.

Bất ngờ thứ nhất: merge là deploy

Bản audit đầu tiên của mình chỉ nhìn tên file workflow. Có file nào tên chứa deploy hay release thì đánh dấu repo có đường deploy. LingoLive chỉ có ci.yml và native-demo.yml, nên audit báo không có gì. Nhưng đọc hết ci.yml thì ở cuối file có đoạn này:

on:
  pull_request:
  push:
    branches: [main]
# ...
  deploy:
    name: Deploy to LXC
    needs: test
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: [self-hosted, lxc-prod]
    timeout-minutes: 15
    concurrency:
      group: lxc-prod-deploy
      cancel-in-progress: false

Nghĩa là mọi push và mọi merge vào main, kể cả sửa một dấu phẩy trong README, đều deploy lên production qua runner nằm trên máy prod. Tên file không nói gì về chuyện đó. Một agent đọc repo lần đầu sẽ không biết, và bản audit đầu tiên của mình cũng không biết.

Mình sửa audit để nó đọc nội dung workflow chứ không chỉ đọc tên. Giờ nó tìm job có chữ deploy trong tên, environment: prod..., hoặc runner lxc-prod, rồi xem workflow đó có trigger khi push vào main không:

tools/agent-repo-setup/scripts/audit.mjs

const deployJob =
  /^\s{2}[\w-]*deploy[\w-]*:\s*$/m.test(wfText) ||
  /environment:\s*['"]?prod/i.test(wfText) ||
  /lxc-prod/.test(wfText);
const deploysOnMain = deployJob && /push:\s*\n\s*branches:\s*\[?\s*['"]?main/.test(wfText);
if (deployJob && existsSync(join(dir, "scripts/deploy")))
  prod.push({ name: "scripts/deploy", re: "scripts[\\\\/]deploy[\\\\/]" });
if (deployJob) prod.push({ name: "ssh to prod hosts", re: "\\bssh\\b.*\\bprod\\b" });

Phát hiện ra rồi thì có ba hệ quả trong repo. Thứ nhất, AGENTS.md có thêm dòng “A push or merge to main deploys to production through CI. Treat every merge as a release.” Agent đọc dòng này mỗi phiên, và reviewer subagent coi mọi thứ chạm tới production là mức high. Thứ hai, guard hook của LingoLive có thêm ba pattern sinh từ audit:

  [/\bfirebase\s+deploy\b/, "firebase deploy is run by a human, not an agent"],
  [/scripts[\\/]deploy[\\/]/, "scripts/deploy is run by a human, not an agent"],
  [/\bssh\b.*\bprod\b/, "ssh to prod hosts is run by a human, not an agent"],

Thứ ba, cách mình xử lý PR thay đổi. PR này mình sẽ tự merge sau khi đọc diff, và coi nó như một lần release. Với repo kiểu này, mình cũng không bao giờ cho agent quyền merge, kể cả khi CI xanh.

Bài học rộng hơn: tool audit chỉ tốt bằng những pattern nó biết. Lần đầu áp vào một repo mới, bạn vẫn phải tự mở từng workflow ra đọc. Mỗi lần thấy thứ tool bỏ sót, sửa tool, đừng chỉ sửa repo.

Bất ngờ thứ hai: security review tìm ra ba lỗ

Sau khi commit, một lượt security review tự động đọc lại commit và báo ba lỗi. Cả ba đều có thật, và mình sửa xong trong cùng một giờ, ở cả tool lẫn repo LingoLive.

1. Format hook chạy qua shell trên Windows

Trên Windows, npx là file .cmd, nên format hook phải chạy formatter qua shell. Đường dẫn file đi thẳng vào câu lệnh. Một file có tên chứa & hay | là đủ để chèn thêm một lệnh khác. LingoLive không có formatter nên không dính hook này, nhưng template trong tool thì có. Bản sửa đầu tiên từ chối mọi đường dẫn có ký tự đặc biệt của shell. Sau đó mình bỏ hẳn shell: hook gọi thẳng file JS của formatter bằng node, nên đường dẫn luôn là một argument duy nhất, và file nằm ngoài project thì bỏ qua. Không có shell thì cũng không còn gì để chèn:

tools/agent-repo-setup/templates/hooks/format-file.mjs

// Run the formatter's own JS entry with node: no shell, so the file path is always a single argument.
if (FORMAT && file && /{{FORMAT_EXT}}/.test(file)) {
  const target = resolve(file);
  const bin = join(root, FORMAT.bin);
  if (!relative(root, target).startsWith("..") && existsSync(bin)) {
    spawnSync(process.execPath, [bin, ...FORMAT.args, target], { stdio: "ignore", cwd: root });
  }
}

2. Guard hook có đường vòng

Bản guard cũ khớp git push theo đúng thứ tự từ. Chỉ cần viết git -C . push, git -c k=v push, bash -c "git push", hay tách cờ thành rm -r -f là lọt. Giờ pattern tìm ở bất kỳ đâu trong câu lệnh, cho phép option chen giữa git và push:

tools/agent-repo-setup/templates/hooks/guard-bash.mjs

// A guardrail, not a security boundary: also keep branch protection, no push credentials for agents,
// and deploy approval in CI. Patterns look anywhere in the command, so `git -C x push`,
// `git -c k=v push` and `bash -c "git push"` are caught too.
const input = JSON.parse(readFileSync(0, "utf8"));
const command = String(input.tool_input?.command ?? "").replace(/\s+/g, " ");

const blocked = [
  [/\bgit\b[^;&|]*\spush\b/, "git push is done by a human after review"],
  // ...

Mấy cách lách này giờ nằm luôn trong verify.mjs, nên repo nào cũng tự kiểm lại mỗi lần verify. Một lỗi đã tìm ra thì phải thành test, không thì nó quay lại.

3. Allow rule rộng hơn mình tưởng

Mình cho phép Bash(git diff *) và Bash(git log *) vì hai lệnh này “chỉ đọc”. Nhưng git diff --output=<file> ghi ra file, còn --ext-diff chạy một chương trình ngoài. Dấu * mở cửa cho cả hai. Cách sửa là thêm deny rule, vì deny luôn xét trước allow:

tools/agent-repo-setup/scripts/apply.mjs

const deny = [
  "Bash(git diff *--output*)",
  "Bash(git log *--output*)",
  "Bash(git diff *--ext-diff*)",
  "Bash(git * -c *)",
  "Read(./.env)",
  // ...

Hook là lan can, không phải tường

Ba lỗi trên cho mình một kết luận rõ: hook chỉ là guardrail. Nó chặn những lỗi vô tình, kiểu agent tiện tay git push hay git add -A. Nó không chặn nổi một kẻ cố tình, vì shell có quá nhiều cách viết cùng một lệnh. Những chốt chặn thật nằm ở chỗ khác:

  • Branch protection trên main: không ai push thẳng, PR phải qua CI và có người duyệt.
  • Agent không có credential để push. Máy chạy agent không giữ token có quyền ghi vào repo production.
  • Deploy cần người duyệt trong CI. Job deploy chờ một người bấm duyệt, thay vì tự chạy khi có push.

Nhìn lại đoạn ci.yml ở trên: job deploy của LingoLive chạy ngay sau job test, không chờ ai duyệt. Hook chặn agent gõ lệnh deploy, nhưng không chặn được một lần merge.

Đưa ra nhiều repo

Một repo thì làm tay cũng được. Mười repo thì cần thứ tự. Mình chia ra như sau.

Audit hết trước, chưa apply gì. Chạy audit dạng JSON cho từng repo, gom lại, nhìn một lượt xem repo nào merge là deploy, repo nào không có gate, repo nào dùng runner gì:

for r in ../repo-a ../repo-b ../repo-c; do
  node tools/agent-repo-setup/scripts/audit.mjs "$r" --json > "audit-$(basename "$r").json"
done

Repo cá nhân, rủi ro thấp đi đầu. Repo không có người dùng thật, không deploy tự động. Ở đây bạn chạy đủ sáu bước, kể cả bật AI review, và tìm ra lỗi của chính tool trước khi nó chạm vào repo quan trọng. LingoLive là repo cá nhân nhưng có production và deploy khi merge, nên với mình nó nằm giữa danh sách, không nằm đầu.

Repo công ty: guardrail trước, CI sau. Lượt đầu chỉ thêm AGENTS.md, CLAUDE.md, settings và hook, dùng cờ --no-ci để apply không tạo workflow nào:

node tools/agent-repo-setup/scripts/apply.mjs ../company-repo --no-ci --dry-run

Workflow mới ở repo công ty cần org đồng ý: action mới, secret API key, runner nào chạy job, ai trả tiền token. Đừng mở PR thêm workflow AI review vào repo của org khi chưa hỏi người quản lý org. Thêm guardrail thì ít tranh cãi hơn nhiều, vì nó chỉ ảnh hưởng tới người dùng agent.

Repo có dữ liệu người dùng thật hoặc quyền vào production: không bật AI review khi chưa có lời đồng ý của chủ repo. AI review gửi diff ra API bên ngoài. Diff có thể chứa fixture lấy từ dữ liệu thật, cấu hình hạ tầng, hay tên máy chủ. Workflow sinh ra vẫn có thể nằm trong repo ở trạng thái tắt. Chỉ có bật ENABLE_AI_REVIEW là quyết định của chủ repo, không phải của bạn.

Những lỗi hay gặp

  • Chạy trên checkout cũ. Checkout của mình chậm 17 commit. Luôn fetch và tạo worktree từ origin/main.
  • Tin audit tuyệt đối. Audit đầu tiên của mình bỏ sót job deploy vì chỉ nhìn tên file. Đọc từng workflow bằng mắt ít nhất một lần.
  • Quên hộp thoại trust. Workspace chưa trust thì settings và hook đều không chạy, dù verify.mjs vẫn xanh. Thử một lệnh bị chặn trong Claude Code để chắc chắn.
  • Để agent merge ở repo merge là deploy. Một PR toàn tài liệu vẫn đi kèm một lần deploy thật.
  • Đặt AI review lên runner production. Apply tự né runner có chữ prod, nhưng nếu runner của bạn tên khác, hãy truyền --runs-on.
  • Coi hook là ranh giới bảo mật. Ba cách lách trong bài cho thấy shell luôn có đường vòng. Branch protection và quyền push mới là tường.
  • Allow rule có dấu sao rộng. git diff * nghe vô hại cho tới khi bạn nhớ ra --output và --ext-diff.
  • Để formatter đụng vào markdown. Bảng markdown trong các bài của series từng trông như bị vỡ: Biome pad cột cho thẳng hàng, rồi blog lại xuống dòng các dòng code dài. Giờ bảng viết gọn kiểu | a | b |, | --- | --- |, và biome.json của repo mẫu có "!**/*.md" để Biome không format markdown nữa.

Checklist

  • Worktree mới từ origin/main, branch riêng, đã xem PR đang mở và commit gần đây.
  • Audit đã chạy, gate và lệnh test một file đúng, đã tự đọc từng workflow để tìm đường deploy.
  • Dry run đã đọc, runner của AI review không phải runner production.
  • Apply xong, git status chỉ có file mới và .gitignore.
  • Phần Project trong AGENTS.md do người viết: bản đồ thư mục, test CI chạy thêm, lệnh không bao giờ chạy.
  • verify.mjs in all checks passed; trong Claude Code đã trust, một lệnh deploy bị hook chặn.
  • PR mở bởi người, merge bởi người. AI review để tắt cho tới khi chủ repo đồng ý.
  • Branch protection, agent không có quyền push, deploy cần người duyệt: ba thứ này đứng sau hook.

Trong series này

  1. Kiến trúc và vai trò của model
  2. Thiết lập repo cho Claude Code và Codex
  3. Spec, plan, tasks
  4. Làm song song và dùng nhiều nhà cung cấp
  5. CI/CD với AI review
  6. Vận hành: chi phí, bảo mật, vòng học và đo hiệu quả
  7. Áp dụng vào một dự án thật (phần thêm)

Nếu bạn thích xem hơn đọc, mình có video tóm tắt cả series và playlist trên YouTube.

Toàn bộ code nằm ở repo mẫu luonghongthuan/agentic-shortlink, tool của bài này nằm ở tools/agent-repo-setup. Các nguyên tắc đằng sau nằm trong bài viết mở đầu.

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