Files

T

anhtnm1andClaude Opus 5 7bd2b95a57 docs(agent): thư viện instruction cho việc sửa bug UI/UX

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>

2026-09-07 19:55:02 +09:00

3.0 KiB

Raw Blame History

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.

---
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

defect_id không đổi suốt vòng đời một lỗi, kể cả khi quay vòng FAIL.
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.
confidence: low → next_agent chỉ được là ui-bug-triage hoặc RETURN_TO_REPORTER.
blocked_on khác rỗng → agent nhận không được implement; chỉ được điều tra thêm.
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.
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).
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ý.
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.
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.

3.0 KiB Raw Blame History

Handoff Contract — envelope truyền giữa các agent

Giá trị hợp lệ của next_agent

Luật

3.0 KiB

Raw Blame History

Giá trị hợp lệ của `next_agent`