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>
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,106 @@
|
||||
# Output Contract — `defect_record`
|
||||
|
||||
Do `ui-bug-triage` sinh ra. Giữ **đúng** thứ tự và tên mục. Không có dữ liệu thì ghi
|
||||
`unknown` hoặc `N/A` kèm lý do — **không xoá mục**.
|
||||
|
||||
---
|
||||
|
||||
```yaml
|
||||
---
|
||||
defect_id: UI-<YYYYMMDD>-<NN>
|
||||
from_agent: ui-bug-triage
|
||||
next_agent: <ui-visual-fixer | ux-flow-fixer | i18n-a11y-fixer | RETURN_TO_REPORTER>
|
||||
category: <visual | flow | i18n-a11y | not-ui>
|
||||
severity: <S1 | S2 | S3 | S4>
|
||||
confidence: <low | medium | high>
|
||||
reproducible: <yes | no | intermittent>
|
||||
security_review: <required | not-required>
|
||||
affected_files: []
|
||||
themes_verified: []
|
||||
languages_verified: []
|
||||
blocked_on: []
|
||||
---
|
||||
```
|
||||
|
||||
# 1. Tóm tắt
|
||||
|
||||
Một câu: cái gì hỏng, ở màn nào, với ai.
|
||||
|
||||
# 2. Quan sát vs kỳ vọng
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Người dùng thấy** | |
|
||||
| **Người dùng mong** | |
|
||||
| **Người dùng suy đoán (chưa xác minh)** | |
|
||||
|
||||
# 3. Môi trường
|
||||
|
||||
| Trường | Giá trị |
|
||||
|---|---|
|
||||
| Phiên bản app / commit | |
|
||||
| OS + độ phân giải + mức scale | |
|
||||
| Theme lúc xảy ra | |
|
||||
| Ngôn ngữ lúc xảy ra | |
|
||||
| Project / workspace liên quan | (mô tả, **không** nêu tên khách hàng) |
|
||||
|
||||
# 4. Các bước tái hiện
|
||||
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
|
||||
**Tỉ lệ tái hiện:** _luôn / thỉnh thoảng (n/m lần) / không_
|
||||
|
||||
# 5. Ma trận biến thể đã thử
|
||||
|
||||
| Biến thể | Đã thử | Kết quả |
|
||||
|---|---|---|
|
||||
| Theme dark | | |
|
||||
| Theme light | | |
|
||||
| Ngôn ngữ vi / ja / en | | |
|
||||
| Cửa sổ nhỏ nhất / maximize | | |
|
||||
| Đổi theme/ngôn ngữ **trước** rồi mới mở màn (bẫy P07) | | |
|
||||
|
||||
# 6. Khoanh vùng
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Nav row | Dashboard / Schedule / Workspace / Monitoring |
|
||||
| Sub-tab / dialog | |
|
||||
| `manifest.json` slug | |
|
||||
| Widget dựng tại | `file.py:line` |
|
||||
| Control (`controls.json`) | `var`, `type`, `object_name` |
|
||||
| Đã kiểm cả `ui/` và `presentation/` | có / không |
|
||||
|
||||
# 7. Giả thuyết nguyên nhân gốc
|
||||
|
||||
| # | Giả thuyết | Mã pitfall | Đã xác minh thế nào | Còn / loại |
|
||||
|---|---|---|---|---|
|
||||
| 1 | | P__ | | |
|
||||
| 2 | | P__ | | |
|
||||
|
||||
**Kết luận:** _(một nguyên nhân + `file:line`, hoặc "chưa xác định" nếu `confidence: low`)_
|
||||
|
||||
# 8. Tác động
|
||||
|
||||
- Ai bị ảnh hưởng:
|
||||
- Chặn công việc gì:
|
||||
- Có đường vòng không:
|
||||
- Lý do chọn mức `severity` này:
|
||||
|
||||
# 9. Cân nhắc bảo mật
|
||||
|
||||
- Chạm permission / credential / monitoring bảo mật / isolation / routing? _có / không_
|
||||
- Dữ liệu người dùng gửi lên đã redact? _có / không — mô tả đã bỏ gì_
|
||||
- Có dấu hiệu ở `system/security.md` S4 không?
|
||||
|
||||
# 10. Open Questions (tối đa 3)
|
||||
|
||||
| # | Câu hỏi | Mặc định nếu không trả lời | Có chặn không |
|
||||
|---|---|---|---|
|
||||
| 1 | | | có / không |
|
||||
|
||||
# 11. Out of scope
|
||||
|
||||
Vấn đề khác phát hiện được, **không** sửa trong lần này — đề xuất issue riêng.
|
||||
@@ -0,0 +1,114 @@
|
||||
# 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.
|
||||
|
||||
---
|
||||
|
||||
```yaml
|
||||
---
|
||||
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*.
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
```diff
|
||||
```
|
||||
|
||||
# 5. Ảnh hưởng lan toả
|
||||
|
||||
| Chỗ khác dùng chung | Đã kiểm | Kết luận |
|
||||
|---|---|---|
|
||||
| | | |
|
||||
|
||||
Lệnh đã chạy để tìm:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```python
|
||||
# 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.
|
||||
@@ -0,0 +1,111 @@
|
||||
# Output Contract — `fix_report`
|
||||
|
||||
Do `fix-implementer` sinh ra sau khi đã áp bản vá.
|
||||
Mục tiêu duy nhất: **trung thực** (`guardrail.md` G10). Reviewer sẽ chạy lại mọi thứ.
|
||||
|
||||
---
|
||||
|
||||
```yaml
|
||||
---
|
||||
defect_id: UI-<YYYYMMDD>-<NN>
|
||||
from_agent: fix-implementer
|
||||
next_agent: regression-reviewer
|
||||
branch: fix/ui-<slug>
|
||||
commits: []
|
||||
gate_result: <all-pass | partial | fail>
|
||||
tests_added: []
|
||||
visual_check: <done | not-done>
|
||||
security_review: <required | not-required>
|
||||
---
|
||||
```
|
||||
|
||||
# 1. Đã làm gì
|
||||
|
||||
| # | File | Thay đổi | Khớp mục nào trong fix_plan |
|
||||
|---|---|---|---|
|
||||
| 1 | | | §3.1 |
|
||||
|
||||
# 2. Diff
|
||||
|
||||
```bash
|
||||
git diff main...HEAD --stat
|
||||
```
|
||||
|
||||
```
|
||||
```
|
||||
|
||||
# 3. Test regression
|
||||
|
||||
| File test | Tên test | Đỏ trước khi sửa | Xanh sau khi sửa |
|
||||
|---|---|---|---|
|
||||
| | | ✅ / ❌ | ✅ / ❌ |
|
||||
|
||||
Bằng chứng "đỏ trước":
|
||||
|
||||
```
|
||||
```
|
||||
|
||||
Bằng chứng "xanh sau":
|
||||
|
||||
```
|
||||
```
|
||||
|
||||
Nếu chưa chứng minh được "đỏ trước": **nói rõ**, đừng bỏ trống.
|
||||
|
||||
# 4. Kết quả CASAN gate
|
||||
|
||||
```bash
|
||||
python scripts/run_quality_gate.py
|
||||
```
|
||||
|
||||
Dán **output thật**, không tóm tắt:
|
||||
|
||||
```
|
||||
```
|
||||
|
||||
| Cổng | Kết quả | Ghi chú |
|
||||
|---|---|---|
|
||||
| C — Clean Architecture | | |
|
||||
| A — Secrets | | |
|
||||
| S — LOC ≤ 400 | | LOC file lớn nhất: `___/400` |
|
||||
| O — Orphan module | | |
|
||||
| A/N — pytest | | |
|
||||
|
||||
## Test vốn đã đỏ TỪ TRƯỚC bản vá này
|
||||
|
||||
| Test | Lý do đỏ | Có liên quan bản vá không |
|
||||
|---|---|---|
|
||||
|
||||
# 5. Kiểm chứng bằng mắt
|
||||
|
||||
| Trục | Đã thử | Kết quả |
|
||||
|---|---|---|
|
||||
| dark | | |
|
||||
| light | | |
|
||||
| vi / ja / en | | |
|
||||
| cửa sổ nhỏ nhất / maximize | | |
|
||||
| kịch bản P07 | | |
|
||||
|
||||
Chưa chạy được app → ghi thẳng **"chưa kiểm chứng bằng mắt"** kèm lý do. Không suy đoán
|
||||
kết quả.
|
||||
|
||||
# 6. Lệch so với fix_plan
|
||||
|
||||
| Chỗ lệch | Vì sao |
|
||||
|---|---|
|
||||
|
||||
Không lệch thì ghi "không có".
|
||||
|
||||
# 7. Chưa làm được
|
||||
|
||||
| Việc | Vì sao | Đề xuất |
|
||||
|---|---|---|
|
||||
|
||||
# 8. Out of scope — phát hiện thêm khi sửa
|
||||
|
||||
Vấn đề khác nhìn thấy nhưng **không** sửa (G1, G8). Đề xuất mở issue riêng.
|
||||
|
||||
# 9. Bảo mật
|
||||
|
||||
- Có secret/PII lọt vào code, test fixture, commit message không? _đã kiểm — có/không_
|
||||
- Cờ `security_review` còn nguyên như plan? _có/không_
|
||||
@@ -0,0 +1,88 @@
|
||||
# Output Contract — `pr_body`
|
||||
|
||||
Do `regression-reviewer` sinh ra khi verdict là PASS / PASS_WITH_NOTES.
|
||||
Khớp **đúng** `.gitea/PULL_REQUEST_TEMPLATE.md` — giữ nguyên tiêu đề mục để reviewer quen mắt.
|
||||
|
||||
Tiêu đề PR: `fix(ui): <mô tả ngắn, tiếng Anh, thể mệnh lệnh>`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
_Nói **tại sao**, không chỉ **cái gì**. Nêu triệu chứng người dùng, nguyên nhân gốc kèm
|
||||
`file:line`, và vì sao chọn cách sửa này._
|
||||
|
||||
Root cause: `path/to/file.py:123` (pitfall P__)
|
||||
Defect: `UI-<YYYYMMDD>-<NN>`
|
||||
|
||||
## Change Type
|
||||
|
||||
- [ ] Cowork feature
|
||||
- [x] Bug fix
|
||||
- [ ] Core AI contribution
|
||||
- [ ] Test / hardening
|
||||
- [ ] Performance
|
||||
- [ ] Documentation
|
||||
|
||||
## Related Work
|
||||
|
||||
Cowork Task:
|
||||
|
||||
Core Repo: http://34.143.229.138/gitea-admin/fsg-ai-core-assets
|
||||
|
||||
Core AI Issue:
|
||||
|
||||
Core Task:
|
||||
|
||||
Related PR:
|
||||
|
||||
## Scope
|
||||
|
||||
**Cố ý bao gồm:**
|
||||
|
||||
**Cố ý KHÔNG bao gồm:** _(các phát hiện out-of-scope, kèm issue đề xuất)_
|
||||
|
||||
## Validation
|
||||
|
||||
- [ ] Unit tests
|
||||
- [ ] Integration tests
|
||||
- [ ] Manual verification
|
||||
- [ ] Regression check
|
||||
|
||||
Commands / evidence:
|
||||
|
||||
```bash
|
||||
python scripts/run_quality_gate.py
|
||||
QT_QPA_PLATFORM=offscreen pytest tests/ui/test_<...>.py -q
|
||||
```
|
||||
|
||||
```
|
||||
<output thật>
|
||||
```
|
||||
|
||||
Ma trận kiểm bằng mắt:
|
||||
|
||||
| Trục | Kết quả |
|
||||
|---|---|
|
||||
| dark / light | |
|
||||
| vi / ja / en | |
|
||||
| cửa sổ nhỏ nhất / maximize | |
|
||||
|
||||
## Security Impact
|
||||
|
||||
_Permission / credential / network / customer data impact._
|
||||
|
||||
Điền cả khi là "không có". Nếu `security-review: required`: ghi rõ tại sao, và nhắc rằng
|
||||
**CI xanh không đủ để merge** (`docs/governance/review-policy.md`).
|
||||
|
||||
## Compatibility
|
||||
|
||||
- [ ] No breaking change
|
||||
- [ ] Breaking change documented
|
||||
|
||||
## Reviewer Notes
|
||||
|
||||
_Chỉ đúng chỗ cần soi kỹ nhất. Kèm các finding `should-fix` / `nit` mà reviewer agent đã
|
||||
ghi nhận nhưng không chặn merge._
|
||||
|
||||
Ảnh `docs/screens/` cần chụp lại: _có/không — liệt kê slug_
|
||||
Reference in New Issue
Block a user