docs(agent): bổ sung role fix-dispatcher và siết lại bộ tài liệu agent
- Thêm agent/roles/0_fix_dispatcher.md: phân tier/lane cho từng defect trước khi các agent khác chạy, kèm agent/commands/fix.md và hợp đồng đầu ra agent/output/dispatch_plan.md. - Cập nhật system/guardrail, response_policy, security và các checklist ui/ux/pr_readiness cho khớp luồng mới. - Mở rộng knowledge: i18n_rules, screen_map, theme_tokens, secrets_and_config; cập nhật workflow intake_to_fix và handoff_contract. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
+62
-8
@@ -21,6 +21,7 @@ Anti-pattern mà bộ này cố tình tránh (mục 10 của tài liệu trainin
|
||||
| Không có Output Contract | Mọi output đi qua template trong `output/` |
|
||||
| Không có Quality Gate | Mỗi role có Quality Gate riêng + `checklist/` dùng chung |
|
||||
| Không có example | `examples/good_fix.md` và `examples/bad_fix.md` |
|
||||
| Effort cố định bất kể lỗi to nhỏ | `roles/0_fix_dispatcher.md` chấm tier trước, lỗi 4px chạy 0 agent |
|
||||
|
||||
Sáu role **không** bị tách thành 7 file nhỏ mỗi role (role/task/process/...). Lý do:
|
||||
phần bị lặp giữa các role chính là guardrail, knowledge và checklist — chúng đã được
|
||||
@@ -47,7 +48,8 @@ agent/
|
||||
│ ├─ qt_pitfalls.md ← 20 nguyên nhân gốc hay gặp của bug UI PySide6
|
||||
│ ├─ secrets_and_config.md ← SecretStore, schema migration, bẫy .get() trên config merge
|
||||
│ └─ quality_gates.md ← CASAN gate, lệnh chạy, test headless
|
||||
├─ roles/ ← 7 agent chuyên biệt
|
||||
├─ roles/ ← 1 hub + 7 agent chuyên biệt
|
||||
│ ├─ 0_fix_dispatcher.md ← HUB: chấm tier T0/T1/T2/T3, chọn lane, tách defect
|
||||
│ ├─ 1_ui_bug_triage.md
|
||||
│ ├─ 2_ui_visual_fixer.md
|
||||
│ ├─ 3_ux_flow_fixer.md
|
||||
@@ -55,14 +57,17 @@ agent/
|
||||
│ ├─ 5_fix_implementer.md
|
||||
│ ├─ 6_regression_reviewer.md
|
||||
│ └─ 7_security_defect_fixer.md
|
||||
├─ commands/
|
||||
│ └─ fix.md ← nguồn của slash command /fix (điểm vào của hub)
|
||||
├─ workflow/
|
||||
│ ├─ intake_to_fix.md ← pipeline end-to-end, ai làm gì ở bước nào
|
||||
│ ├─ intake_to_fix.md ← pipeline end-to-end, 4 lane theo tier
|
||||
│ └─ handoff_contract.md ← envelope truyền giữa các agent
|
||||
├─ checklist/
|
||||
│ ├─ ui_review.md
|
||||
│ ├─ ux_review.md
|
||||
│ └─ pr_readiness.md
|
||||
├─ output/
|
||||
│ ├─ dispatch_plan.md ← template điều phối (output của Hub)
|
||||
│ ├─ defect_record.md ← template hồ sơ lỗi (output của Triage)
|
||||
│ ├─ fix_plan.md ← template phương án sửa (output của Fixer)
|
||||
│ ├─ fix_report.md ← template báo cáo sau khi sửa (output của Implementer)
|
||||
@@ -74,10 +79,11 @@ agent/
|
||||
|
||||
---
|
||||
|
||||
## 3. Bảy agent và khi nào dùng
|
||||
## 3. Một hub + bảy agent, và khi nào dùng
|
||||
|
||||
| # | Agent | Pattern | Nhận vào | Trả ra |
|
||||
|---|---|---|---|---|
|
||||
| **0** | **Fix Dispatcher** (hub) | Router | Phản ánh thô của người dùng | `dispatch_plan.md` — tier + lane + tách defect |
|
||||
| 1 | **UI Bug Triage** | Reviewer | Lời kể lộn xộn của user, ảnh chụp màn hình, log | `defect_record.md` + phân loại + route |
|
||||
| 2 | **UI Visual Fixer** | Generator | defect_record (loại `visual`) | `fix_plan.md` — layout/QSS/theme/icon/DPI |
|
||||
| 3 | **UX Flow Fixer** | Generator | defect_record (loại `flow`) | `fix_plan.md` — luồng, trạng thái, phản hồi |
|
||||
@@ -86,19 +92,36 @@ agent/
|
||||
| 6 | **Regression Reviewer** | Reviewer | Patch + fix_report | Verdict PASS/FAIL + `pr_body.md` |
|
||||
| 7 | **Security Defect Fixer** | Generator | defect_record (loại `security`) | `fix_plan.md` — credential, secret, migration |
|
||||
|
||||
Đây là **Multi-Agent Pattern**: `Triage (Planner) → Specialist → Implementer (Executor)
|
||||
→ Reviewer`. Không bỏ bước. Đặc biệt không bỏ bước 1: 80% bug UI báo lên là mô tả
|
||||
triệu chứng, không phải nguyên nhân.
|
||||
Đây là **Multi-Agent Pattern**: `Dispatcher (Router) → Triage (Planner) → Specialist →
|
||||
Implementer (Executor) → Reviewer`.
|
||||
|
||||
**Số bước thực chạy do agent 0 quyết định, không phải mặc định 5.** Bộ v1.2 chạy đủ pipeline
|
||||
cho mọi lỗi, kể cả đổi một giá trị 4px — đó là lý do agent 0 ra đời. Bốn lane:
|
||||
|
||||
| Tier | Lỗi kiểu gì | Lane | Gọi agent |
|
||||
|---|---|---|---|
|
||||
| **T0** | Đổi số đo hiển thị, sai chính tả chuỗi có key sẵn, đổi token màu có sẵn | DIRECT | **0 lần** — hub sửa luôn + 4 cổng máy |
|
||||
| **T1** | Nguyên nhân gốc đã rõ kèm `file:line`, 1 màn, ≤ 3 file, ≤ 40 LOC | SOLO | 1 lần |
|
||||
| **T2** | Nguyên nhân chưa rõ nhưng đã khoanh 1 màn; chạm QSS/token/i18n dùng chung | PAIR | 3 lần |
|
||||
| **T3** | Mô tả thuần triệu chứng, không tái hiện được, nhiều category, > 150 LOC | FULL | 4–5 lần |
|
||||
|
||||
Bước 1 vẫn **không** được bỏ ở T3 — 80% bug UI báo lên là mô tả triệu chứng, không phải
|
||||
nguyên nhân. Ở T1/T2, phần triage do hub tự làm trong `dispatch_plan`, và chỉ hợp lệ khi
|
||||
phản ánh đã tự chỉ ra màn hình + triệu chứng cụ thể. Bước 6 chỉ được bỏ ở T0/T1, và phải
|
||||
nêu rõ cổng nào thay thế.
|
||||
|
||||
Agent 7 là specialist thứ tư, ngang hàng 2/3/4 trong pipeline, nhưng khác ở hai điểm: nó
|
||||
được phép chạm `config.py`, `infrastructure/`, `core/` (ba role kia bị chặn ở tầng
|
||||
presentation), và nó **không được tự quyết chính sách bảo mật** — bốn câu hỏi bắt buộc trả
|
||||
về cho Cowork Team.
|
||||
|
||||
### Routing rule (Triage quyết định)
|
||||
### Routing rule (Hub chấm tier → Triage chọn specialist)
|
||||
|
||||
```text
|
||||
Người dùng báo lỗi
|
||||
│
|
||||
├─ agent 0 tách thành N defect_id, chấm tier từng cái
|
||||
│ (≤ 5 lệnh đọc/grep, 0 subagent; hết mà chưa chấm được → T2)
|
||||
│
|
||||
├─ "nhìn sai / lệch / mất chữ / màu lạ / bị che" → 2. UI Visual Fixer
|
||||
├─ "bấm không ăn / không biết đang chạy / mất dữ liệu" → 3. UX Flow Fixer
|
||||
@@ -108,12 +131,36 @@ Người dùng báo lỗi
|
||||
Trả về, mở issue type:bug thường.
|
||||
|
||||
Nhóm `security` THẮNG mọi nhóm khác: lỗi vừa lệch layout vừa lộ credential thì đi 7 trước.
|
||||
Tín hiệu bảo mật cũng ép tier lên **T3-SEC** bất kể diff nhỏ cỡ nào — một dòng `==` so
|
||||
mật khẩu không bao giờ là T0.
|
||||
```
|
||||
|
||||
Tier chỉ đi **lên**. FAIL ở bước 6 → tier +1 rồi chạy lại, không sửa lại ở nguyên tier cũ.
|
||||
|
||||
---
|
||||
|
||||
## 4. Cách dùng
|
||||
|
||||
### 4.0 Điểm vào (khuyến nghị)
|
||||
|
||||
Cài một lần cho mỗi máy — `.claude/` nằm trong `.gitignore`, nên nó **không** theo
|
||||
clone; `agent/` mới là bản gốc được version:
|
||||
|
||||
```bash
|
||||
mkdir -p .claude/agents .claude/commands
|
||||
cp agent/roles/[1-7]_*.md .claude/agents/
|
||||
cp agent/commands/fix.md .claude/commands/
|
||||
```
|
||||
|
||||
Rồi:
|
||||
|
||||
```text
|
||||
/fix màn Folder kéo to ra thì mất cây thư mục bên trái
|
||||
```
|
||||
|
||||
Hub sẽ chấm tier, in `dispatch_plan`, rồi tự chạy đúng lane. Chỉ gọi trực tiếp role 1–7
|
||||
khi đã biết chắc tier.
|
||||
|
||||
### 4.1 Dùng thủ công (mọi trợ lý AI)
|
||||
|
||||
Nạp theo đúng thứ tự này rồi dán bug report của user vào:
|
||||
@@ -122,6 +169,7 @@ Nạp theo đúng thứ tự này rồi dán bug report của user vào:
|
||||
agent/system/guardrail.md
|
||||
agent/system/security.md
|
||||
agent/system/response_policy.md
|
||||
agent/roles/0_fix_dispatcher.md ← luôn nạp trước, để biết cần chạy tới đâu
|
||||
agent/roles/<role đang dùng>.md
|
||||
+ các file knowledge/ mà role đó liệt kê ở mục "KNOWLEDGE"
|
||||
```
|
||||
@@ -133,9 +181,13 @@ subagent, copy sang `.claude/agents/`:
|
||||
|
||||
```bash
|
||||
mkdir -p .claude/agents
|
||||
cp agent/roles/*.md .claude/agents/
|
||||
cp agent/roles/[1-7]_*.md .claude/agents/
|
||||
```
|
||||
|
||||
`0_fix_dispatcher.md` **không** copy vào `.claude/agents/`: hub cần quyền gọi agent khác,
|
||||
mà subagent trong Claude Code không gọi được subagent. Hub chạy ở session chính, qua
|
||||
`/fix` (`.claude/commands/fix.md`).
|
||||
|
||||
Sau đó gọi bằng tên: `ui-bug-triage`, `ui-visual-fixer`, `ux-flow-fixer`,
|
||||
`i18n-a11y-fixer`, `fix-implementer`, `regression-reviewer`, `security-defect-fixer`.
|
||||
|
||||
@@ -154,4 +206,6 @@ trong commit message — instruction cũng là code.
|
||||
|---|---|---|
|
||||
| 1.0 | 2026-09-07 | Bản đầu: 6 role, 6 knowledge module, 4 output contract |
|
||||
| 1.1 | 2026-09-07 | Thêm role 7 `security-defect-fixer` + `knowledge/secrets_and_config.md`. Lý do: bộ v1.0 chỉ phủ UI/UX, nên credential hardcode phát hiện qua màn Settings bị rơi vào `not-ui` và không ai nhận |
|
||||
| 1.4 | 2026-09-08 | Nạp bài học từ lượt audit i18n toàn app. `knowledge/i18n_rules.md` §2.0 (`bind_*` là cách mặc định cho chuỗi tĩnh, `bind_dynamic` cho chữ theo trạng thái, không bind dữ liệu), §"Cách TÌM ra hết các chỗ bị lỗi" (grep chuỗi tiếng Việt ra 962 dòng mà **không** dòng nào là lỗi thật; phép đo đúng là thay `tr()` bằng chuỗi mốc trên `MainWindow` thật), và 3 mục checklist mới. Lý do: bộ v1.3 không có cách nào phát hiện lỗi "chữ không được áp lại" — nó không để lại dấu vết nào trong source |
|
||||
| 1.3 | 2026-09-08 | Thêm hub `0_fix_dispatcher` + `output/dispatch_plan.md` + `/fix`. Lý do: bộ v1.2 không có tầng điều phối, nên **mọi** lỗi đều kéo cả pipeline 4–5 agent — kể cả nới một `setMinimumWidth` lên 232px. Bổ sung 4 lane theo tier, danh sách đóng T0 (6 loại + 9 disqualifier), 4 cổng máy thay reviewer ở T0, luật escalate một chiều, và luật tách một phản ánh thành nhiều `defect_id` chấm tier riêng |
|
||||
| 1.2 | 2026-09-07 | Nạp bài học từ lần chạy thật đầu tiên (`SEC-20260907-01`). Bản vá của bước 5 mang một blocker mà **không mục nào trong bộ v1.1 bắt được** — reviewer tìm ra bằng tay. Bổ sung: `secrets_and_config.md` §9 (chặn rỗng, `compare_digest` + ASCII, và luật "API an toàn hơn thường có miền đầu vào hẹp hơn"); `6_regression_reviewer.md` Bước 2.1 (ràng buộc miền đầu vào) và 4.1 (test rỗng ruột); `5_fix_implementer.md` + `quality_gates.md` (baseline bằng `comm -13` trên tên test, guard `git add`, và thực tế suite vốn đã đỏ 11+66); `bad_fix.md` ca 11-12 — hai ví dụ **có thật** đầu tiên trong file |
|
||||
|
||||
Reference in New Issue
Block a user