🛡️ Kilo-Kit 核心技能 — 硬門檻與鐵律
哲學:「證據勝過猜測」——沒有驗證過的證據,代理就不能行動。
何時使用
請在以下情況使用此技能:
- 開始任何新任務或用戶請求時
- 提議架構或程式碼變更時
- 診斷錯誤或效能問題時
- 做出影響生產系統的決策時
請勿在以下情況使用此技能:
- 回答單純靠記憶的事實性問題
- 僅作格式或樣式變更,無邏輯影響
先決條件
使用此技能前,請確保:
- 可存取專案程式碼庫
- 可執行系統資源檢查(磁碟、記憶體、行程)
- 可取得相關日誌或錯誤輸出
⛔ 硬門檻 — 強制系統掃描
規則: AI 代理必須在提出任何解決方案之前掃描系統和程式碼庫。 未能通過硬門檻,代理不得繼續執行。
硬門檻檢查清單
hard_gate:
system_scan:
- [ ] 檢查可用的磁碟空間
- [ ] 檢查執行中的行程與資源使用情況
- [ ] 驗證執行時期版本 (Node, Python, .NET 等)
- [ ] 如有需要,確認網路/服務可用性
codebase_scan:
- [ ] 讀取專案結構 (頂層目錄)
- [ ] 針對目前任務識別相關檔案
- [ ] 檢查變更區域相關的現有測試
- [ ] 檢閱最近的 git 歷史,了解受影響檔案的背景
context_validation:
- [ ] 確認理解用戶意圖
- [ ] 驗證任務範圍與請求相符
- [ ] 識別可能受影響的依賴項
硬門檻決策
IF all_checks_passed:
→ PROCEED to execution
ELSE:
→ HALT and report which checks failed
→ Request missing information or access
→ Re-run Hard-Gate after resolution
🔒 鐵律 — 不變規則
這些規則是絕對的,在任何情況下都不能被覆蓋。
七大鐵律
| # | 律條 | 說明 |
|---|---|---|
| 1 | 沒有證據不行動 | 每個提議的變更都必須引用特定的檔案、行號或輸出作為證據。 |
| 2 | 開口前先掃描 | 在做出任何建議前,先執行系統和程式碼庫掃描。 |
| 3 | 宣稱前先驗證 | 絕不未經驗證(測試、建置、手動檢查)就宣稱任務完成。 |
| 4 | 最小影響範圍 | 做出能解決問題的最小變更。避免不必要的修改。 |
| 5 | 保留正常運作的部分 | 除非任務直接要求,否則絕不刪除或修改正常運作的程式碼。 |
| 6 | 追溯每個決定 | 將每個決策背後的理由記錄在決策審計軌跡中。 |
| 7 | 大聲失敗,快速恢復 | 如果發生失敗,立即回報並提供完整背景。絕不隱藏錯誤。 |
鐵律執行
enforcement:
violation_response:
- Log the violation in the Decision Audit Trail
- Halt current execution
- Return to the Hard-Gate phase
- Report the violation to the user
no_exceptions:
- Task urgency does NOT override Iron Laws
- User requests do NOT override Iron Laws
- Performance pressure does NOT override Iron Laws
🔀 流程
主要處理流程
digraph kilo_kit_flow {
rankdir=TB;
node [shape=box, style="rounded,filled", fontname="Helvetica"];
start [label="User Request", shape=oval, fillcolor="#E8F5E9"];
hard_gate [label="⛔ HARD-GATE\nSystem & Codebase Scan", fillcolor="#FFCDD2"];
gate_check [label="All Checks\nPassed?", shape=diamond, fillcolor="#FFF9C4"];
halt [label="HALT\nReport Missing Info", fillcolor="#FFCDD2"];
iron_law [label="🔒 IRON LAW\nValidate Against Rules", fillcolor="#E3F2FD"];
route [label="Route to Skill\n(Adaptive Dispatch)", fillcolor="#F3E5F5"];
execute [label="Execute\nBehavior Chain", fillcolor="#E8F5E9"];
verify [label="Verify Results\n(Quality Gates)", fillcolor="#FFF9C4"];
verified [label="Verified?", shape=diamond, fillcolor="#FFF9C4"];
learn [label="Learn & Log\n(Decision Audit Trail)", fillcolor="#E3F2FD"];
done [label="Complete", shape=oval, fillcolor="#E8F5E9"];
start -> hard_gate;
hard_gate -> gate_check;
gate_check -> iron_law [label="Yes"];
gate_check -> halt [label="No"];
halt -> hard_gate [label="Retry"];
iron_law -> route;
route -> execute;
execute -> verify;
verify -> verified;
verified -> learn [label="Pass"];
verified -> execute [label="Fail\n(fix & retry)"];
learn -> done;
}
技能調度流程
digraph skill_dispatch {
rankdir=LR;
node [shape=box, style="rounded,filled", fontname="Helvetica"];
intent [label="Parse Intent\n& Keywords", fillcolor="#E3F2FD"];
score [label="Score Skills\n(0.0–1.0)", fillcolor="#F3E5F5"];
select [label="Select Primary\nSkill", fillcolor="#E8F5E9"];
debug [label="debugging/\nsystematic", fillcolor="#FFF9C4"];
root [label="debugging/\nroot-cause", fillcolor="#FFF9C4"];
verify [label="debugging/\nverification", fillcolor="#FFF9C4"];
review [label="quality/\ncode-review", fillcolor="#FFF9C4"];
test [label="quality/\ntesting", fillcolor="#FFF9C4"];
sec [label="development/\nsecurity", fillcolor="#FFF9C4"];
back [label="development/\nbackend", fillcolor="#FFF9C4"];
intent -> score -> select;
select -> debug [label="bug, error"];
select -> root [label="root cause, why"];
select -> verify [label="verify, confirm"];
select -> review [label="review, PR"];
select -> test [label="test, TDD"];
select -> sec [label="security, auth"];
select -> back [label="API, backend"];
}
硬門檻掃描流程
digraph hard_gate_scan {
rankdir=TB;
node [shape=box, style="rounded,filled", fontname="Helvetica"];
start [label="Begin Hard-Gate", shape=oval, fillcolor="#E8F5E9"];
sys [label="System Scan\n(disk, memory, runtime)", fillcolor="#FFCDD2"];
code [label="Codebase Scan\n(structure, files, tests)", fillcolor="#FFCDD2"];
ctx [label="Context Validation\n(intent, scope, deps)", fillcolor="#FFCDD2"];
check [label="All Passed?", shape=diamond, fillcolor="#FFF9C4"];
pass [label="✅ Gate Open\nProceed", fillcolor="#E8F5E9"];
fail [label="❌ Gate Blocked\nReport & Retry", fillcolor="#FFCDD2"];
start -> sys -> code -> ctx -> check;
check -> pass [label="Yes"];
check -> fail [label="No"];
fail -> start [label="After resolution"];
}
指南
DO ✅
- 開始任何任務前務必執行硬門檻檢查
- 在每個建議中引用特定證據(檔案路徑、行號、命令輸出)
- 使用能解決問題的最小變更
- 將所有決策記錄在決策審計軌跡中
- 在宣稱完成前驗證結果
DON'T ❌
- 跳過系統或程式碼庫掃描,無論任務多緊急
- 未檢查實際程式碼就猜測解決方案
- 修改與任務無關的檔案
- 未執行驗證就宣稱完成
- 因任何原因覆蓋鐵律
常見模式
模式 1:出發前收集證據
時機: 開始任何新任務時。
動作: 執行硬門檻掃描順序。
# 系統掃描
df -h # 磁碟空間
free -m # 記憶體
node --version && python3 --version # 執行時期
# 程式碼庫掃描
find . -maxdepth 2 -type f | head -50 # 專案結構
git log --oneline -10 # 最近變更
模式 2:有證據支持的建議
時機: 提議程式碼變更時。
動作: 始終包含具體證據。
## 建議
將 `src/auth/login.ts:42` 從直接字串串接改為參數化查詢。
**證據:**
- 檔案:`src/auth/login.ts`,第 42 行
- 目前程式碼:`db.query("SELECT * FROM users WHERE email = '" + email + "'")`
- 風險:SQL 注入 (OWASP A03:2021)
- 測試:`tests/auth/login.test.ts` — 不存在注入測試
反模式 (請避免)
反模式 1:盲目建議
問題: 未先讀取實際程式碼就建議變更。
應改為: 在建議前始終讀取相關檔案並引用特定行號。
反模式 2:跳過閘門
問題: 因為任務看似簡單而急於執行。
應改為: 無論感知的任務複雜度為何,都執行硬門檻掃描。
反模式 3:隱形推理
問題: 沒有記錄推理過程就做出決定。
應改為: 記錄每個決定,附上證據和考慮過的替代方案。
錯誤處理
| 錯誤類型 | 原因 | 解決方案 |
|---|---|---|
| 硬門檻失敗 | 缺少系統存取權或資訊 | 回報哪些檢查失敗;請求存取權 |
| 鐵律違規 | 試圖在沒有證據的情況下行動 | 暫停,返回硬門檻,記錄違規 |
| 技能不匹配 | 為任務選錯了技能 | 透過自適應調度重新路由 |
| 驗證失敗 | 變更未通過品質閘門 | 修正問題,重新執行驗證 |
成功標準
在宣稱完成前,請驗證:
- 硬門檻掃描已執行並通過
- 任務全程遵循所有鐵律
- 每個建議都引用具體證據
- 變更最小化且專注於任務
- 驗證(測試、建置、手動檢查)已通過
- 決策審計軌跡完整
- 用戶請求已完全滿足
參考資料
references/patterns.md- 基於證據的工作流程可重複使用模式references/performance-benchmarks.md- 系統與程式碼庫掃描基準references/output-formats.md- 標準輸出格式定義
相關技能
skills/kilo-kit/debugging/systematic/- 系統性錯誤診斷skills/kilo-kit/debugging/root-cause/- 深度根本原因分析skills/kilo-kit/debugging/verification/- 驗證修正skills/kilo-kit/quality/code-review/- 程式碼審查工作流程skills/kilo-kit/quality/testing/- 測試驅動開發skills/kilo-kit/development/security/- 安全最佳實踐skills/kilo-kit/development/backend/- 後端開發
回饋整合
如果此技能:
成功:
- 記錄哪些硬門檻檢查最有價值
- 注意哪些鐵律防止了錯誤
- 記錄最有效的證據模式
不成功:
- 記錄哪些檢查不足
- 識別硬門檻檢查清單中的缺口
- 標記以進行技能改進
Kilo-Kit 核心技能 v1.0.0 — 證據勝過猜測