c7d71b77a7
Bộ 7 role chuyên biệt (triage → specialist → implementer → reviewer) cùng lớp dùng chung: guardrail, tri thức về repo, checklist, và contract đầu ra. Vì sao có: bug UI/UX được báo bằng lời kể triệu chứng, và người sửa hay bỏ qua ba thứ mà repo này rất dễ vi phạm — luật "không file nào ngoài theme/ được đặt tên một màu", trần LOC theo bánh cóc, và việc ui/ với presentation/ cùng tồn tại nên sửa nhầm file là "đã fix mà vẫn thấy lỗi". knowledge/qt_pitfalls.md chép lại 20 nguyên nhân gốc hay gặp của bug PySide6; examples/bad_fix.md có hai ca CÓ THẬT, gồm ca chính bản vá trong nhánh này từng mắc (compare_digest trên str ngoài ASCII) và lọt qua vòng review đầu. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
53 lines
3.0 KiB
Markdown
53 lines
3.0 KiB
Markdown
# Handoff Contract — envelope truyền giữa các agent
|
|
|
|
Mọi agent kết thúc lượt bằng khối YAML này, đặt **ngay trên** phần nội dung chính.
|
|
Đây là phần máy đọc; phần dưới nó là phần người đọc.
|
|
|
|
```yaml
|
|
---
|
|
defect_id: UI-2026-0907-01 # UI-<YYYYMMDD>-<số thứ tự trong ngày>
|
|
from_agent: ui-bug-triage
|
|
next_agent: ui-visual-fixer # xem bảng giá trị hợp lệ bên dưới
|
|
category: visual # visual | flow | i18n-a11y | security | not-ui
|
|
severity: S2 # S1 | S2 | S3 | S4
|
|
confidence: high # low | medium | high
|
|
reproducible: yes # yes | no | intermittent
|
|
security_review: not-required # required | not-required
|
|
affected_files:
|
|
- presentation/folder/folder_tab.py:118
|
|
- theme/qss.py:204
|
|
themes_verified: [dark, light] # [] nếu chưa kiểm
|
|
languages_verified: [vi] # [] nếu không liên quan
|
|
blocked_on: [] # danh sách open question CHẶN bước tiếp theo
|
|
---
|
|
```
|
|
|
|
## Giá trị hợp lệ của `next_agent`
|
|
|
|
| Giá trị | Nghĩa |
|
|
|---|---|
|
|
| `ui-visual-fixer` / `ux-flow-fixer` / `i18n-a11y-fixer` | Route sang specialist UI |
|
|
| `security-defect-fixer` | Route sang specialist bảo mật (`category: security`) |
|
|
| `fix-implementer` | Plan đã sẵn sàng để hiện thực |
|
|
| `regression-reviewer` | Patch đã sẵn sàng để review |
|
|
| `HUMAN_REVIEW` | Xong phía agent; chờ Cowork Team |
|
|
| `RETURN_TO_REPORTER` | Không phải bug, hoặc thiếu thông tin chặn, hoặc cần quyết định sản phẩm |
|
|
|
|
## Luật
|
|
|
|
1. **`defect_id` không đổi** suốt vòng đời một lỗi, kể cả khi quay vòng FAIL.
|
|
2. Một defect_record = **một nguyên nhân gốc**. Triage phát hiện hai nguyên nhân → tách
|
|
thành hai `defect_id`.
|
|
3. `confidence: low` → `next_agent` chỉ được là `ui-bug-triage` hoặc `RETURN_TO_REPORTER`.
|
|
4. `blocked_on` khác rỗng → agent nhận **không** được implement; chỉ được điều tra thêm.
|
|
5. `security_review: required` là **cờ dính**: một khi bật, không agent nào được tắt.
|
|
Chỉ Cowork Team gỡ được. `category: security` thì cờ này **luôn** bật.
|
|
6. `themes_verified` / `languages_verified` chỉ ghi thứ **thực sự đã kiểm**. Đây là chỗ hay
|
|
bị ghi khống nhất (`guardrail.md` G10).
|
|
7. Agent nhận envelope phải kiểm envelope trước khi làm việc. Thiếu trường hoặc mâu thuẫn
|
|
(ví dụ `confidence: low` mà `next_agent: fix-implementer`) → trả về ngay, không xử lý.
|
|
8. `category: security` thắng mọi nhóm khác. Một lỗi vừa lệch layout vừa lộ credential thì
|
|
`next_agent: security-defect-fixer`; phần UI tách thành `defect_id` riêng, xử lý sau.
|
|
9. `blocked_on` của role 7 có thể chứa câu hỏi **chính sách** (`needs-security-decision`).
|
|
Đó là chờ hợp lệ — người trả lời là Cowork Team, không phải agent khác.
|