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>
4.1 KiB
4.1 KiB
Guardrail — luật bất biến cho mọi agent trong agent/
Áp dụng cho cả 6 role. Role nào mâu thuẫn với file này thì file này thắng.
G1. Không tự bịa requirement
- Chỉ làm việc trên những gì có trong bug report, source code, và
knowledge/. - Thiếu thông tin → ghi vào mục Assumption hoặc Open Question, KHÔNG tự suy diễn rồi sửa theo suy diễn đó.
- Không tự ý "tiện tay cải thiện UX" ngoài phạm vi lỗi được báo. Phát hiện vấn đề khác → ghi vào mục Out of scope (đề xuất issue riêng).
G2. Không đoán vị trí code
- Mọi khẳng định về code phải kèm
path/file.py:line. Chưa đọc file thì chưa được kết luận. - Người dùng mô tả bằng tiếng Việt/Nhật → tra
knowledge/screen_map.mdvàdocs/screens/controls.jsonđể tìm đúng widget, không đoán theo tên gọi.
G3. Sửa đúng tầng
Cowork Local là Clean Architecture 4 tầng, phụ thuộc chỉ hướng vào trong:
presentation/ → application/ → domain/ ← infrastructure/
- Bug UI/UX được sửa ở
presentation/,ui/,theme/,i18n/. Đó là mặc định. - Nếu buộc phải đụng
application/hoặcdomain/, phải nêu rõ lý do tại sao không sửa được ở tầng trên trongfix_plan.md, và coi đó là thay đổi cần reviewer chú ý. domain/vàapplication/là 100% Pure Python. Tuyệt đối không thêm importPySide6/PyQtvào hai tầng này — Gate C sẽ chặn.- Widget chỉ gọi xuống service của
application/. Không query SQLite/JSON trực tiếp, không gọi LLM trực tiếp trong GUI thread.
G4. Không đặt tên màu ngoài theme/
- Không hex literal (
#1f6fb2), khôngQColor("red"), khôngsetStyleSheet("color: blue")trong bất kỳ file nào ngoàitheme/. - Sửa màu = sửa/đọc token trong
theme/palettes.py, hoặc gánobjectNamerồi style trongtheme/qss.py. Chi tiết:knowledge/theme_tokens.md. - Đây là lỗi bị từ chối review thường xuyên nhất khi sửa bug UI.
G5. Không hardcode chuỗi hiển thị
- Mọi text người dùng nhìn thấy đi qua
tr("key"). Chi tiết:knowledge/i18n_rules.md. - Sửa một nhãn = sửa cả 3 ngôn ngữ
en/ja/vi, không sửa mỗi tiếng Việt.
G6. Giữ Single Responsibility
- Mọi module production
<= 400 LOC(Gate S). Nếu bản vá làm file vượt 400 dòng, phải tách module — và việc tách đó phải nêu trongfix_plan.mdtrước khi làm. - Không "sửa bug" bằng cách nhét thêm 150 dòng vào một file đã 380 dòng.
G7. Không làm suy yếu kiểm thử
- Không xoá test, không
@pytest.mark.skip, không nới assert để pass gate. - Test đang đỏ vì lý do khác → báo trong report, không sửa lén.
- Mỗi bug UI được sửa nên có ít nhất một test tái hiện, chạy được headless
(
QT_QPA_PLATFORM=offscreen).
G8. Bản vá tối thiểu
- Ưu tiên bản vá nhỏ nhất khắc phục được nguyên nhân gốc, không phải triệu chứng.
- Không refactor kèm trong PR fix bug. Một PR = một thay đổi logic (Definition of Done).
- Không đổi format/indent toàn file — diff phải đọc được.
G9. Không tự merge, không tự đóng issue
- Agent chỉ đề xuất. Quyết định merge thuộc Cowork Team (
docs/governance/ownership.md). - Thay đổi chạm tới permission, credential, MCP write/exec, sandbox, network, TLS,
isolation, model routing, xoá dữ liệu → bắt buộc đánh dấu
security-review: requiredtrong output, kể cả khi chỉ sửa UI.
G10. Trung thực về kết quả
- Chưa chạy được test thì ghi "chưa chạy", không ghi "đã pass".
- Sửa được 2/3 vấn đề trong report thì nói rõ phần còn lại và lý do.
- Không chắc nguyên nhân gốc → ghi mức tin cậy (
confidence: low/medium/high) và liệt kê giả thuyết thay thế.