ghi chú làm việc · MiniGate · 2026-11-05, bổ sung 2026-11-06

Quy trình làm việc với agent: tool, flow, đối tượng và chỗ người phải đứng

Tổng hợp buổi trao đổi về cách tối ưu công cụ test / debug qua CLI từ hiện trạng MiniGate để tái dùng cho dự án sau, và cách tổ chức quy trình để chủ dự án bớt phải quản lý trực tiếp. Mục 12–16 mở rộng sang câu hỏi lớn hơn: quy trình thực hiện dự án, hồ sơ theo loại task, vai trò người và cách tổ chức phòng ban khi dùng agent.

Nguồn số liệu: mgctl, cpctl, wsctl, deskctl, minigate, rt trên server test, ngày 2026-11-05. Kết luận là đề xuất, chưa phải quyết định.

00Câu hỏi gốc

Đang có nhiều CLI cho agent (mgctl, cpctl, wsctl, deskctl, minigate, rt) và nhiều flow test khai báo. Muốn tối ưu lại để tái dùng cho dự án sau. Chuỗi câu hỏi đã đi qua:

  1. Cách đưa tool cho AI qua CLI và định nghĩa flow có phải hướng đi hợp lý so với cộng đồng không?
  2. Ngoài tool, các đối tượng khác (env, role, flow, step, fixture, report…) tổ chức thế nào?
  3. Các đối tượng đó định nghĩa ở đâu, có cần structure không?
  4. Có nên sửa tool ngay trong lúc test / debug sản phẩm không?
  5. Người nên tham gia ở bước nào?
  6. Quy trình của cả dự án nên chia pha ra sao: nháp trước rồi lặp hồi quy đến khi khách ổn?
  7. Khi làm việc với agent, tôi bắt đầu ở đâu: theo nguyên lý, và theo thư mục nào của dự án?

01Hiện trạng tóm tắt

Có 6 CLI và 4 “engine flow” khác nhau cùng một ý tưởng (flow JSON gồm steps, params, expect, shot, dùng testenv) nhưng mỗi cái tự viết schema và runner riêng. Code dùng chung bị chép tay giữa repo: find-common.js giống hệt ở 3 repo, schema.js giống ở desktop và mobile, util.js mỗi repo một bản, testenv.js và mgctl.js lệch dần.

deskctl flowminigate flowwsctl e2emgctl flow
Đối tượngElectron (CDP)Android / iOS (adb, xcrun)Web (Chrome)API + gọi CLI khác
Bước phổ biếnexpect 704 · shot 331 · wait 299 · use 180 · type 146run 583 (chuỗi lệnh con) · expect 534eval 473 (JS thô) · shot 367 · click 362 · sleep 325args 75 · as 66 · expect 63 · save 16
Chỉ phần tử#chat.row.c3 hoặc css=…chat-thread.pinned-bar (có *)CSS trong eval / clickkhông (API)
Bước tái dùnguse + steps/*.jsonkhônguse + steps/*.jsonflow con + cli
Vai tròtestEnvroles A/B + {{testEnv.user}}role (1 lần)as + needs theo testenv
Điều kiện / lặpkhôngkhôngkhôngwhen
ChờtimeoutMs 281 · sleep 27timeoutMs 459sleep 325 · wait 228không cần
  • wsctl e2e đã rò rỉ ra JS. 473 bước eval và 325 sleep nghĩa là DSL không đủ diễn đạt, người viết nhảy xuống code và chờ cứng.
  • minigate flow thực chất là shell script dạng JSON. Tốt cho agent (mỗi bước chạy tay được) nhưng không có lớp step nên 281 lần input tap dính thẳng vào testid.
  • mgctl flow là lớp khác hẳn. Không chạm UI, chỉ điều phối vai trò, params, flow con, gọi CLI khác, lưu kết quả. Đây là lớp đáng giữ nhất.

Phần làm tốt và nên giữ: config + .local.json, testenv theo vai trò, mgctl api đăng nhập như app, bộ data + .runs báo cáo, doctor, quy ước testid module.screen.element dùng chung desktop và mobile.

02Hướng đi có hợp lý so với cộng đồng?

Có. “CLI cho AI + flow khai báo + testenv theo vai trò + bằng chứng mỗi lần chạy” là dòng chính 2025–2026.

  • CLI thay vì tool-call / MCP. Anthropic (bài “code execution with MCP”) và OpenAI Codex đều chỉ ra: agent gọi lệnh rồi tự đọc output tiết kiệm token và dễ ghép hơn nạp hàng chục tool definition. Vercel ra agent-browser dạng CLI vì lý do này.
  • Test như dữ liệu. Maestro (mobile) dùng YAML flow: tapOn, assertVisible, runFlow con. Cấu trúc flow JSON của MiniGate gần như song song.
  • Progressive disclosure cho agent. help ngắn, _doc trong config, skill, doctor: đã có.
  • Evidence và reproducibility. Bộ data + .runs khớp xu hướng.

Chỗ cộng đồng làm khác

  1. Tránh DSL tự chế khi đã có sẵn. Maestro, Playwright, WebdriverIO có format ổn định, agent biết sẵn cú pháp. DSL riêng nên mỏng: giữ lớp nghiệp vụ, uỷ lớp tương tác cho engine chuẩn. Bốn runner tự viết là đi hơi xa.
  2. Một lệnh một việc, in JSON. --json, stdout là kết quả, stderr là log, exit code có nghĩa, không hỏi khi không có TTY. mgctl đã theo, rt (menu + xác nhận) thì chưa.
  3. Test chính tool. Ai test runner? Mobile có 2 file test, còn lại không.
  4. Flaky là bài toán chính. Auto-wait, retry, trace là nơi Maestro / Playwright đầu tư nhiều nhất và DSL riêng phải tự gánh.

03Flow riêng so với Maestro và Playwright

Nhu cầuHiện tại (3 runner UI)Maestro (mobile, YAML)Playwright (web / Electron)Nhận xét
Tìm phần tửtestid, mỗi runner một cú phápid, text, regex, indexgetByTestId / Role / Textengine ngoài có 4–5 cách, ta chỉ có testid
Auto-waitkhông, dùng timeoutMs / sleepcócóchỗ ta tốn công nhất, họ cho sẵn
Assertexpect + text / contains / visible / gone / attr / countassertVisible, assertNotVisible, assertTrue20+ matcherđủ dùng nhưng tự bảo trì
Flow conuse + stepsrunFlow + envhàm / fixturengang nhau
Vai trò, testenvmạnhchỉ envstorageState theo tài khoảnta mạnh hơn, đây là lớp nghiệp vụ
Điều kiện, lặpkhôngrunFlow when, repeatJS đầy đủthiếu, nên có 4 flow na ná (chat-hai-nguoi-0/1/2/3)
Ảnh, trace, reportshot + .runs + Telegramscreenshot, record, JUnit / HTMLtrace viewer, HTML report, videotrace viewer là thứ ta không có
Hai máy / hai vaimobile có roles A/Bkhôngnhiều context trong 1 testPlaywright hơn, Maestro kém ta
Agent biết sẵn cú pháp?không, đọc help mỗi phiêncócóchi phí ẩn của DSL riêng
ElectronCDP tự viết (page.js 363 dòng)khônghỗ trợ chính thứcthay hẳn được lớp CDP
Android / iOSadb / xcrun tự viếthỗ trợ chính thứckhôngthay được lớp input / expect
Giấy phépcủa taApache-2.0Apache-2.0dùng thương mại được

Giữ gì, uỷ gì

Giữ (lớp nghiệp vụ, không ai có): testenv theo vai trò, as / needs, tài khoản bảo vệ, tiền tố [E2E] và dọn dữ liệu; mgctl flow làm bộ điều phối; lệnh đơn cho agent (api, shot, inspect, doctor); quy ước testid.

Uỷ cho engine ngoài (lớp tương tác): web và Electron → Playwright, bước UI dịch 1:1 hoặc bước playwright: <spec> để mgctl flow gọi rồi thu report. Mobile → Maestro cho input / expect, giữ app, shot, net, biometric, notif, log của minigate; hai máy thì mgctl flow điều phối 2 Maestro.

Cái giá: thêm 2 dependency lớn (Playwright kéo browser, Maestro cần Java), agent học 2 cú pháp, dịch lại flow hiện có (desktop ~40, mobile 28, ws vài chục). Đổi lại bỏ được 3 runner tự viết, có auto-wait và trace viewer, dự án sau chỉ mang theo lớp nghiệp vụ mỏng.

Phương án giữa: giữ DSL nhưng chuẩn hoá một schema step chung cho 3 runner UI, thêm auto-wait vào expect để bỏ sleep, đưa when / repeat xuống. Rẻ hơn nhưng vẫn tự nuôi engine.

Khuyến nghị: chọn uỷ, bắt đầu từ wsctl e2e vì rò rỉ nặng nhất và Playwright thay được trọn vẹn.

04Cá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 (mọi dự án, một dự án, một repo, một máy, một lần chạy) và đổi nhanh hay chậm.

Đối tượngNghĩaThuộc vềĐổiNằm ởCommit
Quy ướctestid, exit code, stdout/stderr, tên vai trò, [E2E]mọi dự ánrất chậmkit, 1 trangcó
Config lệnhtham số không bí mật của toolrepochậmconfig/<lệnh>.json + _doccó
Override máyghi đè riêng máymáytuỳ*.local.jsonkhông
Môi trườngserver + workspace + URL + vai trò dùng biến nàodự ánchậmcommon config/test-env.jsoncó
Bí mậtmật khẩu, token theo môi trườngdự ánhiếmsecrets/test-env/<env>.envrepo private
Vai tròadmin, chat1, works-staff2, mobile…dự ánchậmmột bảng duy nhất, cùng file envcó
Hồ sơChrome profile, emulator, máy thậtmáytrung bìnhconfig/profiles + localmột phần
Fixturedữ liệu mẫu bất biếnrepochậmfixtures/ cạnh flowcó
Bướcthao tác UI đặt tên: chat.send, auth.loginrepotrung bìnhsteps/<module>.jsoncó
Flowkịch bản nghiệp vụrepo (UI) / common (liên repo)nhanhflows/<module>/<tên>.jsoncó
Bộ datatham số một đợt chạytác vụmỗi đợtwork/<ngày>/<tác vụ>/không
Bằng chứngảnh, log, report.jsonlần chạymỗi lần<bộ data>/.runs/<id>/không
Tri thức agentskill, help, README thư mụcrepochậm.claude/skills, help/có
Hợp đồng APIOpenAPIrepo backendtrung bìnhopenapi/có

Nguyên tắc đặt chỗ: càng chung và càng chậm đổi thì càng lên cao (kit → common → repo); càng riêng và càng nhanh đổi thì càng ra ngoài repo (local → work → .runs).

Quan hệ giữa các đối tượng

flow ──needs──▶ role ──resolve qua──▶ env ──đọc──▶ secret
 │                                      │
 ├──use──▶ step ──dùng──▶ testid (quy ước)
 ├──with──▶ fixture
 ├──chạy trên──▶ profile (máy)
 └──nhận──▶ dataset ──sinh ra──▶ run / evidence
  • Flow không chứa URL, tài khoản, đường dẫn máy. Chỉ tên vai trò và tên fixture.
  • Step là nơi duy nhất biết testid. UI đổi testid thì sửa một chỗ.
  • Dataset tách khỏi flow để một flow chạy nhiều đợt, mỗi đợt có .runs riêng.

Quyết định tổ chức cụ thể

  • Một bảng vai trò cho toàn hệ thống; mobile cần 2 máy thì ánh xạ A → chat1, B → chat2.
  • Đặt tên flow theo module/hành-vi, không theo thiết bị. 4 flow chat-hai-nguoi-0..3 nên là 1 flow mgctl gọi 4 bước trên 2 vai.
  • Tag (smoke, that, quyen, hoi-quy) thay cho hậu tố tên file.
  • Fixture bất biến; thứ flow tạo ra mang [E2E] {run.id} và có bước dọn.
  • Mỗi run ra một report.json cùng schema dù bước chạy bằng engine nào.
  • Mỗi thư mục flows / steps / fixtures có README ngắn; skill chỉ trỏ tới, không chép.

05Đị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ó structure cho mọi thứ máy đọc, không cần cho thứ chỉ người và agent đọc.

TầngChứa gìỞ đâuAi sửa
Kitschema từng đối tượng, quy ước, runner lõi, template thư mụcrepo riêng (mg-cli-kit), có versionhiếm, có review
Dự áninstance env, role, profile, flow liên repo, contract, secretsrepo common của dự ánngười vận hành
Repostep, flow UI, fixture, config lệnh, tri thức agent<repo>/cli/dev của app
Ngoài repolocal override, dataset, run*.local.json, work/, .runs/máy, lần chạy

Hiện đã có tầng 2, 3, 4. Thiếu tầng 1: schema đang nằm trong repo app nên mỗi repo một bản. Đưa schema lên kit là thay đổi cấu trúc duy nhất cần làm. Mỗi file instance khai "$schema", runner validate lúc load.

Đối tượngStructureMức chặtLý do
Env, RoleJSON Schemachặt6 CLI cùng đọc
ReportJSON Schema, có versionchặtđiểm nối giữa mọi engine và consumer
Flow, StepJSON Schemachặt ở khung, mở ở bước (oneOf theo driver, x-*)bước UI khác theo driver
Config lệnhschema cạnh configvừanhư rt đang làm
ProfileJSON Schemavừatrộn local nên cần biết field hợp lệ
Fixturechỉ manifestlỏngnội dung tuỳ nghiệp vụ; manifest ghi giấy phép ảnh / font
Datasetsinh từ params của flowtự độngkhông viết tay
Tri thức agentkhôngtự doép schema chỉ gây phiền
Quy ướcvăn bảntự donhưng mỗi quy ước có một check trong doctor
  • Schema phải có version và lệnh migrate, nếu không kit đóng băng.
  • Mở rộng có kiểm soát: additionalProperties:false ở khung, cho phép x-<repo>-* hoặc with tự do trong bước.
  • Kit là repo riêng, không phải thư mục trong common, vì common chứa secrets và dữ liệu MiniGate.
mg-cli-kit/                      # tầng kit
  schemas/ env · role · flow · step · report · profile · config
  conventions.md
  template/                      # mgctl init-cli sinh từ đây

common_minigate/                 # tầng dự án
  config/test-env.json  config/profiles/  flows/<module>/  secrets/test-env/

<repo>/cli/                      # tầng repo
  steps/<module>.json  flows/<module>/*.json  fixtures/ + fixtures.json  config/<lệnh>.json

work/<ngày>/<tác vụ>/            # ngoài repo
  env.json  params.json  .runs/<id>/report.json

06Sửa tool trong lúc test / debug sản phẩm

Nên, nhưng phân tầng. Nhu cầu thật về tool chỉ lộ ra khi đang test; cấm sửa là tự bịt nguồn phát hiện. 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; agent có xu hướng nới expect, tăng timeout, thêm sleep) và trôi thiết kế (mỗi lần kẹt thêm một ngoại lệ).

TầngSửa trong lúc test?Điều kiện
Step, flow, fixtureCó, tự docommit riêng, tách khỏi commit sửa sản phẩm
Lệnh / flag mới CLI repoCó, tối thiểughi gap, có help, chạy lại flow từ sạch
Runner lõi, schema, quy ướcKhông sửa tại chỗghi gap kèm ví dụ, gom sửa theo đợt, nâng version kit

Ba kỷ luật

  1. Tách commit và tách run. Sửa tool xong chạy lại từ sạch; report có field toolVersion.
  2. 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. Đưa vào skill / CLAUDE.md cho agent.
  3. Mỗi lệnh sửa có một check đi kèm trong doctor hoặc test của CLI.

Nhịp: trong sprint sửa tầng 1 thoải mái, tầng 2 khi kẹt, tầng 3 chỉ ghi gap. Cuối đợt đọc gaps, gom cái lặp từ 2 repo trở lên lên kit. Test / debug là nơi phát hiện nhu cầu tool, không phải nơi thiết kế tool.

07Người đứng ở đâu

Người ở chỗ đặt ý định và chỗ phán xét; agent ở chỗ thực thi và thu thập. Bốn cổng người bắt buộc đứng, mọi chỗ khác agent tự chạy:

1 · Cổng ý định

Người viết goal cho flow và chọn tag nào là nghiệm thu. Không có cổng này agent test cái dễ đo thay vì cái quan trọng.

2 · Cổng phán xét

Người đọc report tóm tắt và quyết fail thuộc loại nào: lỗi sản phẩm, lỗi tool, flaky. Chỉ người được kết luận.

3 · Cổng dữ liệu thật và bí mật

Người cấp env / secret, duyệt flow chạy trên workspace có người thật, bảo vệ tài khoản.

4 · Cổng thay đổi kit

Người review theo đợt mọi thay đổi schema, runner lõi, quy ước.

BướcNgườiAgent
Quy ước, schema kitquyết định, reviewđề xuất kèm ví dụ từ gaps
Env, role, secretsđịnh nghĩa, cấpchỉ dùng
Mục tiêu flowviết 1–2 câu goaldịch thành steps, expect, fixture
Viết step, flow, fixturexem lần đầu khi là tiêu chí nghiệm thuviết, chạy thử, sửa
Chạy, thu bằng chứngkhôngchạy, sinh report
Phân loại failphán xétđề xuất kèm bằng chứng
Sửa tool tầng repokhôngsửa tối thiểu, ghi gap
Gom gaps lên kitđọc, chọn, bỏgom, nhóm, nháp
Flow dữ liệu thậtduyệt trước, xem ảnh sauchạy, dọn [E2E]
Deploy, releaseconfirmchuẩn bị, chạy sau confirm
  • Người xem ở mức tóm tắt. Phải mở từng ảnh hoặc đọc log thô là tool chưa đạt. Mục tiêu: vài phút cho một đợt vài chục flow.
  • Sự tham gia giảm dần theo độ chín. Flow mới xem kỹ lần đầu xanh, sau chỉ xem khi fail. Tool mới review lúc lên kit, sau tin doctor.

08Quy trình một tính năng (hoặc một request)

#BướcNgườiAgentĐầu raTool
1Ý địnhgoal, vai trò, cái không được xảy ra, tiêu chíhỏi lại chỗ mơ hồ, nháp danh sách flow nghiệm thurequest có goal + danh sách flowrt req new
2Hợp đồngduyệt specOpenAPI, sinh type, mockspec + typemgctl contract
3Flow trước codexem flow lần đầuviết flow từ goal, phải đỏ đúng chỗflow + fixture + datasetflow init, testenv
4Làmkhông, trừ khi blockcode theo spec, chạy test + flow, commit tách tool / sản phẩmcommit Refs, pushprocess-requests
5Nghiệm thuđọc report, phán xét fail, duyệt dữ liệu thậtchạy flow theo tag, sinh report, đề xuất phân loạireport.json + ảnh, Telegrammgctl flow run
6Phát hànhconfirmdeploy, smoke sau deploy, release, thông báotag, versions.json, report smokemgctl deploy / release
7Gom (theo đợt)đọc gaps, chọngom gaps, nháp kit, dọn flow trùngkit version mới, bộ hồi quygaps, doctor
  • Bước 3 trước bước 4 là thay đổi lớn nhất: tiêu chí nghiệm thu được máy hoá trước khi code.
  • Bước 2 cho phép song song backend và client trên spec + mock.
  • Người chỉ xuất hiện ở 1, 3 (lần đầu), 5, 6, 7.
  • Ba điểm ép: không có goal và danh sách flow thì không vào bước 4; report là đầu vào duy nhất cho deploy; flow đã dùng nghiệm thu tự thành hồi quy.
  • Sửa lỗi nhỏ: 1 (mô tả + cách tái hiện) → 3 (một flow tái hiện, phải đỏ) → 4 → 5.

09Quy trình cả dự án

“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 (rủi ro lớn nhất khi dùng agent); hồi quy phình không kiểm soát. Giữ vòng lặp nhưng đặt vào 5 pha có điều kiện ra.

0

Nền (1–2 tuần)

kit, testenv, quy ước, testid, pipeline report. Làm thật vì mọi pha sau dựa vào.

Ra khi doctor xanh, một flow mẫu chạy được trên cả 3 nền tảng.

1

Nháp rộng

Khách thấy toàn bộ hình hài càng sớm càng tốt. Nháp có chủ đích: mock data, UI trước, backend giả (như mock/* của mobile). Nháp không gọi API thật, không migration, không flow hoi-quy.

Ra khi khách chốt phạm vi và luồng chính; đầu ra là danh sách flow nghiệm thu theo module.

2

Làm thật theo module

Mỗi module đi qua contract → flow đỏ → code → report xanh. Nháp của module được thay, không fix dần.

Ra khi flow nghiệm thu của module xanh và khách duyệt module đó.

3

Ổn định (2–3 vòng, mỗi vòng ~1 tuần)

Hồi quy → fix → hồi quy trên dữ liệu gần thật. Chỉ sửa, không thêm; yêu cầu mới vào backlog vòng sau.

Ra khi bộ hồi quy xanh N lần liên tiếp và khách ký nghiệm thu theo danh sách flow. Quá 3 vòng thì nguyên nhân thường ở pha 1 chốt chưa đủ.

4

Vận hành

Release, smoke sau deploy, gaps theo đợt. Hồi quy có ngân sách: smoke vài phút mỗi deploy, hoi-quy đầy đủ cuối ngày hoặc trước release, flow flaky gắn cach-ly và vào gaps.

liên tục

  • 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.
  • Pha 0 và 1 khoảng 20% thời gian, pha 2 là phần lớn.

10Nơi bắt đầu khi làm việc với agent

Theo nguyên lý

Bắt đầu bằng định nghĩa “xong là gì”, viết xuống ở một chỗ tồn tại lâu hơn cuộc trò chuyện. 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, phiên sau agent lại đoán.

TầmĐiểm xuất phát của ngườiAgent nhận từ đó
Dự ánluật chơi: bằng chứng nào được chấp nhận, ai kết luận pass / fail, dữ liệu nào không đụng, thay đổi nào cần duyệt (bốn cổng), viết thành một trangđọc mỗi phiên
Một việcba câu: ai làm gì thì thấy gì; cái gì không được xảy ra; bằng chứng nào chứng minh. Chưa trả lời được câu ba thì việc chưa sẵn sàng giaoviết flow, spec, code; dừng khi bằng chứng đạt
Một ngàybằng chứng của hôm qua: đọc, phán xét, rồi mới giao việc mớichạy tiếp, phân loại fail để người phán xét

Một việc nên là một request lưu lại, khoảng 5 dòng: title, goal, roles, không được, nghiệm thu (tên flow + tag). Steps, expect, fixture, spec, code là việc của agent. 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.

Một câu: 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. Thấy mình ở khoảng giữa là tín hiệu tiêu chí chưa rõ hoặc tool chưa đủ tin; việc cần làm là sửa tiêu chí hay tool, không phải tự nhảy vào làm.

Theo thư mục

Mở phiên ở thư mục trung tâm của dự án, đứng ngoài mọi repo (với MiniGate là ~/work), không mở trong một repo.

  • Tiêu chí và phán xét cắt ngang nhiều repo; bắt đầu trong repo là tự giới hạn tầm nhìn theo ranh giới code.
  • Bộ data và bằng chứng (work/<ngày>/<tác vụ>/, .runs) nằm ở đây, không trong repo.
  • Memory của agent gắn với thư mục khởi động; một chỗ cố định thì tích luỹ, đổi thư mục là đổi bộ nhớ.
  • Bản đồ repo đã nạp sẵn, agent tự vào repo khi làm; chiều ngược lại không có.

Chỉ mở trong repo khi việc nằm trọn trong repo đó và cần ngữ cảnh riêng (CLAUDE.md, skill, quy tắc store). Đó là phiên “làm” của agent theo request, không phải phiên người đặt tiêu chí. Hai loại phiên tách nhau.

Thư mục trung tâm cần ba thứ: nơi viết ý định (todo / request), nơi chứa bộ data và kết quả chạy, nơi đọc lại (notes, review). Nên có một CLAUDE.md tại đó nói rõ “đây là bàn làm việc, bắt đầu bằng đọc bằng chứng hôm qua rồi mới nhận việc mới”. Dự án sau giữ nguyên nguyên tắc: một thư mục bàn làm việc ngoài mọi repo, chứa bản đồ repo, bộ data, bằng chứng, ghi chú.

11Việc còn mở để nghĩ tiếp

Mục tiêu đã nêu: tối ưu quy trình làm việc nhóm để chủ dự án không phải tham gia quản lý nhiều. Những quyết định còn chờ:

  1. DSL flow dừng ở lớp nào? Uỷ hẳn lớp tương tác cho Playwright / Maestro, hay phương án giữa (chuẩn hoá schema step, thêm auto-wait)? Bắt đầu từ wsctl e2e.
  2. Flow JSON thuần hay cho phép JS? Đề xuất JSON thuần, logic ở driver.
  3. Kit là repo riêng? Đề xuất có, common là consumer đầu tiên.
  4. Schema report.json là gì, đủ để người đọc vài phút một đợt? Đây là điểm nối cho mọi thứ còn lại, nên làm sớm.
  5. Ai giữ cổng nào khi nhóm lớn hơn một người: cổng ý định và phán xét có thể giao cho PO / QA, cổng dữ liệu thật và kit nên giữ ở người vận hành. → Trả lời ở mục 14 và 15.
  6. Thứ tự chuyển: deskctl → minigate → wsctl e2e (theo độ gần với mgctl flow), hay wsctl e2e trước (theo mức rò rỉ)?
  7. Template request hiện chỉ có title; thêm goal / roles / không được / nghiệm thu và chặn vào bước làm khi thiếu goal hoặc nghiệm thu.
  8. CLAUDE.md tại thư mục trung tâm mô tả vòng ngày (đọc bằng chứng → phán xét → giao việc).
  9. Kiểm kê bước 1: bảng lệnh nào thuộc lõi hay dự án, trùng ở đâu, để quyết phạm vi kit trước khi thiết kế API.

Điều rút ra lớn nhất: phần mang sang dự án mới là quy ước, schema của env / role / flow / step / report, cấu trúc thư mục và bốn cổng người đứng. Phần ở lại là nội dung của các file đó. Ranh giới tái sử dụng đi theo loại đối tượng, không theo repo.

12Đối chiếu với các phương pháp cộng đồng đánh giá cao

Mục tiêu thật của ghi chú này không phải tối ưu hiện trạng mà là tìm một quy trình thực hiện dự án tận dụng tối đa agent. Chưa có quy trình thống nhất, đang tự đúc rút. Đối chiếu với các nguồn được trích dẫn nhiều nhất 2025–2026 cho thấy hướng đi ở các mục trên đã rất gần đồng thuận, ở ba điểm:

  • “Xong là gì” viết ra chỗ bền hơn cuộc trò chuyện chính là tinh thần của spec-driven development: spec phải nằm trong repo, không thì mục nát.
  • Bốn cổng người gần với cách HumanLayer khuyên đội nhóm: review plan, không chỉ review code.
  • CLI cho AI, mỗi lệnh một việc, xuất JSON, exit code rõ khớp với bài “Writing tools for agents” của Anthropic. Đội của họ tốn thời gian tối ưu tool nhiều hơn tối ưu prompt.
Phương phápCốt lõiMượn gì cho MiniGate
Research → Plan → Implement
HumanLayer
Mỗi pha ra một file markdown. Giữ context agent ở 40–60%, ghi tiến độ ra file rồi mở phiên mới khi đầy. Một dòng nghiên cứu sai sinh ra hàng nghìn dòng code sai, một dòng plan sai sinh ra hàng trăm.Thêm pha nghiên cứu trước hợp đồng, đầu ra là research.md. Người đọc research trước khi duyệt hợp đồng.
Explore → Plan → Code → Commit
Anthropic
Plan mode cho việc chạm nhiều file hoặc code lạ. Việc nhỏ rõ ràng thì làm thẳng. Đầu tư vào verification vì đó là thứ agent tự kiểm được.Phân tầng việc theo kích cỡ, không ép mọi việc qua bảy bước.
Spec-driven
Spec Kit · OpenSpec · BMAD
Chuỗi constitution → specify → clarify → plan → tasks → implement. Spec 1–3 trang, bắt buộc có mục ngoài phạm vi và tiêu chí nghiệm thu kiểm thử được. BMAD mô phỏng cả đội agile, nặng và tốn token (một benchmark: 5,5 giờ so với 12 phút của OpenSpec).Mượn cổng và cấu trúc thư mục mỗi tính năng, không ôm nguyên framework.
spec / prompt_plan / todo
Harper Reed
Hone ý tưởng bằng hỏi đáp từng câu một, sinh plan dạng chuỗi prompt, để agent tự tick todo.md. Tick todo là cách giữ trạng thái qua nhiều phiên.tasks.md tick được, phiên mới đọc lại từ file.
Ralph loop
Geoffrey Huntley
Vòng lặp bash chạy agent với context sạch mỗi lượt. Bộ nhớ nằm ở git, progress.txt và prd.json. Sau mỗi lượt agent ghi bài học vào AGENTS.md.Pha ổn định chạy loop tự động với ngân sách lượt chạy. Gaps thành rules.
Context engineering cấp độiCLAUDE.md ngắn, dưới 200 dòng, tách quy tắc theo chủ đề vào thư mục rules. CLAUDE.md chỉ là lời khuyên; thứ bắt buộc phải xảy ra mỗi lần thì làm thành hook.Tách CLAUDE.md thành ba lớp: quy ước, rules, hook.
Writing tools for agents
Anthropic
Tool là hợp đồng giữa hệ xác định và agent bất định. Viết tool, cho agent chạy thử trên bộ việc mẫu, đọc transcript xem agent vấp ở đâu, sửa thông báo lỗi để agent biết bước tiếp theo.Eval cho kit. Trả lời trực tiếp câu “có nên sửa tool khi đang test”.

Khoảng trống lớn nhất của ghi chú này so với cộng đồng: mục 8 đi thẳng từ ý định sang hợp đồng, chưa có pha nghiên cứu tách riêng, và chưa nói gì về quản lý context của agent.

Gợi ý cụ thể

  1. Thêm pha nghiên cứu trước hợp đồng. Agent đọc code, truy vết luồng dữ liệu, ghi research.md. Đây là bước có đòn bẩy cao nhất đang bị bỏ qua.
  2. Phân tầng việc theo kích cỡ. Bug có repro rõ thì làm thẳng. Việc chạm nhiều file thì plan mode cộng test. Tính năng mới thì đủ bộ research, spec, plan, tasks. Chi tiết ở mục 13.
  3. Chuẩn hoá thư mục mỗi tính năng trong repo: research.md, spec.md, plan.md, tasks.md. Request 5 dòng ở mục 10 thành phần đầu của spec.
  4. Tách CLAUDE.md thành ba lớp. Quy ước ngắn trong CLAUDE.md, quy tắc chi tiết trong rules, thứ bắt buộc làm hook. “Report là đầu vào duy nhất cho deploy” nên là hook chặn, không nên là câu dặn.
  5. Mỗi task một phiên sạch. Xong một task thì ghi tiến độ vào tasks.md, commit, phiên mới đọc lại từ file. Giải bài “một ngày đọc bằng chứng hôm qua trước”.
  6. Vòng lặp kiểu Ralph cho pha ổn định. Pha 3 chỉ sửa không thêm, tiêu chí là flow xanh: bài toán lý tưởng để chạy loop qua đêm với ngân sách lượt chạy.
  7. Gaps thành bộ nhớ của agent. Đầu ra của bước gom gaps là cập nhật rules hoặc AGENTS.md, không chỉ là danh sách chờ sửa tool.
  8. Đo tool bằng eval. Bộ việc mẫu cho kit, đọc transcript, sửa thông báo lỗi.

Khung thống nhất tối thiểu

LớpNội dungNgười giữ cổng
NềnCLAUDE.md ngắn, rules, hooks, kit schemathay đổi kit
Tính năngresearch, spec, plan, tasks trong repoduyệt spec và plan
Thực thiphiên sạch mỗi task, flow đỏ rồi xanh, reportphán xét report
Tự độngloop cho hồi quy và việc cơ khíngân sách lượt chạy
Họcgaps thành rules và AGENTS.md theo đợtduyệt đợt

Bước tiếp theo hợp lý: chọn một tính năng thật, chạy đủ khung này một lần, ghi lại chỗ bị cản rồi chỉnh.

13Hồ sơ theo loại task

Câu hỏi: các loại task khác nhau (tạo tính năng, fix bug, tối ưu UI/UX…) có nên là các quy trình khác nhau không? Nên khác, nhưng khác ở cổng và bằng chứng, không khác ở khung. Mỗi loại task một quy trình riêng thì đội không nhớ nổi và agent không có một file quy tắc chung để đọc. Cách hợp lý là một bộ khung với các cổng bật tắt được; mỗi loại task là một hồ sơ chọn cổng nào bật.

Khung chung giữ nguyên bốn thứ: hợp đồng viết ra trước khi làm, bằng chứng do máy sinh ra, người giữ cổng ở đúng chỗ, bài học gom về rules. Thứ thay đổi theo loại task là ba câu hỏi: hợp đồng là gì, bằng chứng là gì, người đứng ở cổng nào.

Phân loại theo hai trục chứ không theo tên task: độ mơ hồ của “đúng là gì” và phạm vi ảnh hưởng. Fix bug có repro rõ: mơ hồ thấp, phạm vi hẹp. Tính năng mới: mơ hồ cao, phạm vi rộng. Tối ưu UI/UX: mơ hồ cao nhưng phạm vi hẹp, nên cần hồ sơ riêng. Tên task chỉ là nhãn tiện gọi.

Bảy loại gặp nhiều nhất

Loại taskHợp đồngBằng chứngCổng ngườiBỏ qua
Tính năng mớiresearch, spec, plan, tasksflow đỏ thành xanh, reportduyệt spec, duyệt plan, nghiệm thukhông bỏ gì
Fix bugmột test hoặc flow tái hiện lỗi, đỏ trướctest xanh, hồi quy xanhxác nhận repro đúng với báo cáospec, plan
Tối ưu UI/UXảnh trước, mô tả cảm nhận muốn đạt, danh sách không được pháảnh sau, visual diff, flow hồi quyphán xét bằng mắt sau mỗi vòngspec chữ, tasks
Refactorcam kết hành vi không đổi, phạm vi filehồi quy xanh, diff không có thay đổi hành vichốt phạm vi trước, review diff sauspec, flow mới
Hiệu năngsố đo baseline và mục tiêubenchmark trước sau cùng điều kiệnduyệt mục tiêu, duyệt kết quả đospec chữ
Nâng cấp dependencychangelog breaking, danh sách điểm chạmbuild xanh, hồi quy xanhduyệt danh sách breakingplan dài
Nghiên cứu, spikecâu hỏi cần trả lời, thời gian giới hạnresearch.md có đề xuấtđọc và quyếtcode merge
  • UI/UX là loại duy nhất mà hợp đồng chữ không đủ. Tiêu chí kiểm thử được gần như không viết nổi cho “nhìn thoáng hơn”. Vòng lặp phải ngắn: agent sửa, chụp ảnh, người nhìn, nói một câu, lặp. Thứ cần chặt là danh sách không được phá và flow hồi quy giữ chức năng nguyên vẹn.
  • Fix bug cấm bắt đầu khi chưa có repro đỏ. Điểm ép tương đương “không có goal thì không code” của tính năng. Agent rất hay sửa triệu chứng nếu không bị buộc tái hiện trước.
  • Refactor và hiệu năng chung một nguyên tắc: hành vi không đổi, bằng chứng là bộ hồi quy hiện có. Hồi quy chưa đủ phủ thì việc đầu tiên là bổ sung flow, chưa được chạm code.
  • 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 hồ sơ tính năng hoặc spike. Cần quy ước cho agent nói rõ “việc này vượt hồ sơ” thay vì cố làm tiếp.

Sự cố và vận hành

Loại taskHợp đồngBằng chứngCổng ngườiLưu ý
Hotfix productionmô tả tác động, phạm vi tối thiểu, kế hoạch rollbacksmoke xanh trên staging, log sau deployduyệt phạm vi, duyệt deploybỏ plan dài, nhưng bắt buộc tạo task nợ để làm fix tử tế sau
Xử lý flaky testlog 10 lần chạy, giả thuyết nguyên nhânchạy lặp 20 lần xanh liên tiếpduyệt giả thuyết trước khi sửacấm sửa bằng sleep hoặc retry mù
Thêm log, monitoringcâu hỏi vận hành cần trả lời, sự kiện cần thấydashboard hoặc log mẫu có dữ liệu thậtduyệt danh sách sự kiệnkhông đổi hành vi nghiệp vụ
Đổi cấu hình, feature flaggiá trị trước sau, môi trường áp dụngdoctor xanh, smoke xanhduyệt giá trị trên productionmơ hồ thấp nhưng phạm vi có thể rất rộng
CI/CD, pipelinebước nào thêm bớt, thời gian chạy mục tiêupipeline xanh trên nhánh thửduyệt thay đổi liên quan secretthử trên nhánh riêng trước

Dữ liệu và hợp đồng giao tiếp

Loại taskHợp đồngBằng chứngCổng ngườiLưu ý
Migration schema, dữ liệuscript lên và xuống, số bản ghi ảnh hưởngchạy trên bản sao dữ liệu thật, đếm trước sau khớpduyệt script, duyệt chạy thậtngười giữ cổng dữ liệu thật, agent không chạm
Đổi API, contractdiff OpenAPI hoặc schema, danh sách client bị ảnh hưởngcontract test xanh ở cả hai phíaduyệt breaking changenon-breaking thì theo hồ sơ tính năng
Tích hợp bên thứ batài liệu API, tài khoản sandbox, trường hợp lỗi cần xử lýflow chạy với sandbox, mock cho hồi quycấp tài khoản, duyệt xử lý lỗitách lớp adapter để mock được

Chất lượng và dọn dẹp

Loại taskHợp đồngBằng chứngCổng ngườiLưu ý
Bổ sung test cho code cũdanh sách hành vi cần phủ, thứ tự ưu tiêncoverage tăng, test đỏ khi cố tình pháduyệt danh sách hành viagent dễ viết test khớp code sai, cần mutation check
Xoá tính năng, code chếtdanh sách điểm xoá, ai còn dùngbuild xanh, hồi quy xanh, grep không còn tham chiếuxác nhận không ai dùnglàm theo đợt, commit riêng từng khối
Bảo mật, vá lỗ hổngmô tả lỗ hổng, cách khai thác, phạm vitest chứng minh không khai thác được nữaduyệt cách vá, xoay secret nếu cầnkhông ghi chi tiết khai thác vào repo công khai
Review PRtiêu chí review, mức rủi rodanh sách phát hiện có dòng và cách tái hiệnngười quyết mergeagent review tách khỏi agent viết code

Sản phẩm và nội dung

Loại taskHợp đồngBằng chứngCổng ngườiLưu ý
Prototype, mock cho kháchphạm vi màn hình, dữ liệu giả, thời gian giới hạnảnh hoặc bản chạy đượckhách và chủ dự án xemghi rõ là nháp, không được khoá thành kiến trúc (pha 1 mục 9)
Nội dung, i18n, copy textbảng chuỗi cần đổi, ngôn ngữ, giọng vănảnh màn hình từng ngôn ngữ, không còn khoá thiếuduyệt câu chữkhông đụng logic
Tài liệu, hướng dẫnđối tượng đọc, câu hỏi tài liệu phải trả lờingười mới làm theo được không cần hỏiđọc thửagent viết từ code, người kiểm đúng ý

Nền và meta

Loại taskHợp đồngBằng chứngCổng ngườiLưu ý
Khởi tạo dự án, module mớikit, quy ước, cấu trúc thư mục, pipeline reportdoctor xanh, flow mẫu chạy đượcduyệt cấu trúctương ứng pha 0 mục 9
Sửa kit, tool cho agentgap đã ghi, lệnh nào đổi, schema đổi gìtest của chính tool xanh, eval agent chạy thửduyệt thay đổi kitgom theo đợt, đúng tinh thần mục 6
Tiếp nhận codebase lạcâu hỏi cần hiểu, module ưu tiênresearch.md có sơ đồ luồng và điểm rủi rođọc và bổ sungkhông sửa code trong lúc này
Nâng cấp framework lớndanh sách breaking, thứ tự chuyển đổi theo modulebuild xanh từng module, hồi quy xanhduyệt thứ tự, duyệt từng mốcchia thành nhiều task nhỏ, mỗi task một hồ sơ

Đừng làm 25 file rules. Hầu hết các dòng trên quy về sáu hồ sơ gốc: tính năng, sửa lỗi, không đổi hành vi, chỉnh bằng mắt, nghiên cứu, vận hành có rollback. Các loại còn lại là biến thể thêm một hai điểm ép: migration là “không đổi hành vi” cộng cổng dữ liệu thật, hotfix là “sửa lỗi” cộng rollback và task nợ.

Ba loại sát MiniGate nhất là sửa kit, flaky test và prototype cho khách, vì cả ba đang là vấn đề mở. Viết hồ sơ cho ba loại này trước, chạy vài tuần rồi mới mở rộng.

Triển khai: mỗi hồ sơ là một file ngắn trong thư mục rules (rules/bugfix.md, rules/ui-tweak.md…). Agent đọc đúng file theo nhãn task. CLAUDE.md giữ gọn, chỉnh từng hồ sơ độc lập khi đúc rút thêm.

14Chia người theo cổng, không theo chức danh hay loại task

Câu hỏi: nên chia người theo vai cũ (PM, dev, QA…), theo ai thực hiện loại task nào, hay cách khác? Chia theo cổng mà họ chịu trách nhiệm.

  • Chia theo vai cũ là chia theo năng lực sản xuất. Khi agent làm phần lớn việc sản xuất, cái khan hiếm là người hiểu đúng là gì, người phán xét bằng chứng, người chịu trách nhiệm khi sai. Giữ vai cũ thì dev thành người ngồi nhìn agent, QA thành người chạy lại thứ agent đã chạy.
  • Chia theo loại task còn tệ hơn, vì loại task là thuộc tính của việc, không phải của người. Người “chuyên fix bug” không có context module nào, trong khi context module mới quyết định chất lượng khi điều khiển agent.

Cách hợp lý hơn là hai trục: trục ngang là cổng, trục dọc là module.

Trục cổng: năm vai

VaiGiữ cổng nàoThay cho vai cũNăng lực cốt lõi
Chủ ý địnhspec, phạm vi, ưu tiên, nghiệm thu nghiệp vụPM, BA, một phần designernói chuyện với khách, viết “xong là gì”
Chủ bằng chứngchuẩn report, flow, testenv, ngân sách flakyQA, testerthiết kế bằng chứng thay vì chạy test
Chủ kitquy ước, schema, rules, tool cho agent, kiến trúctech lead, một phần devhiểu agent vấp ở đâu, sửa tool thay vì sửa prompt
Chủ vận hànhdữ liệu thật, secret, deploy, rollbackdevops, SREnói không đúng lúc
Người lái agentchạy phiên hằng ngày, viết request, giám sát loop, đọc bằng chứng hôm quadevhiểu sâu module mình lái

Bốn vai đầu là vai giữ cổng, số người ít, không phụ thuộc loại task. Vai thứ năm là vai sản xuất mới, đông nhất, phân theo trục dọc.

Trục module

Mỗi người lái agent sở hữu một hoặc vài module và làm đủ mọi loại task trên module đó. Loại task chỉ quyết định hồ sơ nào bật, tức phải ghé cổng nào. Fix bug ở module thanh toán thì người lái thanh toán làm, qua cổng chủ bằng chứng. Tính năng mới cùng module vẫn người đó, qua thêm cổng chủ ý định, và cổng chủ kit nếu động vào schema.

Kết quả là một bảng phân công gọn: hàng là loại task, cột là cổng, ô là ai phải ký. Người lái nhìn hồ sơ là biết gõ cửa ai, không cần họp.

Loại taskChủ ý địnhChủ bằng chứngChủ kitChủ vận hành
Tính năng mớispec, nghiệm thuflow nghiệm thunếu chạm schemakhi release
Fix bug—repro đỏ, hồi quy——
Tối ưu UI/UXphán xét bằng mắtflow hồi quy——
Refactor—hồi quy đủ phủphạm vi, review diff—
Migration dữ liệu—đếm trước sauschemascript, chạy thật
Hotfixtác độngsmoke—deploy, rollback
Sửa kit—evalduyệt đợt—
  • Đội nhỏ thì một người đội nhiều mũ, nhưng phải nói rõ đang đội mũ nào khi đứng ở cổng. Hiện chủ dự án là chủ ý định kiêm chủ kit kiêm chủ vận hành. Ghi ra để khi đội lớn lên tách mũ mà không phải vẽ lại quy trình. Đây là câu trả lời cho câu hỏi mở số 5 ở mục 11.
  • 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. Người viết spec rất dễ nhìn thấy cái mình muốn thấy.
  • QA không biến mất mà đổi chất. Chủ bằng chứng là vai tăng giá trị nhất, vì toàn bộ niềm tin vào agent đứng trên chất lượng của flow và report. Tham gia từ lúc viết spec để tiêu chí nghiệm thu kiểm thử được.
  • Agent cũng có vai, nhưng theo context chứ không theo chức danh. Agent nghiên cứu, agent thực thi, agent review là ba phiên tách biệt để agent review không thiên kiến bởi code nó viết. Không cần mô phỏng cả đội agile kiểu BMAD, vì phần phán xét vẫn là người.
  • Chuyển người từ vai cũ theo thế mạnh sẵn có. Dev giỏi hệ thống sang chủ kit. Dev giỏi nghiệp vụ lái module lớn. QA giỏi thiết kế case sang chủ bằng chứng. Người thích vận hành giữ cổng vận hành.

15Phòng ban theo vai hay theo dự án

Theo dự án cho phần giao hàng, theo vai chỉ cho những thứ phải sống lâu hơn dự án. Mô hình lai, nhưng ranh giới đặt theo câu hỏi “thứ này có cần tồn tại sau khi dự án kết thúc không”, không theo chức danh.

Thời agent làm lệch cán cân so với trước ở ba chỗ:

  • Chi phí bàn giao giữa người thành chi phí lớn nhất. Agent viết code trong vài phút thì một ngày chờ phòng QA hay phòng design xếp lịch là vô lý. Phòng ban theo vai sinh hàng đợi, hàng đợi giết tốc độ của agent. Chủ ý định, chủ bằng chứng, người lái phải ngồi trong dự án.
  • Đòn bẩy lớn nhất nằm ở kit và quy ước. Một cải tiến tool cho agent, schema flow hay rules có lợi cho mọi dự án cùng lúc. Để kit trong từng dự án thì bị chép tay giữa repo, đúng tình trạng ở mục 1. Cần một chủ sở hữu sống lâu hơn bất kỳ dự án nào.
  • Dữ liệu thật và secret cần ít tay chạm. Mỗi dự án tự giữ secret là mỗi dự án một lỗ hổng.
Thứ gìĐặt ở đâuVì sao
Chủ ý định, chủ bằng chứng, người lái agenttrong dự áncần context dự án hằng ngày, quyết trong giờ chứ không trong ngày
Chủ kit, rules, schema, tool cho agent, evalđơn vị nền tảng dùng chungtài sản tái dùng, cần version và kỷ luật thay đổi theo đợt
Chủ vận hành, secret, deploy, bảo mậtđơn vị dùng chunggiảm số người chạm production, chuẩn hoá rollback
Cộng đồng theo vai (nhóm chủ bằng chứng các dự án…)không phải phòng ban, chỉ lịch gặp định kỳchia sẻ mẫu flow, chuẩn report; không có quyền điều phối người

Gần với kiểu squad cộng chapter, nhưng đơn vị nền tảng ở đây có sản phẩm thật là kit, khách hàng thật là các dự án, thước đo thật là số gap đóng được mỗi đợt.

Đơn vị kit rất dễ thành tháp ngà. Chống bằng ba quy ước: kit có version để dự án pin; dự án đề xuất thay đổi qua gap; chủ kit dành một phần thời gian ngồi trong dự án tự lái agent. Người không lái agent thì không được quyết tool cho agent.

Chưa đủ hai dự án dùng chung thì chưa lập đơn vị kit. Kit nằm trong dự án đầu tiên nhưng ở repo riêng (mục 5). Lập đơn vị khi dự án thứ hai bắt đầu kéo kit về, không sớm hơn.

Dự án kết thúc thì người đi đâu. Hồ sơ năng lực mỗi người ghi theo vai cổng và module đã lái, sang dự án mới nhận vai tương đương ngay. Cộng đồng theo vai giúp việc này vì người ta đã quen nhau trước khi chuyển.

Dự án nhỏ gộp vai, nhưng không gộp cổng kit và cổng vận hành vào dự án. Được gộp chủ ý định với chủ bằng chứng, hoặc người lái kiêm chủ ý định. Vẫn lấy kit từ đơn vị chung và deploy qua cổng vận hành chung.

Tỷ lệ nhân sự tham khảo: một dự án vừa cần khoảng một chủ ý định, một chủ bằng chứng, hai đến năm người lái. Đơn vị kit một đến ba người phục vụ nhiều dự án, vì việc của họ là sửa tool theo đợt, không trả lời yêu cầu hằng ngày.

16Sơ đồ tổ chức và luồng gap

Hai đơn vị dùng chung ở trên, các dự án ở dưới. Kit đi xuống theo version, gap đi lên theo đợt, report đi sang cổng vận hành để deploy. Đường đứt nét ngang là cộng đồng theo vai, không có quyền điều phối.

Sơ đồ tổ chức: đơn vị nền tảng và vận hành dùng chung ở trên, các dự án ở dưới, kit đi xuống, gap đi lên, report đi sang vận hành Đơn vị nền tảng · chủ kit rules · schema env/role/flow/step/report · tool cho agent · eval sống lâu hơn mọi dự án · 1–3 người · làm việc theo đợt thước đo: số gap đóng mỗi đợt Đơn vị vận hành · chủ vận hành secret · dữ liệu thật · deploy · rollback · bảo mật ít tay chạm production · dùng chung cho mọi dự án đầu vào duy nhất: report xanh Dự án A Chủ ý định spec · phạm vi · nghiệm thu Chủ bằng chứng flow · testenv · report Người lái agent × n · theo module module chat · module thanh toán · module admin… mọi loại task trên module mình · hồ sơ quyết định ghé cổng nào agent: nghiên cứu / thực thi / review là ba phiên tách bằng chứng: .runs · report.json · research / spec / plan / tasks trong repo kit pin v1.4 Dự án B (nhỏ) Chủ ý định kiêm chủ bằng chứng đội nhỏ gộp vai, nhưng nói rõ đang đội mũ nào Người lái agent × 2 không tự mọc kit riêng · không tự giữ secret lấy kit từ đơn vị chung, deploy qua cổng vận hành chung bằng chứng: .runs · report.json kit pin v1.3 kit vN, dự án pin version gap gap theo đợt gap theo đợt report xanh → deploy report xanh ← smoke, rollback cộng đồng theo vai (chủ bằng chứng các dự án, người lái các dự án): lịch gặp định kỳ, chia sẻ mẫu flow và chuẩn report, không điều phối người
Mũi tên liền: kit đi xuống và report đi sang cổng vận hành. Mũi tên đứt nét: gap từ dự án về đơn vị kit, gom theo đợt. Đường đứt nét ngang dưới cùng: cộng đồng theo vai.

Đọc sơ đồ theo một vòng: dự án lấy kit theo version → người lái làm task theo hồ sơ → bằng chứng sinh ra → chủ bằng chứng và chủ ý định phán xét → report xanh đi sang cổng vận hành để deploy → chỗ nào kit cản thì ghi gap → đơn vị kit gom gap theo đợt, ra version mới → dự án pin version mới khi sẵn sàng.