Quy trình làm việc với agent: cổng người đứng, việc agent làm

00Câu hỏi

• Người nên tham gia ở bước nào, agent tự chạy ở bước nào?
• Ngoài tool, các đối tượng (env, vai, flow, step, fixture, report…) tổ chức thế nào, có cần schema không?
• Quy trình một tính năng và quy trình cả dự án chia pha ra sao?
• Loại task khác nhau có cần quy trình khác nhau không?
• Có nên sửa tool ngay trong lúc test sản phẩm?
• Chia người theo chức danh cũ, theo loại task, hay cách khác?

01Người đứng ở đâu: bốn cổng

• Người xem ở mức tóm tắt. Phải mở từng ảnh hay đọc log thô là tool chưa đạt.
• Sự tham gia giảm dần theo độ chín: flow mới xem kỹ lần đầu xanh, sau chỉ xem khi fail.

02Bắt đầu từ “xong là gì”

Agent làm tốt phần “làm thế nào” và kém phần “đúng là gì”. Bắt đầu bằng mô tả cách làm là làm thay agent việc nó giỏi và bỏ trống việc chỉ người làm được. Bắt đầu trong chat thì ý định mất khi phiên kết thúc.

Chưa trả lời được câu “bằng chứng nào chứng minh” thì việc chưa sẵn sàng giao. Thấy mình đang viết bước thao tác hay chọn tool là đã đi xuống tầng của agent: việc cần làm là sửa tiêu chí hay sửa tool, không phải tự nhảy vào làm.

03Các đối tượng ngoài tool

Tool là động từ, các đối tượng là danh từ, và danh từ quyết định tái sử dụng được hay không. Xếp theo hai trục: thuộc về ai, và đổi nhanh hay chậm. Càng chung và càng chậm đổi thì càng lên cao (kit, hub, repo); càng riêng và càng nhanh đổi thì càng ra ngoài repo (local, bàn làm việc).

flow ──needs──▶ vai ──resolve qua──▶ env ──đọc──▶ secret (ref)
 ├──use──▶ step ──dùng──▶ testid
 ├──with──▶ fixture
 ├──chạy trên──▶ profile
 └──nhận──▶ bộ data ──sinh ra──▶ bằng chứng

• Flow không chứa URL, tài khoản, đường dẫn máy; chỉ tên vai và tên fixture. Đổi env là đổi “mock” hay “thật”, không nhân đôi flow.
• Đặt tên flow theo phân hệ và hành vi, không theo thiết bị. Tag (smoke, regression, quyền) thay cho hậu tố tên file. Chuỗi bước là flow con, không đánh số trong tên.
• Fixture bất biến; thứ flow tạo ra mang tiền tố test và id lần chạy, có bước dọn.
• Mỗi lần chạy ra một report.json cùng schema dù bước chạy bằng engine nào.

04Định nghĩa ở đâu, có schema không

Schema tập trung trong kit, nội dung phân tán theo chủ sở hữu. Có schema cho mọi thứ máy đọc, không cần cho thứ chỉ người và agent đọc.

• Schema có version và lệnh migrate, nếu không kit đóng băng.
• Mở rộng có kiểm soát: khung đóng, bước cho phép trường riêng theo engine.
• Kit là repo riêng, không phải thư mục trong hub, vì hub chứa dữ liệu của một sản phẩm.

05Quy trình một việc

• Ba điểm ép: không có goal và nghiệm thu thì không vào bước 5; report là đầu vào duy nhất cho deploy; flow đã dùng nghiệm thu tự thành hồi quy.
• Bước 4 trước bước 5 là thay đổi lớn nhất: tiêu chí nghiệm thu được máy hoá trước khi code. Bước 3 cho phép song song backend và client trên spec và mock.
• Người chỉ xuất hiện ở 1, 2, 3, 4 (lần đầu), 6, 7, 8. Việc nhỏ và rõ thì bỏ bớt bước (mục 7).

06Quy trình cả dự án: năm pha

“Nháp, hồi quy, fix, lặp đến khi khách ổn” về cơ bản đúng, với agent càng đúng vì code nháp rẻ. Ba chỗ hay vỡ: “khách thấy ổn” không phải điều kiện dừng; nháp bị khoá thành kiến trúc; hồi quy phình không kiểm soát. Giữ vòng lặp nhưng đặt vào năm pha có điều kiện ra.

Khách tham gia hai lần với hai câu hỏi khác nhau: pha 1 “đây có phải thứ anh muốn không”, pha 3 “đây có chạy đúng như đã chốt không”. Trộn hai câu là lý do vòng lặp không kết thúc.

07Hồ sơ theo loại task

Loại task khác nhau nên khác ở cổng và bằng chứng, không khác ở khung. Khung chung giữ bốn thứ: hợp đồng viết ra trước khi làm, bằng chứng do máy sinh, người giữ cổng đúng chỗ, bài học gom về rules. Phân loại theo hai trục: độ mơ hồ của “đúng là gì” và phạm vi ảnh hưởng.

• Sáu hồ sơ gốc là đủ; loại khác là biến thể thêm một hai điểm ép. Đừng làm 25 file rules.
• bugfix cấm bắt đầu khi chưa có repro đỏ; agent rất hay sửa triệu chứng nếu không bị buộc tái hiện trước.
• visual-tweak là loại duy nhất hợp đồng chữ không đủ: vòng lặp ngắn agent sửa, chụp, người nhìn, nói một câu.
• Một task có thể đổi hồ sơ giữa chừng. Bug nhỏ truy ra lỗi thiết kế thì dừng, chuyển sang feature hoặc research; agent phải nói rõ “việc này vượt hồ sơ”.
• Mỗi hồ sơ một file ngắn trong kit doc/rule/; agent đọc đúng file theo nhãn task.

08Sửa tool trong lúc test

Nên, nhưng phân tầng. Nhu cầu thật về tool chỉ lộ ra khi đang test. Hai rủi ro cần chặn: nhiễm kết quả (pass vì sản phẩm đúng hay vì tool vừa đổi cách đo) và trôi thiết kế (mỗi lần kẹt thêm một ngoại lệ).

• Tách commit và tách run; report ghi version tool.
• Sửa tool chỉ được chặt hơn hoặc rộng hơn, không lỏng hơn. Nới ngưỡng, bỏ assert, thêm sleep là che lỗi: ghi gap thay vì sửa.
• Mỗi lệnh sửa có một check đi kèm trong lệnh kiểm hoặc test của CLI.

09Chia người trong đội

Chia theo cổng họ chịu trách nhiệm (trục ngang) và module họ lái (trục dọc), không theo chức danh cũ, không theo loại task. Chức danh cũ chia theo năng lực sản xuất, thứ agent đã làm phần lớn; loại task là thuộc tính của việc, không phải của người.

• Bốn vai đầu giữ cổng, ít người. Người lái là vai sản xuất mới, đông nhất, mỗi người sở hữu vài module và làm mọi loại task trên đó; hồ sơ cho biết phải gõ cửa cổng nào.
• Đội nhỏ gộp vai nhưng nói rõ đang đội mũ nào khi đứng ở cổng. Được gộp chủ ý định với chủ bằng chứng; không gộp cổng kit và cổng vận hành vào dự án.
• Tách người viết request và người phán xét kết quả với task phạm vi rộng.
• Agent cũng tách vai theo phiên: nghiên cứu, thực thi, review là ba phiên riêng để review không thiên kiến bởi code nó viết.
• Phòng ban: chủ ý định, chủ bằng chứng, người lái ngồi trong dự án (hàng đợi giữa phòng giết tốc độ của agent). Chủ kit và chủ vận hành ở đơn vị dùng chung, vì kit và secret phải sống lâu hơn dự án. Chưa có hai dự án dùng chung thì chưa lập đơn vị kit.
• Vòng vận hành: dự án pin kit theo version → người lái làm task theo hồ sơ → bằng chứng → phán xét → report xanh sang cổng vận hành → chỗ kit cản thì ghi gap → đơn vị kit gom theo đợt, ra version mới.

10Phiên làm việc: mở ở đâu, bắt đầu thế nào

• Phiên đặt tiêu chí và phán xét mở ở thư mục cha của máy, đứng ngoài mọi repo: việc cắt ngang nhiều repo, bằng chứng ở bàn làm việc, memory của agent tích luỹ ở một chỗ.
• Phiên làm theo request mở trong repo nền tảng hoặc hub khi việc nằm trọn trong đó và cần ngữ cảnh riêng. Hai loại phiên tách nhau.
• Không mở phiên trong thư mục bản chạy và thư mục secret.
• Mỗi phiên bắt đầu bằng đọc tóm tắt phiên trước (work/run/<ngày>/README.md) và hộp request; kết thúc bằng ghi tóm tắt: đã làm gì, bằng chứng ở đâu, còn gì.
• Mỗi task một phiên sạch; tiến độ ghi ra file, phiên mới đọc lại từ file. Thứ bắt buộc phải xảy ra mỗi lần thì làm thành hook, không làm thành lời dặn trong CLAUDE.md.

Cây thư mục và cách luật nạp vào phiên: ghi chú 2, mục thư mục cha.

11Đối chiếu với cộng đồng

Hướng đi trên gần với đồng thuận 2025–2026 ở ba điểm: spec nằm trong repo chứ không trong chat (spec-driven); người review plan chứ không chỉ review code; CLI cho agent với mỗi lệnh một việc, xuất JSON, exit code rõ. Những thứ mượn thêm:

Engine test (Playwright, Maestro) có format ổn định mà agent biết sẵn; DSL riêng nên mỏng, giữ lớp nghiệp vụ, uỷ lớp tương tác. Chi tiết ở ghi chú 2.

12Ví dụ MiniGate

13Việc còn mở

• Engine chuẩn cho cả công ty: Playwright cho web và Electron, Maestro cho mobile là đề xuất; thử trên một sản phẩm mỗi loại trước khi chốt.
• Flow JSON thuần hay cho phép JS? Đề xuất JSON thuần, logic ở driver.
• Schema report đủ để người đọc vài phút một đợt chưa; runner nào xuất đúng schema.
• Ngân sách token cho eval và loop: ai duyệt, trần bao nhiêu mỗi đội.
• Chạy đủ khung này trên một tính năng thật, ghi lại chỗ bị cản rồi chỉnh.

Người bắt đầu ở chỗ đặt tiêu chí và chỉ quay lại ở chỗ phán xét theo tiêu chí đó. Khoảng giữa là của agent.