{/* Trang này được tạo tự động từ SKILL.md của kỹ năng bởi website/scripts/generate-skill-docs.py. Chỉnh sửa nguồn SKILL.md, không phải trang này. */}
Gỡ lỗi hệ thống
Gỡ lỗi gốc 4 giai đoạn: tìm hiểu lỗi trước khi sửa.
Siêu dữ liệu kỹ năng
| Nguồn | Đi kèm (được cài đặt theo mặc định) |
| Đường dẫn |
skills/software-development/systematic-debugging ` | | Phiên bản |
1.1.0 ` | | Tác giả | Đặc vụ Hermes (chuyển thể từ obra/siêu năng lực) | | Giấy phép | MIT | | Nền tảng | Linux, macOS, Windows | | Thẻ |
debugging
, `troubleshooting
, `problem-solving
, `root-cause
,
investigation |
| Kỹ năng liên quan | XPROTECTX14XPROTECTX, XPROTECTX15XPROTECTX, XPROTECTX16XPROTECTX |
Tham khảo: đầy đủ SKILL.md
thông tin
Sau đây là định nghĩa kỹ năng đầy đủ mà Hermes tải khi kỹ năng này được kích hoạt. Đây là những gì tác nhân coi là hướng dẫn khi kỹ năng được kích hoạt.
Gỡ lỗi hệ thống
Tổng quan
Sửa lỗi ngẫu nhiên lãng phí thời gian và tạo ra lỗi mới. Các bản vá nhanh che giấu các vấn đề tiềm ẩn.
Nguyên tắc cốt lõi: LUÔN tìm ra nguyên nhân gốc rễ trước khi thử khắc phục. Sửa chữa triệu chứng là thất bại.
Vi phạm nội dung của quy trình này là vi phạm tinh thần gỡ lỗi.
Luật Sắt
` NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
` ``Nếu chưa hoàn thành Giai đoạn 1, bạn không thể đề xuất cách khắc phục.
Khi nào nên sử dụng
Sử dụng cho BẤT KỲ vấn đề kỹ thuật nào:
- Kiểm tra thất bại
- Lỗi trong quá trình sản xuất
- Hành vi bất ngờ
- Vấn đề về hiệu suất
- Xây dựng thất bại
- Vấn đề tích hợp`Sử dụng tính năng này ĐẶC BIỆT khi:
- Chịu áp lực về thời gian (những trường hợp khẩn cấp khiến việc đoán mò trở nên hấp dẫn)
- "Chỉ cần một lần sửa nhanh" có vẻ hiển nhiên
- Bạn đã thử nhiều cách khắc phục
- Sửa lần trước không được
- Bạn chưa hiểu rõ vấn đề`Đừng bỏ qua khi:
- Vấn đề có vẻ đơn giản (lỗi đơn giản cũng có nguyên nhân gốc rễ)
- Bạn đang vội (gấp rút đảm bảo phải làm lại)
- Có người muốn nó được sửa NGAY BÂY GIỜ (có tính hệ thống nhanh hơn là đập phá)
Bốn giai đoạn
Bạn PHẢI hoàn thành từng giai đoạn trước khi chuyển sang giai đoạn tiếp theo.
Giai đoạn 1: Điều tra nguyên nhân gốc rễ`TRƯỚC KHI thử BẤT KỲ cách khắc phục nào:
1. Đọc kỹ thông báo lỗi
- Đừng bỏ qua các lỗi hoặc cảnh báo trong quá khứ
- Chúng thường chứa giải pháp chính xác
- Đọc hoàn toàn dấu vết ngăn xếp
- Ghi chú số dòng, đường dẫn file, mã lỗi
**Hành động:** Sử dụngread_filetrên các tệp nguồn có liên quan. Sử dụngsearch_files ` để tìm chuỗi lỗi trong cơ sở mã.
2. Tái sản xuất một cách nhất quán
- Bạn có thể kích hoạt nó một cách đáng tin cậy không?
- Các bước cụ thể là gì?
- Lần nào cũng vậy à?
- Nếu không thể tái tạo → thu thập thêm dữ liệu, đừng đoán
**Hành động:** Sử dụng công cụterminal ` để chạy thử nghiệm thất bại hoặc kích hoạt lỗi:
# Run specific failing test
pytest tests/test_module.py::test_name -v
# Run with verbose output
pytest tests/test_module.py -v --tb=long
`
### 3. Kiểm tra các thay đổi gần đây
- Điều gì đã thay đổi có thể gây ra điều này?
- Git khác, các cam kết gần đây
- Phụ thuộc mới, thay đổi cấu hình`**Hành động:**
``` bash
# Recent commits
git log --oneline -10
# Uncommitted changes
git diff
# Changes in specific file
git log -p --follow src/problematic_file.py | head -100
`
### 4. Thu thập bằng chứng trong hệ thống đa thành phần`** KHI hệ thống có nhiều thành phần (API → dịch vụ → cơ sở dữ liệu, CI → xây dựng → triển khai):**`**TRƯỚC KHI đề xuất cách khắc phục, hãy thêm công cụ chẩn đoán:**
Đối với MỖI ranh giới thành phần:
- Ghi lại dữ liệu nào được đưa vào thành phần
- Ghi lại dữ liệu nào thoát khỏi thành phần
- Xác minh sự lan truyền của môi trường/cấu hình
- Kiểm tra trạng thái ở mỗi lớp
Chạy một lần để thu thập bằng chứng cho thấy nó bị hỏng ở đâu.
SAU ĐÓ phân tích bằng chứng để xác định thành phần bị lỗi.
SAU ĐÓ hãy điều tra thành phần cụ thể đó.
### 5. Theo dõi luồng dữ liệu`** KHI có lỗi sâu trong ngăn xếp cuộc gọi:**
- Giá trị xấu bắt nguồn từ đâu?
- Hàm này có giá trị xấu gọi là gì?
- Tiếp tục truy tìm ngược dòng cho đến khi tìm được nguồn
- Chữa tại gốc, không chữa tại triệu chứng`**Hành động:** Sử dụng
`search_files
` để theo dõi các tài liệu tham khảo:
``` python
# Find where the function is called
search_files("function_name(", path="src/", file_glob="*.py")
# Find where the variable is set
search_files("variable_name\\s*=", path="src/", file_glob="*.py")
`
### Danh sách kiểm tra hoàn thành giai đoạn 1
- [ ] Thông báo lỗi được đọc và hiểu đầy đủ
- [ ] Vấn đề được sao chép nhất quán
- [ ] Những thay đổi gần đây được xác định và xem xét
- [ ] Bằng chứng được thu thập (nhật ký, trạng thái, luồng dữ liệu)
- [ ] Vấn đề riêng biệt đối với thành phần/mã cụ thể
- [ ] Giả thuyết nguyên nhân gốc rễ được hình thành`**DỪNG:** Không chuyển sang Giai đoạn 2 cho đến khi bạn hiểu TẠI SAO điều đó lại xảy ra.
---
## Giai đoạn 2: Phân tích mẫu`**Tìm mẫu trước khi sửa:**
### 1. Tìm ví dụ hoạt động
- Xác định vị trí mã làm việc tương tự trong cùng một cơ sở mã
- Cái gì hoạt động giống với cái gì bị hỏng?
**Hành động:** Sử dụng
`search_files
` để tìm các mẫu có thể so sánh:
``` python
search_files("similar_pattern", path="src/", file_glob="*.py")
`
### 2. So sánh với tài liệu tham khảo- Nếu triển khai một mẫu, hãy đọc HOÀN TOÀN phần triển khai tham chiếu
- Đừng đọc lướt - đọc từng dòng
- Hiểu rõ mẫu trước khi áp dụng
### 3. Xác định sự khác biệt
- Làm việc và bị hỏng có gì khác nhau?
- Liệt kê mọi sự khác biệt, dù nhỏ
- Đừng cho rằng "điều đó không quan trọng"
### 4. Hiểu sự phụ thuộc
- Cái này cần những thành phần gì nữa?
- Cài đặt, cấu hình, môi trường gì?
- Nó đưa ra giả định gì?
---
## Giai đoạn 3: Giả thuyết và kiểm nghiệm`**Phương pháp khoa học:**
### 1. Hình thành một giả thuyết duy nhất
- Nêu rõ: “Tôi nghĩ X là nguyên nhân sâu xa vì Y”
- Viết nó ra
- Cụ thể, không mơ hồ
### 2. Kiểm tra ở mức tối thiểu
- Thực hiện thay đổi NHỎ NHẤT có thể để kiểm tra giả thuyết
- Mỗi lần một biến
- Không sửa nhiều việc cùng một lúc
### 3. Xác minh trước khi tiếp tục
- Nó có tác dụng không? → Giai đoạn 4
- Không thành công à? → Hình thành giả thuyết MỚI
- KHÔNG thêm nhiều bản sửa lỗi lên trên
### 4. Khi Bạn Không Biết
- Nói "Tôi không hiểu X"
- Đừng giả vờ như biết
- Yêu cầu người dùng giúp đỡ
- Nghiên cứu thêm
---
## Giai đoạn 4: Thực hiện`**Khắc phục tận gốc chứ không phải triệu chứng:**
### 1. Tạo ca kiểm thử thất bại
- Tái tạo đơn giản nhất có thể
- Kiểm tra tự động nếu có thể
- PHẢI có trước khi sửa
- Sử dụng kỹ năng
`test-driven-development
### 2. Thực hiện sửa lỗi đơn
- Giải quyết nguyên nhân gốc rễ được xác định
- MỘT thay đổi tại một thời điểm
- Không có cải tiến "trong khi tôi ở đây"
- Không tái cấu trúc đi kèm
### 3. Xác minh sửa lỗi
``` bash
# Run the specific regression test
pytest tests/test_module.py::test_regression -v
# Run full suite — no regressions
pytest tests/ -q
`
### 4. Nếu việc sửa lỗi không hiệu quả — Quy tắc số ba
- **DỪNG.**
- Đếm: Bạn đã thử bao nhiêu bản sửa lỗi rồi?
- Nếu < 3: Quay lại Giai đoạn 1, phân tích lại với thông tin mới
- **Nếu ≥ 3: DỪNG và đặt câu hỏi về kiến trúc (bước 5 bên dưới)**
- KHÔNG cố gắng khắc phục số 4 mà không thảo luận về kiến trúc
### 5. Nếu hơn 3 lần sửa lỗi không thành công: Cấu trúc câu hỏi`**Mẫu biểu thị vấn đề về kiến trúc:**
- Mỗi bản sửa lỗi sẽ hiển thị trạng thái/khớp nối được chia sẻ mới ở một nơi khác
- Các bản sửa lỗi yêu cầu "tái cấu trúc hàng loạt" để triển khai
- Mỗi lần sửa chữa sẽ tạo ra triệu chứng mới ở nơi khác`**DỪNG LẠI và đặt câu hỏi về các nguyên tắc cơ bản:**
- Mô hình này về cơ bản có hợp lý không?
- Có phải chúng ta đang "gắn bó với nó nhờ quán tính tuyệt đối"?
- Chúng ta có nên cấu trúc lại kiến trúc hay tiếp tục sửa chữa các triệu chứng?
**Thảo luận với người dùng trước khi thử các cách khắc phục khác.**
Đây KHÔNG phải là một giả thuyết thất bại - đây là một kiến trúc sai.
---
## Cờ đỏ - DỪNG và theo dõi quá trình
Nếu bạn bắt gặp mình đang suy nghĩ:
- "Sửa nhanh bây giờ, điều tra sau"
- "Cứ thử thay đổi X xem có được không"
- "Thêm nhiều thay đổi, chạy thử nghiệm"
- "Bỏ qua bài kiểm tra, tôi sẽ xác minh thủ công"
- "Chắc là X, để tôi sửa"
- "Tôi không hiểu lắm nhưng cách này có thể hiệu quả"
- "Mẫu ghi X nhưng tôi sẽ điều chỉnh theo cách khác"
- "Đây là những vấn đề chính: [liệt kê các cách khắc phục mà không cần điều tra]"
- Đề xuất giải pháp trước khi truy tìm luồng dữ liệu
- **"Thêm một lần sửa lỗi nữa" (khi đã thử 2+)**
- **Mỗi lần sửa sẽ phát hiện một vấn đề mới ở một nơi khác**`**TẤT CẢ những điều này có nghĩa là: DỪNG LẠI. Quay lại Giai đoạn 1.**`**Nếu hơn 3 lần sửa lỗi không thành công:** Đặt câu hỏi về kiến trúc (Giai đoạn 4, bước 5).
## Những cách hợp lý hóa phổ biến
| Xin lỗi | Thực tế |
|--------|----------|
| "Vấn đề đơn giản, không cần quá trình" | Những vấn đề đơn giản cũng có nguyên nhân gốc rễ. Quá trình nhanh chóng đối với các lỗi đơn giản. |
| "Trường hợp khẩn cấp, không có thời gian xử lý" | Gỡ lỗi có hệ thống NHANH CHÓNG hơn so với việc đoán và kiểm tra. |
| "Cứ thử cái này trước rồi điều tra" | Bản sửa lỗi đầu tiên đặt mẫu. Hãy làm đúng ngay từ đầu. |
| "Tôi sẽ viết bài kiểm tra sau khi xác nhận đã khắc phục được" | Các bản sửa lỗi chưa được kiểm tra không dính. Thử nghiệm đầu tiên chứng minh điều đó. |
| "Sửa nhiều lần cùng lúc giúp tiết kiệm thời gian" | Không thể cô lập những gì đã làm việc. Gây ra lỗi mới. |
| "Tham khảo dài quá, tôi sẽ sửa lại mẫu" | Sự hiểu biết một phần đảm bảo có lỗi. Đọc nó hoàn toàn. |
| "Tôi thấy có vấn đề rồi, để tôi khắc phục" | Nhìn thấy triệu chứng ≠ hiểu nguyên nhân gốc rễ. |
| "Thêm một lần sửa lỗi nữa" (sau hơn 2 lần thất bại) | 3+ thất bại = vấn đề kiến trúc. Hãy hỏi mẫu, đừng sửa lại. |
## Tham khảo nhanh
| Giai đoạn | Hoạt động chính | Tiêu chí thành công |
|-------|--------------||-------------------|
| **1. Nguyên nhân gốc rễ** | Đọc lỗi, tái tạo, kiểm tra các thay đổi, thu thập bằng chứng, theo dõi luồng dữ liệu | Hiểu CÁI GÌ và TẠI SAO |
| **2. Mẫu** | Tìm các ví dụ hoạt động, so sánh, xác định sự khác biệt | Biết có gì khác biệt |
| **3. Giả thuyết** | Lý thuyết dạng, kiểm tra tối thiểu, mỗi lần một biến | Giả thuyết mới hoặc được xác nhận |
| **4. Thực hiện** | Tạo kiểm tra hồi quy, khắc phục nguyên nhân gốc rễ, xác minh | Lỗi đã được giải quyết, tất cả các bài kiểm tra đều đạt |## Tích hợp đại lý Hermes
### Công cụ điều tra
Sử dụng các công cụ Hermes này trong Giai đoạn 1:
- **
`search_files
** — Tìm chuỗi lỗi, theo dõi lệnh gọi hàm, định vị mẫu
- **
`read_file
** — Đọc mã nguồn với số dòng để phân tích chính xác
- **
`terminal
** — Chạy thử nghiệm, kiểm tra lịch sử git, tái tạo lỗi
- **
`web_search
/
`web_extract
** — Nghiên cứu thông báo lỗi, tài liệu thư viện
### Với delegate_task
Để gỡ lỗi nhiều thành phần phức tạp, hãy gửi các tác nhân phụ điều tra:
``` python
delegate_task(
goal="Investigate why [specific test/behavior] fails",
context="""
Follow systematic-debugging skill:
1. Read the error message carefully
2. Reproduce the issue
3. Trace the data flow to find root cause
4. Report findings — do NOT fix yet
Error: [paste full error]
File: [path to failing code]
Test command: [exact command]
""",
toolsets=['terminal', 'file']
)
`
### Với sự phát triển dựa trên thử nghiệm
Khi sửa lỗi:
1. Viết bài kiểm tra tái hiện lỗi (ĐỎ)
2. Gỡ lỗi một cách có hệ thống để tìm ra nguyên nhân gốc rễ
3. Khắc phục tận gốc (XANH)
4. Thử nghiệm chứng minh cách khắc phục và ngăn chặn sự hồi quy
## Tác động trong thế giới thực
Từ các phiên gỡ lỗi:
- Cách tiếp cận có hệ thống: 15-30 phút để khắc phục
- Phương pháp sửa lỗi ngẫu nhiên: 2-3 giờ đập
- Tỷ lệ sửa lỗi lần đầu: 95% so với 40%
- Lỗi mới được giới thiệu: Gần bằng 0 so với phổ biến`** Không có phím tắt. Không cần đoán. Có hệ thống luôn thắng.**