3. Triển khai & Production / Phần 10

10. Một graph thực tế cho Codex hoặc Antigravity

Giả sử yêu cầu:

“Thêm chức năng hủy booking. Không cho hủy khi khách đã check-in; hoàn tiền theo policy; cập nhật UI và test.”

10.1 Cách one-shot dễ thất bại

Một prompt duy nhất có thể khiến agent:

đoán tên model và endpoint;
sửa frontend trước khi hiểu backend;
tạo rule hoàn tiền không khớp policy;
không thấy background job hoặc audit log;
chỉ chạy test ở file vừa tạo;
thay đổi ngoài scope.

10.2 Graph đề xuất

Luồng Thực Thi 8 Node Chuẩn Cho Coding Agent

START
  ↓
Clarify goal
  ↓
Map repository
  ↓
Retrieve domain rules
  ↓
Plan change
  ↓
Plan review ── risky/ambiguous ──→ Human clarification
  ↓ approved
Write failing tests
  ↓
Implement smallest patch
  ↓
Run focused tests
  ├─ fail → Diagnose → Revise ─┐
  └─ pass                     │
      ↓                       │
Run full checks               │
  ├─ fail → Diagnose ─────────┘
  └─ pass
      ↓
Security & business review
  ├─ critical finding → Revise
  └─ clean
      ↓
Human approval for merge/deploy
      ↓
END

10.3 State contract

CodingState Dataclass Schema

class CodingState:
    goal: str
    acceptance_criteria: list[str]
    assumptions: list[str]
    repository_map: dict
    domain_rules: list[dict]
    plan: list[dict]
    files_allowed: list[str]
    patch_summary: str
    test_commands: list[str]
    test_results: list[dict]
    review_findings: list[dict]
    iteration: int
    max_iterations: int
    status: str

10.4 Node 1 - Clarify goal

Output không phải bài văn. Nó nên là:

Goal Clarification Output

{
  "acceptance_criteria": [
    "Booking ở trạng thái checked_in không thể hủy",
    "Refund được tính từ policy hiện có, không tạo công thức mới",
    "Mọi lần hủy tạo audit event",
    "UI hiển thị lý do khi action bị khóa"
  ],
  "open_questions": [
    "Ai có quyền override policy?"
  ],
  "risk_level": "high"
}

Nếu open_questions ảnh hưởng business rule, edge chuyển tới human clarification. Agent không được tự bịa.

10.5 Node 2 - Map repository

Tool chỉ đọc:

tìm entity Booking, Payment, Refund;
tìm route hiện có;
tìm test tương tự;
đọc migration convention;
đọc tài liệu domain;
ghi file path và trích đoạn liên quan vào state.

Mục tiêu là xây context pack nhỏ, có nguồn, thay vì nạp cả repository.

10.6 Node 3 - Plan change

Mỗi step trong plan nên có:

mục tiêu;
file dự kiến;
contract bị ảnh hưởng;
test chứng minh;
rủi ro;
dependency.

Planner không viết code. Tách planning khỏi implementation giúp review scope trước khi patch lớn xuất hiện.

10.7 Node 4 - Viết test trước

Không nhất thiết áp dụng test-driven development cứng cho mọi task, nhưng với business rule, test trước rất hữu ích. Nó biến yêu cầu thành executable specification.

Các case tối thiểu:

hủy booking hợp lệ;
từ chối khi đã check-in;
refund đúng từng policy boundary;
idempotency khi request lặp;
unauthorized user;
audit event;
UI state và error message.

10.8 Node 5 - Implement smallest patch

Prompt của coder nên có:

goal và acceptance criteria;
relevant files;
plan đã duyệt;
failing tests;
coding conventions;
phạm vi file được sửa;
yêu cầu không refactor ngoài scope.

Model mạnh hơn không thay thế scope control. “Smallest patch” giảm surface area của lỗi và làm review dễ hơn.

10.9 Node 6 - Test và diagnose

Đừng đưa toàn bộ log hàng chục nghìn dòng cho model. Tool nên parse:

command;
exit code;
test failed;
stack trace liên quan;
changed files;
thời gian;
flaky signal nếu có.

Node diagnose phải phân biệt:

implementation bug;
test expectation sai;
environment/config lỗi;
dependency không sẵn;
lỗi có sẵn trước patch.

Nếu cùng signature lỗi xuất hiện ba lần, dừng loop và yêu cầu người hỗ trợ. Đây là loop guard.

10.10 Node 7 - Review độc lập

Reviewer không nên nhận chain-of-thought của coder như chân lý. Hãy cho reviewer:

requirement;
diff;
test result;
domain rules;
checklist bảo mật.

Review theo category:

correctness;
business invariant;
auth/permission;
data migration;
transaction và concurrency;
backward compatibility;
observability;
maintainability;
scope creep.

10.11 Node 8 - Human approval

Gói duyệt nên ngắn và có bằng chứng:

Gói Duyệt Phê Duyệt Mẫu

Mục tiêu: thêm cancel booking
Files changed: 7
Tests: 42 passed, 0 failed
Business rules: 6/6 covered
Security findings: 0 critical, 1 low
Migration: none
Known limitation: refund provider sandbox chưa có end-to-end test
Action requested: approve merge, chưa deploy production

Đây là cách biến coding agent từ “người viết code nhanh” thành một worker trong hệ thống kỹ nghệ có kiểm soát.