phương pháp làm việc với agent · bản 2026-11-07
Làm việc với agent: phương pháp dùng chung
Ba ghi chú trả lời ba câu: người đứng ở đâu khi agent làm phần lớn việc, công cụ và thư mục tổ chức ra sao, thông tin nào lưu ở đâu. Phần nguyên lý dùng được cho mọi dự án; phần MiniGate chỉ là ví dụ, đóng khung riêng.
00Đọc theo thứ tự
| Ghi chú | Trả lời câu gì | Đọc khi |
|---|---|---|
| 1. Quy trình | Người đứng ở cổng nào, agent làm gì ở giữa; quy trình một việc, một dự án; hồ sơ theo loại task; chia vai trong đội. | bắt đầu dùng agent trong một đội |
| 2. Kit và cây thư mục | Kit gồm gì, cái gì không nên tự viết; cây thư mục của kit, của hub sản phẩm, của máy (7 tầng); luật nạp vào agent thế nào. | dựng dự án mới hoặc chuyển dự án cũ |
| 3. Thông tin lưu ở đâu | Mỗi mẩu thông tin thuộc phạm vi nào, lên git không, mất máy dựng lại từ đâu. | vận hành máy, thêm thông tin mới |
01Mười nguyên tắc xuyên suốt
- Người đặt tiêu chí và phán xét, agent thực thi. Người bắt buộc đứng ở bốn cổng: ý định, phán xét, dữ liệu thật và secret, thay đổi kit. Khoảng giữa là của agent.
- “Xong là gì” viết ở chỗ bền hơn cuộc chat. Một việc là một request năm dòng: title, goal, roles, không được, nghiệm thu. Thiếu goal hoặc nghiệm thu thì chưa được làm.
- Bằng chứng do máy sinh ra. Report đúng schema là đầu vào duy nhất cho deploy; người đọc tóm tắt, không đọc log thô.
- Một khung, nhiều hồ sơ. Loại task khác nhau ở cổng và bằng chứng, không khác ở khung. 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.
- Kit là chữ cộng một lớp nghiệp vụ mỏng. Engine tương tác (click, chờ, chụp) mượn của Playwright, Maestro. Tool riêng của dự án là giá trị; kit làm cho nó rẻ để xây.
- Thành phần vào kit khi gap lặp hai đến ba lần, không có tool chuẩn phủ được, và thuộc lớp nghiệp vụ. Kit có version, dự án pin.
- Bảy tầng thư mục, mỗi tầng một quy tắc truy cập. 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.
- Luật có ba nguồn, nạp qua một chỗ. Kit nói luật chung, hub nói luật sản phẩm, repo nói đặc thù kỹ thuật; import ở file cấp user để tới mọi phiên.
- Một nguồn, chỗ khác chỉ trỏ. Sinh lại được thì commit nguồn sinh, không commit bản sinh. Trùng có chủ đích phải có lệnh kiểm lệch.
- Hỏi “mất máy thì cái gì không lấy lại được” trước khi hỏi “file này để đâu”. Dữ liệu chạy và khởi động khi boot quan trọng hơn mọi file cấu hình.
02Thuật ngữ dùng thống nhất
| Từ | Nghĩa | Ở đâu |
|---|---|---|
| kit | bộ dùng chung của công ty: luật, hồ sơ, mẫu, schema, hook, lệnh kiểm. Có version. | kit/agent-kit/ |
| hub | repo trung tâm của một sản phẩm: CLI dự án, luật sản phẩm, vai, env, flow nghiệm thu, tài liệu vận hành, hồ sơ máy, quyết định. | product/<sp>-hub/ |
| repo nền tảng | repo code của một nền tảng (web, api, desktop, mobile…). Chỉ giữ code, test, đặc thù kỹ thuật. | platform/<sp>-<nền-tảng>/ |
| thư mục cha | 7 tầng trên một máy: kit product platform runtime vault tools work. | ~/, bản đồ ở map.md |
| bàn làm việc | nơi agent ghi tự do: request nháp, bằng chứng, review, ghi chú, nháp cho khách. | work/ |
| request | một việc giao cho agent, năm dòng, có id và trạng thái. | công cụ request của công ty |
| hồ sơ | cách chọn cổng và bằng chứng cho một loại task (feature, bugfix, no-behavior-change, visual-tweak, research, ops-rollback). | kit doc/rule/ |
| cổng | chỗ người bắt buộc đứng: ý định, phán xét, dữ liệu thật và secret, thay đổi kit. | kit doc/policy.md, hub doc/gate.md |
| vai (người) | chủ ý định, chủ bằng chứng, chủ kit, chủ vận hành, người lái agent. | kit doc/role.md |
| vai (test) | tài khoản theo vai nghiệp vụ (admin, nhân viên…) mà flow dùng; secret chỉ là ref. | hub testenv/role.json |
| env, profile, fixture | môi trường chạy (mock, test, thật); hồ sơ máy chạy (trình duyệt, emulator); dữ liệu mẫu bất biến. | hub testenv/env/, profile/, fixture/ |
| flow, step, testid | kịch bản nghiệp vụ theo vai; thao tác UI đặt tên, nơi duy nhất biết testid; định danh phần tử module.screen.element. | hub flow/, step/, repo nền tảng xuất testid |
| bằng chứng, report | ảnh, log, report.json đúng schema của một lần chạy. | work/run/<ngày>/<tác-vụ>/ |
| gap | chỗ tool hoặc kit cản việc, ghi ngay tại chỗ, gom về kit theo đợt. | hub gap/ |
| luật sản phẩm, rule-block | một trang luật của sản phẩm (viết tắt, cảnh báo, quy tắc deploy, rà soát rủi ro); bản tóm tắt chép vào CLAUDE.md của repo nền tảng cho máy dev. | hub doc/rule.md |
| hồ sơ máy, quyết định | thứ riêng một máy không sinh lại được, kèm bootstrap.md; quyết định đã chốt, một file một chủ đề. | hub ops/<máy>/, doc/decision/ |
Tên thư mục kit mặc định số ít, tiếng Anh. Dự án có sẵn tên khác (docs/ flows/) giữ nguyên và khai bảng tên trong kit.lock; trong các ghi chú này dùng tên số ít.
03Áp cho một dự án mới
- Dựng khung bằng lệnh init của kit: 7 tầng, hub, bàn làm việc,
kit.lock, mẫu CLAUDE.md,map.md. - Điền phần chỉ dự án biết: luật sản phẩm (
doc/rule.md), vai thật và env (secret chỉ là ref), ai giữ cổng nào (doc/gate.md), số đo tuần 0 (doc/baseline.md). - Viết CLI của dự án theo hợp đồng CLI của kit: một lệnh một việc,
--json, exit code có nghĩa, không hỏi khi không có TTY, không hardcode đường dẫn. - Giao request đầu tiên theo mẫu năm dòng; để hook chặn request thiếu goal hoặc nghiệm thu.
- Mỗi máy một hồ sơ
ops/<máy>/cóbootstrap.md; có lệnh export và check để máy khớp hồ sơ. - Theo đợt: đọc gap, gom cái lặp lên kit, ra version mới, dự án pin khi sẵn sàng.
04Nguồn chuẩn
Các ghi chú này là phần giải thích. Văn bản có hiệu lực, có version, nằm ở:
- Kit:
doc/policy.md(luật một trang),doc/role.md(vai và cổng),doc/rule/(sáu hồ sơ),doc/convention/(cli-contract, naming, testid, evidence, information-placement),doc/template/,schema/,hook/. - Hub của từng sản phẩm:
doc/rule.md,doc/repos.md,doc/gate.md,doc/decision/,ops/<máy>/.
Trạng thái việc đang làm không ghi ở đây; xem quyết định trong hub và backlog ở bàn làm việc của máy.