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

2.8 KiB

Raw Blame History

Output Contract — `fix_plan`

Do ui-visual-fixer / ux-flow-fixer / i18n-a11y-fixer sinh ra. Đây là thứ fix-implementer thi hành — mơ hồ chỗ nào thì chỗ đó sẽ bị đoán bừa.

---
defect_id: UI-<YYYYMMDD>-<NN>
from_agent: <tên specialist>
next_agent: <fix-implementer | RETURN_TO_REPORTER>
root_cause_file: path/to/file.py:123
root_cause_pitfall: P__
confidence: <medium | high>
security_review: <required | not-required>
loc_risk: <none | near-limit | exceeds>
blast_radius: []          # màn/widget khác dùng chung phần bị sửa
---

1. Nguyên nhân gốc

Đúng một. Nêu file:line, trích đoạn code, và giải thích tại sao dòng đó sinh ra triệu chứng người dùng thấy.

# path/to/file.py:118

Vì sao đây là nguyên nhân gốc chứ không phải triệu chứng:

Các giả thuyết đã loại và lý do loại:

2. Ràng buộc thiết kế đã kiểm

Không mâu thuẫn với ràng buộc có chủ ý ở theme_tokens.md §4.
Nếu phản ánh của người dùng thực ra là thiết kế đúng: nêu ở đây và chuyển next_agent: RETURN_TO_REPORTER.

3. Phương án sửa

#	File	Thay đổi	Vì sao chọn mức này
1

Mức can thiệp đã chọn (theo thang ưu tiên của role):

Các phương án đã cân nhắc và bị loại:

4. Diff dự kiến

5. Ảnh hưởng lan toả

Chỗ khác dùng chung	Đã kiểm	Kết luận

Lệnh đã chạy để tìm:

grep -rn "<...>" --include=*.py .

6. Ràng buộc kiến trúc


Tầng bị sửa	presentation / ui / theme / i18n
Có chạm `application/` hoặc `domain/` không	không — hoặc lý do bắt buộc phải chạm
LOC file sau khi sửa	`___ / 400`
Cần tách module không	có/không — nếu có, tách thế nào
File mới có được import ngay không (Gate O)

7. i18n

Key	en	ja	vi	File
				`i18n/____.py`

Không thêm chuỗi mới thì ghi N/A.

8. Cách kiểm chứng

8.1 Test tự động

# tests/ui/test_____.py
def test_...(qtbot, ctx):
    """Regression: <triệu chứng> (defect UI-...)."""

Test này phải đỏ trước khi sửa. Nếu không viết được test tự động: nêu lý do cụ thể.

8.2 Kiểm bằng mắt

Trục	Giá trị phải thử	Kết quả mong đợi
Theme	dark, light
Ngôn ngữ
Kích thước cửa sổ	nhỏ nhất, maximize
Thứ tự thao tác	có kịch bản P07

9. Rủi ro

Rủi ro	Khả năng	Giảm thiểu

10. Out of scope

Cố ý không làm trong lần này, và vì sao.

2.8 KiB Raw Blame History

Output Contract — fix_plan