3c3ec748f9
- 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>
154 lines
8.9 KiB
Markdown
154 lines
8.9 KiB
Markdown
# Workflow — từ phản ánh của người dùng tới PR
|
||
|
||
## 0. Lane theo tier — đọc trước
|
||
|
||
Pipeline dưới đây là **lane FULL (T3)**, không phải mặc định. `0_fix_dispatcher` chấm tier
|
||
trước và cắt bớt bước:
|
||
|
||
| Tier | Lane | Bước thực chạy | Gọi agent |
|
||
|---|---|---|---|
|
||
| **T0** | DIRECT | hub sửa → 4 cổng máy (`roles/0_fix_dispatcher.md` §4.1) | 0 |
|
||
| **T1** | SOLO | hub triage inline → **5** → hub review bằng `checklist/ui_review.md` | 1 |
|
||
| **T2** | PAIR | hub triage inline → **2/3/4** → **5** → **6** | 3 |
|
||
| **T3** | FULL | **1** → **2/3/4** → **5** → **6** | 4–5 |
|
||
| **T3-SEC** | FULL-SEC | **7** → *(Cowork Team)* → **5** → **6** | 3 + chờ người |
|
||
|
||
Bỏ bước nào cũng phải **nêu rõ trong `dispatch_plan`** cổng nào thay thế. Bước **6** chỉ
|
||
được bỏ ở T0 và T1.
|
||
|
||
## 1. Pipeline (lane FULL)
|
||
|
||
```text
|
||
Người dùng báo lỗi (chat / issue / miệng)
|
||
│
|
||
▼
|
||
┌───────────────────────────┐
|
||
│ 0. fix-dispatcher HUB │ → dispatch_plan.md
|
||
│ Router │ + tách N defect_id + tier + lane
|
||
└───────────┬───────────────┘
|
||
│ T0 → hub tự sửa, KHÔNG đi tiếp
|
||
│ T1 → nhảy thẳng xuống bước 5
|
||
│ T2 → nhảy thẳng xuống bước 2/3/4
|
||
│ T3 → đi tiếp bước 1
|
||
▼
|
||
┌───────────────────────────┐
|
||
│ 1. ui-bug-triage │ → defect_record.md
|
||
│ Planner │ + category + severity + confidence
|
||
└───────────┬───────────────┘
|
||
│ route theo category (security THẮNG mọi nhóm khác)
|
||
┌───────┬─┴──────┬──────────┬───────────┐
|
||
▼ ▼ ▼ ▼ ▼
|
||
┌────────┐┌────────┐┌──────────┐┌─────────┐ not-ui
|
||
│ 2. ││ 3. ││ 4. ││ 7. │ → RETURN_TO_REPORTER
|
||
│ visual ││ flow ││ i18n-a11y││ security│ (mở issue type:bug thường)
|
||
└────┬───┘└───┬────┘└────┬─────┘└────┬────┘
|
||
└────────┼──────────┴───────────┘
|
||
│ ⚠ role 7 có thể dừng ở đây:
|
||
│ 4 câu chính sách chưa có đáp án
|
||
│ → RETURN_TO_REPORTER (needs-security-decision)
|
||
▼ fix_plan.md
|
||
┌───────────────────────────┐
|
||
│ 5. fix-implementer │ → patch + fix_report.md
|
||
│ Executor (SỬA FILE) │ + CASAN gate output
|
||
└───────────┬───────────────┘
|
||
▼
|
||
┌───────────────────────────┐
|
||
│ 6. regression-reviewer │ → verdict + pr_body.md
|
||
│ Reviewer │
|
||
└───────────┬───────────────┘
|
||
FAIL ──┘ (quay lại 5, hoặc về 2/3/4 nếu sai nguyên nhân gốc)
|
||
PASS ──▶ Cowork Team review → merge
|
||
```
|
||
|
||
## 2. Ai được làm gì
|
||
|
||
| Agent | Đọc | Sửa file | Chạy lệnh | Quyết định |
|
||
|---|---|---|---|---|
|
||
| 0. dispatcher | ✅ | ✅ **chỉ ở T0** | ✅ (grep, gate) | tier + lane + tách defect |
|
||
| 1. triage | ✅ | ❌ | ✅ (grep, tra manifest) | phân loại + route |
|
||
| 2/3/4. specialist | ✅ | ❌ | ✅ (đọc, kiểm LOC) | nguyên nhân gốc + phương án |
|
||
| 7. security | ✅ | ❌ | ✅ (đọc, `git log -S`) | lỗ hổng + migration; **không** quyết chính sách |
|
||
| 5. implementer | ✅ | ✅ | ✅ (git, pytest, gate) | cách hiện thực trong phạm vi plan |
|
||
| 6. reviewer | ✅ | ❌ | ✅ (git, pytest, gate) | PASS / FAIL |
|
||
| Cowork Team | — | — | — | **merge** |
|
||
|
||
Chỉ **một** agent được sửa file. Ranh giới này là thứ giữ cho pipeline review được.
|
||
|
||
Ngoại lệ duy nhất là hub ở **T0**, và nó bị bó rất chặt để đổi lại: danh sách đóng 6 loại
|
||
thay đổi, 9 disqualifier, trần ≤ 2 file / ≤ 10 dòng, và 4 cổng máy bắt buộc dán output thật.
|
||
Vượt bất kỳ ràng buộc nào → `git checkout --` rồi chấm lại T2. Hub **không** được sửa file ở
|
||
T1/T2/T3 — ở đó nó chỉ điều phối và (ở T1) review, vì reviewer không được là người viết patch.
|
||
|
||
## 3. Cổng chuyển bước
|
||
|
||
Không bước nào được đi tiếp nếu chưa đạt:
|
||
|
||
| Từ → Đến | Điều kiện |
|
||
|---|---|
|
||
| 0 → bất kỳ | Mỗi defect_id có đúng 1 tier + 1 lane, tier ≠ T0 dẫn được về một dòng cụ thể của Bước 3, đã xét override bảo mật trước |
|
||
| 0 → tự sửa (T0) | Trúng danh sách đóng, 0 disqualifier, Gate S + blast radius đã **đo bằng lệnh** |
|
||
| 1 → 2/3/4 | `confidence >= medium`, có ít nhất một `file:line`, đã redact |
|
||
| 2/3/4 → 5 | Đúng **một** nguyên nhân gốc, có cách kiểm chứng, không vượt 400 LOC (hoặc đã có kế hoạch tách) |
|
||
| 7 → 5 | Như trên, **cộng thêm**: có đường di trú cho cả 4 nhóm người dùng, và 4 câu chính sách đã có đáp án của Cowork Team |
|
||
| 5 → 6 | 5 cổng CASAN xanh, test regression đỏ-trước-xanh-sau |
|
||
| 6 → người | Verdict PASS/PASS_WITH_NOTES + `pr_body` |
|
||
|
||
`confidence: low` ở bất kỳ đâu → quay về bước 1. Không đoán tiếp.
|
||
|
||
## 4. Vòng lặp và giới hạn
|
||
|
||
- FAIL ở bước 6 → về bước 5 (lỗi hiện thực) hoặc về 2/3/4 (sai nguyên nhân gốc).
|
||
- **Tier +1 mỗi lần FAIL.** Chạy lại ở nguyên tier cũ là lỗi điều phối: hai lần thất bại ở
|
||
cùng độ sâu gần như luôn có nghĩa là hồ sơ lỗi sai từ đầu.
|
||
- Tier chỉ đi **lên**. Không có đường hạ tier giữa dòng, kể cả khi diff hoá ra nhỏ.
|
||
- Quá **2 vòng** mà vẫn FAIL → dừng, đưa người thật vào. Vòng thứ ba thường có nghĩa là
|
||
`defect_record` sai từ đầu, không phải bản vá sai.
|
||
|
||
## 5. Đường tắt hợp lệ
|
||
|
||
Đây là các đường tắt hub được phép chọn ở Bước 3. Chúng **thay thế** phần "đường tắt" của
|
||
bộ v1.2 — trước đây tự phát, giờ có tier và có cổng bù.
|
||
|
||
| Tình huống | Tier | Đường tắt |
|
||
|---|---|---|
|
||
| Nới một số đo hiển thị (px, margin, spacing) | T0 | hub sửa, 0 agent |
|
||
| Sai chính tả / sai dấu một chuỗi đã có key | T0 | hub sửa, đủ 3 ngôn ngữ, **vẫn phải có test** |
|
||
| Đổi token màu có sẵn sang token có sẵn | T0 | hub sửa, 0 agent |
|
||
| Thiếu key i18n, UI hiện ra `a.b_c`, đã biết file | T1 | 5 → hub review |
|
||
| Nguyên nhân gốc đã có `file:line` từ người báo (dev) | T1 | 5 → hub review |
|
||
| Chạm QSS/token dùng chung, phải kiểm 2 theme | T2 | 4 (hoặc 2) → 5 → 6 |
|
||
| Lỗi do chính bản vá vừa merge | T3 | đủ pipeline — regression nghĩa là nguyên nhân gốc lần trước sai |
|
||
| Dev báo thẳng một lỗ hổng | T3-SEC | vào thẳng 7, bỏ bước 1 |
|
||
|
||
Bước **6** chỉ được bỏ ở T0 và T1. Ở T0 nó được thay bằng 4 cổng máy; ở T1 nó được thay bằng
|
||
hub review với `checklist/ui_review.md` (hợp lệ vì hub không viết patch ở T1). Ở T2/T3/T3-SEC
|
||
không có đường tắt nào bỏ qua bước 6.
|
||
|
||
## 6. Chạy bằng Claude Code
|
||
|
||
```bash
|
||
mkdir -p .claude/agents .claude/commands
|
||
cp agent/roles/[1-7]_*.md .claude/agents/
|
||
cp agent/commands/fix.md .claude/commands/
|
||
```
|
||
|
||
`.claude/` nằm trong `.gitignore` (dòng 109) nên phải cài lại trên mỗi clone — `agent/`
|
||
là bản gốc. `0_fix_dispatcher.md` không copy sang `agents/`: hub chạy ở session chính vì
|
||
subagent không gọi được subagent. Điểm vào:
|
||
|
||
```text
|
||
> /fix màn Folder kéo to ra thì mất cây thư mục bên trái
|
||
```
|
||
|
||
Hub in `dispatch_plan` rồi tự chạy lane. Muốn chạy tay lane FULL:
|
||
|
||
```text
|
||
> dùng ui-bug-triage cho phản ánh này: "màn Folder kéo to ra thì mất cây thư mục bên trái"
|
||
> dùng ui-visual-fixer với defect_record ở trên
|
||
> dùng fix-implementer với fix_plan ở trên
|
||
> dùng regression-reviewer với patch vừa rồi
|
||
```
|
||
|
||
Các bước trong **một** `defect_id` chạy tuần tự — mỗi bước phụ thuộc output của bước trước.
|
||
Các `defect_id` **độc lập** thì chạy song song được, gọi trong cùng một message.
|