Skill
Sửa lỗi đã chứng minh với ak:fix
Scout và chẩn đoán một lỗi cụ thể, triển khai repair nhỏ nhất đúng nguyên nhân và chứng minh repair không có side effect ẩn.
Dùng ak:fix để đưa một bug, error, test thất bại, lỗi CI hoặc UI defect cụ thể
từ bằng chứng tới repair đã xác minh. Skill xác định behavior mong đợi, scout
project hiện tại, chứng minh root cause, chọn workflow từ blast radius thực tế
và không coi symptom patch là hoàn tất.
Chọn ak:fix cho một lỗi cụ thể
Dùng ak:fix khi
- Bạn có error, reproduction, assertion thất bại hoặc behavior hỏng chính xác.
- Lỗi type, lint, test, log, CI hoặc UI cần thay đổi code.
- Nhiều tệp có thể dùng chung một root cause và cần verification được điều phối.
- Bạn muốn diagnosis, implementation, regression protection và review trong cùng workflow.
Chọn workflow khác khi
- Bạn vẫn cần chứng minh root cause mà chưa muốn cam kết repair. Bắt đầu với
ak:debug. - Bạn đang giao feature hoặc refactor thay vì sửa lỗi. Dùng
ak:cook. - Bạn chỉ cần chạy test hoặc review độc lập. Dùng
ak:testhoặcak:code-review. - Diagnosis phức tạp còn lựa chọn architecture quan trọng. Dùng
ak:brainstormvàak:plantrước implementation.
Chuẩn bị repair contract
Trước khi bắt đầu:
- Hoàn thành Làm quen và xác nhận Engineer Kit đã được cài cho đúng runtime cùng scope bạn đang dùng.
- Cung cấp triệu chứng, reproduction tối thiểu, behavior mong đợi, behavior thực tế và environment liên quan chính xác.
- Nêu constraint, non-goal, acceptance criteria cùng ranh giới quyền hạn cho Git, hệ thống bên ngoài, production data và publication.
- Giữ nguyên công việc không liên quan và cung cấp commit gần đây, test bị ảnh hưởng cùng instruction của project.
| Runtime | Cách gọi | Ranh giới khả dụng |
|---|---|---|
| Claude Code | /ak:fix ... | Phân phối native là mặc định; phân phối plugin rõ ràng cũng được hỗ trợ. |
| Cursor | /ak:fix ... | Cách gọi bằng slash đã được người dùng xác minh. Điều này không thiết lập runtime parity đầy đủ. |
| Codex | $ak:fix ... | Skill dùng discovery native của Codex; không suy ra parity rộng hơn cho Hook và statusline Engineer. |
Chạy Skill
/ak:fix "POST /api/sessions returns 500 when expiresAt is absent. Reproduce with the focused API test, preserve the response contract, and do not commit or deploy." --review/ak:fix "POST /api/sessions returns 500 when expiresAt is absent. Reproduce with the focused API test, preserve the response contract, and do not commit or deploy." --review$ak:fix "POST /api/sessions returns 500 when expiresAt is absent. Reproduce with the focused API test, preserve the response contract, and do not commit or deploy." --review--auto là mặc định. Chọn mode khác khi rủi ro hoặc hình dạng issue yêu cầu:
| Tùy chọn | Behavior | Ranh giới quan trọng |
|---|---|---|
--auto | Chạy tự động và chỉ auto-approve review khi điểm từ 9.5 trở lên, không có Critical finding | Blocker, regression và quyết định quyền hạn chưa xử lý vẫn được escalate |
--review | Dừng để con người review tại mỗi bước chính | Phù hợp cho production, security-sensitive hoặc public-contract work |
--quick | Dùng cycle scout, diagnosis, repair, verification và review ngắn | Chỉ dành cho lỗi type, lint, syntax hoặc defect trực tiếp trong một tệp; bằng chứng root cause vẫn bắt buộc |
--parallel | Chuyển issue độc lập vào workstream có ownership riêng | Issue phải độc lập, ownership không chồng lấn và runtime delegation phải khả dụng cùng được cho phép |
--ultra | Chạy lựa chọn fix plan sau diagnosis dưới dạng best-of-5 verifier pass | Yêu cầu parallel read-only dispatch và xung đột với --quick cùng --parallel |
--advice | Thêm checkpoint tư vấn sau mỗi phase, khi bị kẹt, trước quyết định rủi ro cao và ở lần xác minh thất bại bất ngờ đầu tiên | Adviser chỉ đưa counsel; không thể edit, approve hay mở rộng quyền hạn. Tuân Failure Protocol của plan khi có; dừng cho kongming trước khi tự suy luận |
--ultra chạy Steps 0-2 một lần, sau đó gửi diagnosis đã xác nhận trong một
immutable evidence packet tới đúng năm candidate độc lập, read-only trong một
parallel wave. Verifier chấm các fix plan hoàn chỉnh theo cause-alignment,
blast-radius safety, minimality và verifiability, rồi chọn nguyên trạng một plan
hoặc reject all. Chỉ plan được chọn mới tiếp tục qua Steps 4-6. Mode sẽ dừng nếu
parallel read-only dispatch không khả dụng.
Với nhiều lỗi không liên quan, hãy liệt kê riêng từng triệu chứng và reproduction. Với một lỗi có nhiều triệu chứng, nêu lý do bạn nghĩ chúng có thể chung nguyên nhân nhưng để diagnosis chứng minh hoặc bác bỏ việc nhóm đó.
Hiểu điều gì xảy ra trong một lần chạy
- Skill xác định repair contract. Skill ghi nhận outcome, constraint, non-goal cùng acceptance criteria trước khi chọn mode.
- Skill scout project. Skill xác định stack, tệp có triệu chứng, caller và dependent, test liên quan, commit gần đây cùng pattern hiện có.
- Skill chứng minh diagnosis. Skill ghi error cùng reproduction chính xác, lần theo root cause, giải thích vì sao issue xuất hiện lúc này và lập bản đồ mọi path trong blast radius.
- Skill phân loại công việc. Công việc đơn giản dùng quick route; công việc
vừa theo dõi sáu phase phụ thuộc; công việc phức tạp thêm research, so sánh
solution sau diagnosis và plan. Các lỗi độc lập có thể dùng parallel tree
riêng. Với
--ultra, chỉ bước chọn fix plan được fan out; diagnosis và implementation vẫn chỉ chạy một lần. - Skill triển khai repair đã chọn. Skill thay đổi root cause bằng diff nhỏ nhất phù hợp project và giữ non-goal ngoài scope.
- Skill xác minh và ngăn tái diễn. Skill lặp đúng command trước fix, thêm regression test, kiểm tra caller bị ảnh hưởng, kiểm tra public contract và áp dụng validation layer phù hợp.
- Skill review và hoàn tất. Finding được chấp nhận sẽ được sửa rồi re-verify. Tiến độ plan được đối chiếu, ảnh hưởng tài liệu được đánh giá và journal local ghi lại lịch sử kỹ thuật.
So sánh shadow tùy chọn
Skill hoàn tất phần đánh giá độ phức tạp của chính nó trước và không gọi dịch
vụ quyết định nào theo mặc định. Chỉ khi bạn yêu cầu một thử nghiệm semantic,
hoặc context đã có sẵn một opt-in đáng tin cậy từ bạn, Skill mới có thể chạy
ak eval decision để so sánh kết quả
phân loại với một kết quả shadow. Skill chỉ gửi bản tóm tắt ngắn, không nhạy
cảm về chẩn đoán, không bao giờ gửi tệp source, log, transcript hay credential.
Phép so sánh chỉ mang tính shadow. Skill vẫn theo workflow độ phức tạp hiện có,
giữ nguyên --parallel tường minh và giữ kết quả của chính nó khi có bất đồng,
timeout hoặc provider không khả dụng. Lệnh tự kiểm tra consent ở user scope một
cách độc lập. Một phép so sánh là bằng chứng thử nghiệm, không phải cải thiện đã
được đo lường.
Ngoài ra, chỉ khi bạn yêu cầu tường minh, Skill mới có thể chuẩn bị một request có
giới hạn và đã được review cho ak eval workflow với
workflow fix. Mode mặc định off xác thực request cục bộ. --mode shadow
còn cần cấu hình master và provider ở user scope, consent tường minh
workflow-controller: true của bạn và credential của provider; Skill không bao
giờ suy ra consent từ một key có sẵn trong môi trường. Mode shadow có thể gửi dữ
kiện đã được làm sạch tới provider bên ngoài và phát sinh chi phí.
Thử nghiệm không bao giờ thay đổi việc Skill làm. Quyết định retry, replan và escalation có hiệu lực được giữ nguyên, gợi ý chỉ được ghi lại để so sánh, và khi có lỗi, độ tin cậy thấp hoặc provider không khả dụng thì Skill dùng workflow hiện có. Skill không bao giờ thực thi một gợi ý hay coi nó là quyền. Giới hạn hiện có, lệnh dừng của bạn, checkpoint con người sau ba lần sửa thất bại và các kiểm soát phê duyệt vẫn có hiệu lực. Việc dùng Skill thông thường không gọi lệnh này.
Giữ nguyên các hard gate
Automation không cho phép đoán
Không mode nào được đề xuất hoặc triển khai repair trước scouting và diagnosis. Bản ghi root cause phải nêu triệu chứng, reproduction, expected so với actual behavior, defect cụ thể, lý do lỗi lộ ra lúc này và blast radius.
--autobỏ các lần dừng thường lệ; nó không cấp quyền cho secret, production write, chi phí bên ngoài, publication, deployment hoặc hành động phá hủy.- Regression hoặc contract change sẽ dừng workflow. Bạn chọn revert, thu hẹp repair, cập nhật dependent hoặc chấp nhận rõ behavior đã đổi.
- Regression test phải chứng minh scenario đã sửa và reproduction ban đầu phải pass với output mới.
- Critical review finding chặn completion. Automatic review cycle có giới hạn; lỗi lặp lại sẽ escalate thay vì chạy vô hạn.
- Sau ba repair attempt thất bại, Skill dừng và yêu cầu bạn xem lại architecture hoặc scope.
- Commit, push, pull request, chạy lại CI, comment bên ngoài và deployment là hành động riêng cần quyền riêng.
Xác minh kết quả
Một lần chạy hoàn tất nên cung cấp:
- Repair contract đã chấp nhận cùng baseline trước fix chính xác.
- Scout summary gồm tệp bị ảnh hưởng, dependent, test và thay đổi gần đây.
- Câu root-cause cụ thể với bằng chứng, điều kiện làm lộ lỗi và blast radius.
- Implementation diff tối thiểu cùng biện pháp ngăn regression.
- Kết quả reproduction before-and-after cùng check tập trung và blast-radius.
- Code-review finding, điểm số và cách xử lý mọi blocker hoặc warning.
- Xác nhận public contract không đổi hoặc quyết định rõ cho mỗi thay đổi có chủ đích.
- Trạng thái plan được cập nhật khi áp dụng, quyết định docs-impact và technical journal ngắn gọn.
Đừng coi lần chạy hoàn tất khi bất kỳ trường root-cause nào còn mơ hồ, triệu chứng ban đầu vẫn tái hiện, blast-radius check thất bại hoặc review blocker đã chấp nhận chưa được xử lý.
Xử lý sự cố hoặc tiếp tục
| Triệu chứng | Bước tiếp theo an toàn |
|---|---|
| Skill hỏi log hoặc chi tiết reproduction | Cung cấp output, command, input, environment và expected behavior chính xác. Đừng thay bằng nguyên nhân có vẻ đúng. |
--quick phát hiện nhiều tệp hoặc lựa chọn design | Escalate sang standard hoặc deep route trước implementation. |
| Nhiều fix thất bại | Giữ các hypothesis bị bác bỏ và dừng sau cycle thứ ba để đánh giá lại architecture hoặc scope. |
| Một test pass nhưng dependent workflow hỏng | Giữ regression hiển thị và chọn revert, scope hẹp hơn, cập nhật dependent hoặc chấp nhận rõ. |
| Parallel work chồng lấn tệp | Dừng workstream bị ảnh hưởng, xác định lại exclusive ownership và kiểm tra lại integration point chung. |
| Review luôn thấp hơn automatic threshold | Xử lý Critical finding, review warning hoặc chuyển sang quyết định rõ của con người; đừng tạo điểm pass giả. |
| Runtime không nhận diện Skill | Xác nhận target cùng scope, mở runtime session mới, rồi làm theo Runtime không tìm thấy Skill hoặc Agent. |
Dùng ak:test cho validation độc lập và ak:code-review cho review riêng sau
repair.
Biết các giới hạn hiện tại
- Skill chỉ có thể tái hiện environment và chạy check có trong session hiện tại.
- Mode parallel và advice phụ thuộc capability runtime cùng delegation được
phép.
--ultracòn yêu cầu năm candidate run read-only chạy song song cùng một verifier. - Công việc CI, production, browser profile và provider bên ngoài có thể cần credential và phát sinh chi phí vận hành.
- Cách gọi Cursor bằng slash là bằng chứng do người dùng xác minh, không phải chứng minh runtime parity đầy đủ.
- Kit release đã cài xác định các mode và workflow reference khả dụng của
ak:fix.
Chứng minh root cause với ak:debug
Điều tra lỗi code và hệ thống một cách có phương pháp, giữ nguyên chuỗi bằng chứng và xác minh mọi correction trước khi tuyên bố thành công.
Test và cải thiện suite với ak:test
Chạy validation cho code hoặc UI, tạo hay tối ưu test suite, audit test yếu và nhận bằng chứng có cấu trúc về kết quả.