# 🤖 Agentic AI Workflow Checklist cho Web Developer Việt Nam

> **Dành cho ai?** Web developer VN đang tích hợp AI agent (Claude, Cursor, Copilot Workspace, v.v.) vào quy trình phát triển hàng ngày.
> **Cách dùng:** Copy file này vào Notion/Obsidian hoặc dùng trực tiếp trong repo. Tick checkbox trước mỗi session/sprint.

---

## Mục lục

- [Phần 1 — Setup Môi Trường](#phần-1--setup-môi-trường)
- [Phần 2 — Trước Khi Chạy Agent](#phần-2--trước-khi-chạy-agent)
- [Phần 3 — Review Output Agent](#phần-3--review-output-agent)
- [Phần 4 — Integrate vào CI/CD](#phần-4--integrate-vào-cicd)

---

## Phần 1 — Setup Môi Trường

> ✅ **Mục tiêu:** Đảm bảo hạ tầng AI agent hoạt động ổn định, bảo mật trước khi bắt tay vào task thực tế.

### 🔧 MCP Server (Model Context Protocol)

- [ ] **Cài đặt MCP server runtime** — Node.js ≥ 20 hoặc Python ≥ 3.11, kiểm tra bằng `node -v` / `python --version`
- [ ] **Clone/cài MCP server phù hợp dự án** — Ví dụ: `@modelcontextprotocol/server-filesystem` cho file ops, `mcp-server-git` cho Git
- [ ] **Cấu hình `mcp.json`** — Đặt ở `~/.config/mcp/mcp.json` hoặc root repo, định nghĩa đúng `command`, `args`, `env`
- [ ] **Whitelist thư mục cho phép agent truy cập** — Chỉ expose đúng project folder, KHÔNG expose `~/Documents` hay `/etc`
- [ ] **Test MCP server hoạt động** — Chạy `mcp dev server.js` và kiểm tra log không có lỗi kết nối
- [ ] **Setup MCP Proxy nếu dùng nhiều server** — Dùng `mcp-proxy` để route requests, tránh conflict port
- [ ] **Giới hạn timeout cho MCP calls** — Đặt `timeout: 30000ms` để tránh agent bị treo vô thời hạn
- [ ] **Log MCP requests ra file** — Dễ debug khi agent làm gì đó unexpected, đặt log level `info` minimum

### 🧩 VS Code Extensions

- [ ] **Cài Cline (hoặc Continue.dev)** — Extension ID: `saoudrizwan.claude-dev` / `Continue.continue`, đây là interface chính để chat với agent
- [ ] **Cài GitHub Copilot** (nếu dùng song song) — Tắt auto-complete nếu không cần, tránh conflict với Cline suggestions
- [ ] **Cài GitLens** — Giúp agent (và bạn) hiểu history code nhanh hơn khi review blame/diff
- [ ] **Cài ESLint + Prettier extensions** — Agent sẽ tự format code theo config của repo, không phải format tay
- [ ] **Cài Thunder Client hoặc REST Client** — Để test API endpoint agent tạo ra ngay trong VS Code
- [ ] **Enable "Workspace Trust"** — Vào `File > Preferences > Trust` — luôn review trước khi trust workspace mới
- [ ] **Cấu hình `.vscode/settings.json` cho team** — Đồng bộ extension recommendations qua `extensions.json`, tránh mỗi người setup khác nhau
- [ ] **Tắt telemetry nếu dự án nhạy cảm** — `"telemetry.telemetryLevel": "off"` trong settings

### 🔑 API Keys & Credentials

- [ ] **Tạo API key riêng cho dev environment** — KHÔNG dùng production key, lỡ agent call quá nhiều token sẽ không ảnh hưởng billing chính
- [ ] **Lưu API key vào `.env.local`** — File này phải có trong `.gitignore`, kiểm tra ngay bằng `git check-ignore -v .env.local`
- [ ] **Dùng secret manager cho team** — AWS Secrets Manager / Doppler / 1Password CLI, tránh share key qua Slack/Zalo
- [ ] **Set budget alert trên Anthropic/OpenAI dashboard** — Đặt threshold $10-$20/tháng cho dev, nhận email alert sớm
- [ ] **Rotate API key mỗi 90 ngày** — Đặt reminder trên lịch, ghi ngày tạo key vào comment trong `.env.example`
- [ ] **Kiểm tra scopes/permissions của key** — Chỉ cấp quyền tối thiểu cần thiết (principle of least privilege)
- [ ] **Setup rate limit monitoring** — Dùng dashboard của provider hoặc tool như Helicone để track usage theo ngày
- [ ] **Không hardcode key trong `mcp.json` public** — Dùng biến môi trường `${ANTHROPIC_API_KEY}` thay vì paste thẳng

### 🖥️ Môi Trường Tổng Thể

- [ ] **Tạo branch riêng cho AI-assisted work** — Convention gợi ý: `ai/feature-name` hoặc `agent/refactor-auth`, dễ track và revert
- [ ] **Snapshot môi trường trước khi agent chạy lần đầu** — `git stash` hoặc commit WIP, có điểm rollback sạch
- [ ] **Kiểm tra disk space** — Agent generate nhiều file tạm, cần ít nhất 2GB free trên ổ cài VS Code
- [ ] **Setup `.agentignore`** (nếu tool hỗ trợ) — Liệt kê file/folder agent không được đọc: `node_modules`, `.env`, `secrets/`

---

## Phần 2 — Trước Khi Chạy Agent

> ✅ **Mục tiêu:** "Garbage in, garbage out" — Prompt rõ ràng và context đầy đủ = output chất lượng cao, ít phải sửa.

### 🎯 Define Goal Rõ Ràng

- [ ] **Viết goal theo format cụ thể** — Thay vì *"làm cái login"*, hãy viết: *"Tạo login form với email/password, validate client-side bằng React Hook Form, call API POST /auth/login, handle lỗi 401/422, redirect về /dashboard"*
- [ ] **Chia nhỏ task lớn thành subtasks** — Mỗi agent session nên giải quyết 1 task ≤ 4 giờ dev thực tế, agent càng focused càng ít lỗi
- [ ] **Xác định output mong muốn** — Code? File config? PR description? Test cases? Nói rõ format và location
- [ ] **Liệt kê constraints** — Tech stack (Next.js 14, TypeScript strict, Tailwind v3), coding convention, performance budget
- [ ] **Xác định "Definition of Done"** — Agent biết khi nào dừng: *"Task xong khi có component + unit test + story Storybook"*
- [ ] **Tránh ambiguous pronouns trong prompt** — Thay *"nó"*, *"cái đó"* bằng tên cụ thể của file/function/component
- [ ] **Nếu task có nhiều cách giải** — Nói rõ preferred approach: *"Dùng React Query cho data fetching, không dùng Redux cho feature này"*

### 📋 Chuẩn Bị Context

- [ ] **Attach file liên quan trực tiếp vào context** — Types/interfaces, existing API client, auth hooks — những gì agent cần đọc để không tự reinvent the wheel
- [ ] **Export Figma component ra asset** — Dùng Figma Dev Mode, export spec (spacing, color token, breakpoint) dưới dạng text/JSON để paste vào prompt
- [ ] **Cung cấp API documentation** — Paste response example hoặc OpenAPI schema liên quan, agent đoán API structure = risk cao
- [ ] **Chia sẻ coding convention document** — File `.cursorrules` hoặc `CONTRIBUTING.md`, agent sẽ follow style của team
- [ ] **Chỉ ra file pattern tương tự trong codebase** — *"Tham khảo cách implement ở `components/ProductCard/`"* — học từ code có sẵn nhanh hơn hướng dẫn từ đầu
- [ ] **Cung cấp error message / stack trace** (nếu task là debug) — Đầy đủ, không cắt bớt, kèm context *"lỗi này xảy ra khi user logout trong khi đang upload file"*
- [ ] **Kiểm tra context window không bị overflow** — Claude 3.5 Sonnet: ~200k tokens. Với codebase lớn, chỉ đưa vào file thực sự cần thiết
- [ ] **Loại bỏ sensitive data khỏi context** — Ẩn real email, phone, API keys thật trong example data trước khi paste vào chat

### 🛑 Set HITL Triggers (Human-In-The-Loop)

> HITL = những điểm agent PHẢI dừng lại và hỏi bạn trước khi tiếp tục. Đây là safety net quan trọng nhất.

- [ ] **Định nghĩa rõ HITL trigger trong prompt đầu** — Ví dụ: *"Hỏi tôi trước khi: xóa file, thay đổi database schema, modify file ngoài thư mục `/src`"*
- [ ] **Set trigger cho database operations** — Bất kỳ `migration`, `DROP`, `ALTER TABLE` nào đều cần xác nhận manual
- [ ] **Set trigger khi agent uncertain** — Yêu cầu agent nói *"Tôi không chắc về X, bạn muốn tôi..."* thay vì tự đoán
- [ ] **Set trigger cho external API calls** — Agent không được call 3rd party API (Stripe, Twilio, SendGrid) trong dev session không có mock
- [ ] **Set trigger khi thay đổi ảnh hưởng > 5 files** — Đây thường là sign of scope creep, cần review plan trước
- [ ] **Set trigger cho security-sensitive code** — Authentication, authorization, encryption, input sanitization — luôn cần human review
- [ ] **Cấu hình "ask mode" vs "auto mode"** — Trong Cline: set mode "ask" cho task mới, chỉ dùng "auto" cho task lặp lại đã verify
- [ ] **Đặt checkpoint review định kỳ** — Với task dài, yêu cầu agent *"Sau mỗi 30 phút hoặc sau mỗi major step, tóm tắt đã làm gì và hỏi có tiếp tục không"*

---

## Phần 3 — Review Output Agent

> ✅ **Mục tiêu:** Không merge code agent generate mà không review kỹ. Agent giỏi nhưng không biết business context và không chịu trách nhiệm production.

### 🔍 Kiểm Tra Code Quality

- [ ] **Đọc toàn bộ diff trước khi accept** — Dùng `git diff` hoặc VS Code Source Control panel, không click "Accept All" mà không đọc
- [ ] **Kiểm tra TypeScript types không bị `any`** — Agent hay dùng `any` để tránh lỗi nhanh, thay bằng proper type hoặc `unknown`
- [ ] **Verify không có magic numbers/strings** — Constants phải được đặt tên rõ: `const MAX_RETRY = 3` thay vì `if (count > 3)`
- [ ] **Kiểm tra error handling đầy đủ** — Try/catch phải có meaningful error message, không được swallow errors bằng empty catch `{}`
- [ ] **Review naming conventions** — Function/variable names phải rõ nghĩa, follow convention của codebase hiện tại
- [ ] **Kiểm tra không có dead code** — Agent đôi khi để lại code cũ bị comment out hoặc unused imports
- [ ] **Verify không có hardcoded credentials/URLs** — Grep nhanh: `grep -r "localhost\|api_key\|password" src/` trên code mới
- [ ] **Kiểm tra performance obvious issues** — N+1 query trong loop, missing `useCallback`/`useMemo` ở hot path, large bundle imports
- [ ] **Review logic business có đúng không** — Agent viết code đúng syntax nhưng logic nghiệp vụ có thể sai, bạn mới là người hiểu yêu cầu

### 🧪 Test Coverage

- [ ] **Chạy existing test suite ngay sau khi agent generate code** — `npm test` hoặc `pnpm test` — không để broken tests tồn tại qua đêm
- [ ] **Verify unit tests agent viết thực sự test logic** — Tránh test chỉ "trust the mock" hoặc assert `toBeTruthy()` vô nghĩa
- [ ] **Kiểm tra test coverage cho happy path** — Scenario chính hoạt động đúng không? Đây là minimum bar
- [ ] **Kiểm tra test coverage cho error paths** — API trả về 500, network timeout, invalid input — những case này agent hay bỏ qua
- [ ] **Thêm integration test nếu agent chưa viết** — Đặc biệt với flow quan trọng: checkout, auth, payment
- [ ] **Chạy test với data thực tế (sanitized)** — Dùng production-like data thay vì `"test"`, `"foo"`, `123` — reveal nhiều bug hơn
- [ ] **Verify snapshot tests không bị stale** — Nếu agent update component, snapshot cũ có thể outdated, cần regenerate có chủ đích
- [ ] **Check test độc lập với nhau** — Tests không được share state, mỗi test tự setup và teardown

### ⚠️ Edge Cases

- [ ] **Test với empty/null/undefined inputs** — Đặc biệt với data từ API, luôn có khả năng field bị null
- [ ] **Test với Vietnamese characters** — Tên, địa chỉ, mô tả có dấu: *"Nguyễn Văn Ánh"*, *"Đà Nẵng"* — encoding issues rất phổ biến
- [ ] **Test với large data sets** — List 1000 items, file 10MB upload, string 10.000 ký tự — performance degrade rõ rệt
- [ ] **Test với concurrent requests** — User click button 2 lần nhanh, race condition trong async code
- [ ] **Test responsive trên mobile (375px)** — Agent thường design cho desktop trước, mobile hay bị overflow/overlap
- [ ] **Test với slow network** — Chrome DevTools > Network > Slow 3G — loading states, error states hoạt động không?
- [ ] **Test với user permissions khác nhau** — Admin vs user thường vs guest — agent hay hardcode assume role cao nhất
- [ ] **Test timezone edge cases** — Nếu có date/time logic, test với UTC+7 (VN), UTC+0, và boundary giữa ngày
- [ ] **Test browser compatibility** — Safari trên iOS hay có quirks với CSS Grid, date parsing, WebKit-specific bugs
- [ ] **Kiểm tra accessibility cơ bản** — Tab navigation, aria-label cho icon buttons, color contrast — dễ miss khi chỉ nhìn visual

### 🔐 Security Review

- [ ] **Kiểm tra input validation ở server side** — Client validation chỉ là UX, không phải security. Agent đôi khi chỉ validate client
- [ ] **Verify không có XSS vulnerability** — Tránh `dangerouslySetInnerHTML` với user input, review output encoding
- [ ] **Kiểm tra authorization logic** — Không chỉ authentication. User A không được xem data của User B dù đã đăng nhập
- [ ] **Review SQL queries nếu có** — Raw query phải dùng parameterized, không interpolate string từ user input

---

## Phần 4 — Integrate vào CI/CD

> ✅ **Mục tiêu:** Agent chạy trong pipeline phải có guardrails chặt hơn local dev. Automation + oversight = safe AI workflow.

### ⚙️ GitHub Actions Hooks

- [ ] **Tạo workflow file riêng cho AI tasks** — `.github/workflows/ai-agent.yml`, tách biệt với CI pipeline chính để dễ disable nếu cần
- [ ] **Trigger workflow đúng event** — `pull_request` với `types: [labeled]`, chỉ chạy khi có label `ai-assisted` để không tốn cost
- [ ] **Cấu hình `permissions` tối thiểu trong workflow** — `contents: read`, `pull-requests: write` — không cấp `admin` hay `packages: write` nếu không cần
- [ ] **Set `timeout-minutes`** cho mỗi step agent — Gợi ý: 15 phút cho code gen, 30 phút cho test gen. Tránh runaway jobs tốn tiền
- [ ] **Cache dependencies đúng cách** — `actions/cache` cho `node_modules`, `.next/cache` — agent tasks chạy nhanh hơn, cost thấp hơn
- [ ] **Setup notification khi agent workflow fail** — Slack webhook hoặc GitHub issue auto-create, không để fail âm thầm
- [ ] **Dùng `concurrency` group để tránh duplicate runs** — Cùng PR không nên chạy 2 agent jobs song song
- [ ] **Lưu agent output/logs như artifacts** — `actions/upload-artifact` với retention 7 ngày, audit trail khi cần điều tra

```yaml
# Ví dụ snippet cơ bản
name: AI Agent Task
on:
  pull_request:
    types: [labeled]
jobs:
  ai-review:
    if: contains(github.event.label.name, 'ai-assisted')
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read
      pull-requests: write
```

### 🔒 Agent Permissions trong Pipeline

- [ ] **Không cấp agent quyền push thẳng lên `main`/`develop`** — Agent chỉ được tạo PR, không được merge. Đây là rule không được ngoại lệ
- [ ] **Dùng dedicated bot account cho agent** — Tạo GitHub account `yourproject-ai-bot`, assign minimal permissions, dễ audit và revoke
- [ ] **Lưu API keys của agent trong GitHub Secrets** — `Settings > Secrets > Actions`, không phải trong repo hay environment variables public
- [ ] **Enable branch protection rules** — Require PR review dù code từ bot, `min 1 approval` từ human trước khi merge
- [ ] **Restrict agent access theo environment** — Agent có thể deploy lên `staging`, KHÔNG được touch `production` environment
- [ ] **Audit log agent activities** — GitHub Audit Log (Enterprise) hoặc tự log mọi action của bot account ra external storage
- [ ] **Set spending limits cho API calls trong pipeline** — Khác với dev local, pipeline có thể trigger nhiều lần/ngày — cần hard limit
- [ ] **Review và rotate bot account tokens định kỳ** — Mỗi 60 ngày, đặt reminder, revoke token cũ ngay khi rotate

### 🔁 Rollback Plan

- [ ] **Đảm bảo mọi AI-generated change có revert commit rõ ràng** — Convention: `revert: ai-generated [feature-name] - reason: [lý do]`
- [ ] **Document rollback command trong README** — Ai trong team cũng có thể rollback, không chỉ người setup: `git revert HEAD~3 --no-edit`
- [ ] **Test rollback procedure trước khi merge** — Thực sự chạy rollback trên staging, confirm app hoạt động bình thường sau khi revert
- [ ] **Setup feature flags cho AI-generated features lớn** — Dùng `@unleash/nextjs` hoặc LaunchDarkly, tắt feature ngay lập tức không cần redeploy
- [ ] **Backup database trước khi agent chạy migration** — Automated snapshot trước mỗi migration job, retention tối thiểu 24 giờ
- [ ] **Chuẩn bị runbook cho incident** — Doc ngắn: triệu chứng → diagnosis steps → rollback command → người liên hệ. Để trong `docs/runbooks/`
- [ ] **Monitor error rate sau deploy code từ agent** — Datadog / Sentry alert nếu error rate tăng >5% trong 15 phút sau deploy
- [ ] **Communicate rollback plan với team** — Cả team biết khi nào nên rollback, không cần escalate lên senior mới dám revert
- [ ] **Post-mortem sau mỗi incident liên quan agent** — Doc ngắn: gì xảy ra, tại sao, fix gì, prevent gì. Không blame, chỉ improve

---

## 📌 Quick Reference — Red Flags Cần Dừng Lại Ngay

| 🚩 Tình huống | ⚡ Hành động |
|---|---|
| Agent muốn xóa file không trong scope | Dừng, hỏi lại goal |
| Agent tự thay đổi `.env` hoặc config files | Revert ngay, review lại permissions |
| Test suite fail sau agent commit | Không push, fix trước |
| Agent generate >500 lines trong 1 lần | Chia nhỏ task, review từng phần |
| Agent dùng library không có trong `package.json` | Review security + license trước khi accept |
| Code review thấy `any` type > 3 lần | Yêu cầu agent rewrite với proper types |
| Pipeline cost tăng đột biến | Check runaway jobs, set spending alert |

---

## 📝 Ghi Chú Cuối

> **Nguyên tắc vàng:** Agent là *junior developer rất giỏi kỹ thuật nhưng không biết gì về business của bạn*. Bạn là tech lead — review, guide, và take responsibility cho mọi line code merge vào repo.

**Cập nhật checklist này khi:**
- Upgrade version của AI model/tool
- Onboard project mới với tech stack khác
- Phát sinh incident liên quan đến AI-generated code
- Team có thêm member mới cần onboard workflow

---

*Checklist version 1.0 — Cập nhật lần cuối: 2025 | Đóng góp & feedback: tạo PR hoặc mở Issue trong repo của team bạn* 🇻🇳