Kit cho agent: ba lớp, và cây thư mục từ kit tới máy

00Câu hỏi

• Xây kit có thực sự quan trọng không, hay chỉ là chi phí? Với một dự án thì sao, với nhiều đội thì sao?
• Tool là giá trị riêng của dự án, vậy kit thay thế hay bổ sung?
• Cây thư mục của kit, của sản phẩm, của máy trông thế nào?
• Sản phẩm nhiều nền tảng, nhiều phân hệ thì tổ chức ra sao?

01Ba lớp của kit

Chỗ nguy hiểm là lớp thứ ba. Engine rất dễ nuốt thời gian mà không tăng giá trị tái dùng. Đây là bẫy “xây nền tảng trước sản phẩm”: người giỏi nhất đi làm kit, dự án thật không ai lái agent, kit làm xong không ai biết thiếu gì.

Quy tắc nhanh để xếp bất kỳ lệnh nào: lệnh biết về vai, tài khoản, dữ liệu hay bằng chứng thuộc lớp nghiệp vụ. Lệnh biết về selector, pixel, thời gian chờ thuộc lớp engine. Thứ là schema, help hay tài liệu thuộc lớp chữ. Tái cấu trúc thì tách theo lớp, không tách theo CLI.

02Tool riêng là giá trị của dự án

Agent không biết sản phẩm là gì; thứ duy nhất dạy nó là tool: lệnh đăng nhập như app thật, vai và tài khoản, cách dọn dữ liệu test, lệnh điều khiển thiết bị, testid từng màn hình, flow nghiệm thu. Đó là tri thức sản phẩm đã mã hoá thành lệnh, nằm trong dự án, sống chết cùng dự án.

Vai trò của kit không phải thay tool dự án mà làm cho tool dự án rẻ để xây. Khi kit và engine lo hai nhóm sau, đội dự án dành toàn bộ công cho nhóm một. Thước đo của một đội là số lệnh đặc thù mà agent dùng được, không phải số dòng runner. Tool riêng không chết hẳn cùng dự án: khuôn của nó (cách đặt tên, xuất JSON, gắn vai) thành mẫu trong kit; nội dung ở lại, khuôn mang đi.

03Kit theo quy mô

Một dự án: kit như sản phẩm có repo riêng và người chuyên trách chỉ có nghĩa khi có từ hai dự án dùng chung. Trước đó làm lớp chữ cộng vài lệnh đơn; testenv và report giữ trong dự án đầu tiên nhưng ở repo riêng để sau kéo ra được.

Nhiều đội, nhiều sản phẩm: kit là thứ duy nhất tạo lợi thế theo quy mô. Mỗi đội tự học một bài học thì công ty trả giá bằng số đội. Một cải tiến trong kit nhân lên theo số đội. Lãnh đạo không so sánh được nếu mỗi đội báo cáo bằng một loại bằng chứng: schema report chung là điều kiện để quản lý được. Lớp chữ thành chuẩn bắt buộc với mọi đội; lớp nghiệp vụ dùng chung schema và lệnh đơn, adapter có biến thể theo stack; lớp engine chọn một engine chuẩn cho web, một cho mobile, một runner API.

Thứ quan trọng hơn kit trong ba tháng đầu: quản trị dùng tự phát (ai trả tiền tool nào, dữ liệu khách có vào model nào, secret có trong lịch sử chat không), luật một trang, và baseline (thời gian request đến merge, số lần làm lại, lỗi lọt sang khách).

04Cây repo kit

Tên thư mục tiếng Anh, một từ, số ít. Có version, CHANGELOG, dự án pin bằng kit.lock.

agent-kit/
├── README.md                 # ba lớp, 7 tầng, cách pin, cách gửi gap
├── VERSION  CHANGELOG.md
├── doc/                      # LỚP CHỮ, bắt buộc với mọi đội
│   ├── policy.md             # luật một trang
│   ├── role.md               # năm vai, bốn cổng
│   ├── rule/                 # sáu hồ sơ: feature, bugfix, no-behavior-change, visual-tweak, research, ops-rollback
│   ├── convention/           # cli-contract, naming, testid, evidence, information-placement
│   ├── template/             # request, research, spec, plan, task, gap, decision, gate, baseline, map,
│   │   ├── claude/           #   CLAUDE.md: user (cấp user), work (thư mục cha), hub, platform, rule-block
│   │   ├── hub/              #   rule.md, role.json, env.mock.json, smoke.json, bootstrap.md, gitignore
│   │   └── tier/             #   README platform/, runtime/
│   └── method/               # bộ ghi chú này
├── schema/                   # env, role, flow, step, report, request, gap
├── hook/                     # request-check, report-gate, secret-scan: thứ bắt buộc, không phải lời dặn
├── core/                     # LỚP NGHIỆP VỤ MỎNG: chỉ mọc từ gap
├── adapter/                  # LỚP ENGINE: vỏ mỏng gọi Playwright / Maestro / HTTP
├── eval/                     # bộ việc mẫu, rubric: đo kit bằng chính agent
├── bin/                      # kit-init, kit-doctor
└── test/

• Không nằm trong kit: engine, secret, dữ liệu thật, lệnh nghiệp vụ của sản phẩm.
• Bắt buộc chỉ doc/ schema/ hook/. core/ và adapter/ đo bằng số đội tự nguyện dùng.
• Dòng chảy: sản phẩm ghi gap, kit gom theo đợt, ra version mới, sản phẩm đổi kit.lock khi sẵn sàng.

05Cây hub sản phẩm

Mỗi sản phẩm một hub chứa mọi thứ cắt ngang nền tảng; repo nền tảng chỉ giữ code và đặc thù kỹ thuật. Lệnh init của kit tạo khung này.

product/<sp>-hub/
├── CLAUDE.md                 # ngắn: hub chứa gì, luật ở doc/rule.md, kit ở kit.lock
├── kit.lock                  # agent-kit <version>; dự án cũ khai bảng tên: layout doc=docs flow=flows …
├── cli/                      # LỚP TOOL RIÊNG: lệnh có nghĩa với sản phẩm này, theo cli-contract
│   ├── command/              #   api/ (đăng nhập như app, nghiệp vụ), device/, deploy, status…
│   └── lib/
├── config/                   # tham số mỗi lệnh, có _doc; *.local.json ghi đè riêng máy (không git)
├── testenv/                  # role.json (vai), env/ (mock, test, thật; secret chỉ là ref)
├── flow/                     # acceptance/ smoke/ regression/ ops/
├── step/<nền-tảng>/          # step tái dùng, biết testid
├── profile/  testid/  fixture/
├── feature/<tên>/            # research, spec, plan, task của một tính năng
├── gap/                      # gap chờ gom về kit theo đợt
├── doc/
│   ├── rule.md               # luật sản phẩm một trang: viết tắt, cảnh báo, deploy, rà soát rủi ro
│   ├── repos.md  gate.md  baseline.md
│   ├── decision/YYYY-MM-DD-<chủ-đề>.md
│   └── server/  release/ …   # tài liệu vận hành
├── ops/<máy>/                # hồ sơ máy: bootstrap.md, CLAUDE.md, map.md, manifest tiến trình, route, cron
└── secrets/                  # chỉ khi dự án quyết giữ secret trong repo private; agent không đọc

• Flow nghiệm thu đi theo phân hệ, step và lệnh thiết bị theo nền tảng, vai và env theo sản phẩm, unit test ở repo nền tảng.
• Phân hệ lớn đến mức có đội riêng vẫn là thư mục, không phải hub riêng. Chỉ tách hub khi phân hệ thành sản phẩm độc lập có vai và env riêng.
• Mono-repo hay multi-repo không đổi cây: gom về một repo thì hub là thư mục gốc, nền tảng ở apps/<nền-tảng>/.

06Thư mục cha trên một máy: bảy tầng

Mỗi tầng một quy tắc truy cập rõ. Tách checkout sửa code khỏi bản đang chạy; secret cấm agent; bàn làm việc là nơi duy nhất agent ghi tự do. Lệnh init của kit tạo đủ bảy tầng; map.md ở thư mục cha là bản đồ máy, bản có version nằm ở hub ops/<máy>/.

• Request có id và trạng thái đi qua công cụ request; work/request/ chỉ chứa backlog và nháp.
• Bằng chứng mỗi lần chạy ở work/run/<ngày>/<tác-vụ>/; mỗi phiên ghi tóm tắt work/run/<ngày>/README.md. Sao lưu của agent cũng ở đó, vì agent không ghi được vault/.
• Repo khác tìm nhau bằng URL origin, không theo tên hay vị trí thư mục; đường dẫn ở config và env, không ghi cứng trong code. Đổi chỗ thư mục thì sửa map.md trước, rồi grep đường cũ trong config, env, tiến trình, web server, cron.

07Luật nạp vào agent thế nào

Luật có ba nguồn và được nạp qua ba file. Không chép nội dung giữa các file, chỉ import hoặc trỏ.

08Nhiều nền tảng, nhiều phân hệ

Nghiệm thu là chuyện nghiệp vụ và thường cắt ngang nền tảng (A gửi trên desktop, B nhận trên mobile), còn step mới là thứ biết testid và engine. Vì vậy nền tảng nằm ở khai báo vai, không ở step; kit đọc nền tảng của vai để chọn adapter. Một flow cho ba vai trên ba nền tảng thay cho nhiều file đánh số theo thiết bị:

{
  "flow": "works.giao-lam-duyet",
  "roles": {
    "quan-ly":  { "platform": "desktop" },
    "nhan-vien":{ "platform": "mobile" },
    "duyet":    { "platform": "web" }
  },
  "steps": [
    { "as": "quan-ly",   "use": "desktop/works/giao-viec", "params": { "to": "{{nhan-vien.user}}", "title": "[E2E] viec A" }, "save": "viec" },
    { "as": "nhan-vien", "use": "mobile/works/bao-xong",   "params": { "id": "{{viec.id}}" } },
    { "as": "duyet",     "use": "web/works/duyet",         "params": { "id": "{{viec.id}}" }, "expect": { "status": "da-duyet" } }
  ]
}

Chạy với env “thật” hay “mock” là cùng một flow. Đổi vai sang nền tảng khác thì chỉ đổi đường dẫn use. Bằng chứng xếp theo flow rồi vai và nền tảng.

09Thứ tự làm và thước đo

Bắt đầu từ số không: chữ và schema trước, rồi evidence và testenv trong lớp nghiệp vụ, rồi một adapter, rồi eval. Hook làm ngay khi có schema report. Không hợp nhất runner tự viết; phần engine quyết sau thí điểm, lúc đó danh sách gap cho biết cần uỷ hay cần giữ.

10Ví dụ MiniGate

11Việc còn mở

• Engine chuẩn cho công ty: thử Playwright và Maestro trên một sản phẩm mỗi loại trước khi chốt.
• Thứ tự chuyển runner tự viết: cái rò rỉ nặng nhất trước, hay cái gần lớp điều phối nhất trước?
• Mobile chưa có lớp step: viết step trước khi chuyển flow mobile về hub.
• Ai là đơn vị kit đợt đầu; ngân sách token cho eval và loop.
• CLI vận hành của công ty (ssh, request, đồng bộ repo) thuộc kit hay đơn vị vận hành? Đề xuất: vận hành, nhưng tuân hợp đồng CLI của kit.

Kit là chữ cộng một lớp nghiệp vụ mỏng; engine thì mượn; tool riêng của dự án là thứ kit phải làm cho rẻ, không phải thứ kit thay thế.