autoharness 是專為 Claude Code 設計的免守護程式（Daemon-free）自學習 Skill 層外掛，能從真實工程對話中自動提煉技能並持續優化。它不依賴離線基準測試（Benchmark）或獨立審查迴圈，而是依據模型在後續會話中的實際採納率（Adherence）動態決定技能的留存、整併與歸檔。全系統採用 Python 3.11 原生零依賴實作，只管理自身產出的技能，嚴格隔離使用者既有資產。
autoharness 聚焦解決 AI Agent 技能層長期膨脹與難以維護的難題。傳統自適應框架多仰賴昂貴的離線基準評測（Held-out Benchmark）或常駐後台計時器（Daemon），而 autoharness 選擇直接從使用者的真實會話中提煉技能，並以模型在後續實戰中的採納頻率作為留存依據。
系統設計秉持零侵入性原則：宿主既有的名稱與描述檢索機制維持不變，僅在每次會話啟動時主動於 Context 前端注入結構化技能索引。整個流程完全於本地端透過 Python 3.11 原生腳本驅動，無需外部常駐行程。
當遭遇相似情境時，反思器會主動將新教訓合併至既有技能，而非無限制堆疊相似文件；每項技能皆隨附不可竄改的追溯帳本，完整記錄決策依據與會話片段。
autoharness 完全由 Python 實作且零第三方依賴。系統 PATH 中的 python3 必須為 3.11 或以上版本；若環境誤用 macOS Xcode 內建之 Python 3.9.6，所有 Hook 與 MCP Server 將自動關閉並於 stderr 輸出警示。
| 依賴項目 | 最低版本 | 用途說明 |
|---|---|---|
Python 3.11+ |
>= 3.11.0 | 執行 Hook 捕捉、Promoter 驗證與 MCP Server，零第三方 pip 套件 |
Claude Code |
支援 Plugin 體系 | 提供外掛市集管理與 Session 生命週期 Hook 注入介面 |
於系統終端機執行更新，先重新整理遠端市集索引，再更新特定外掛並重啟 Claude Code：
/plugin uninstall autoharness@autoharness 僅停止外掛攔截器，提煉產出的技能與帳本仍保留於 .claude/skills/ 與 .claude/autoharness/。欲完全清除可手動刪除該目錄；所有由本外掛產生的技能皆帶有 .ledger.jsonl 標記，不會影響使用者自行撰寫之任何檔案。
autoharness 將技能自學習管線切分為職責分明的六大組件，外加帳本追蹤與手動觸發指令。各組件透過 Claude Code 的外掛 Hook 攔截器串接，在不阻塞前台對話的前提下於背景完成提煉、驗證與生命週期淘汰。
所有參數均可透過系統環境變數或 .env 覆寫，數值於外掛載入時動態讀取：
| 環境變數名稱 | 預設值 | 功能說明與調優建議 |
|---|---|---|
AUTOHARNESS_REFLECT_EVERY_N |
50 |
工具調用次數門檻。對話較為瑣碎或除錯密集時可調低至 30。 |
AUTOHARNESS_CONSOLIDATE_EVERY_N |
250 |
全庫整併巡檢週期。大型專案累積大量微技能時可縮短為 150。 |
AUTOHARNESS_MATURITY_PROJECT |
100 |
專案級新技能試用保護期請求數。保護期內免受容量淘汰機制影響。 |
AUTOHARNESS_CAPACITY_PROJECT |
50 |
專案技能容量上限。達到上限後優先淘汰非保護期內使用率最低者。 |
AUTOHARNESS_CAPACITY_GLOBAL |
20 |
跨專案全域技能容量上限，保持全域 Context 精簡高質。 |
AUTOHARNESS_INDEX_DESC_MAX_CHARS |
60 |
會話啟動注入之單條技能描述長度上限，避免佔用過多初始 Context。 |
autoharness 擺脫傳統 Agent 自適應框架必須常駐背景守護行程（Daemon）與離線基準評測的包袱。以下彙整自 Tigerless Labs 官方設計規範與實務運行提煉出的七項關鍵架構原則：
拋棄計時器排程，改以嚴格的工具調用次數為計數基準（預設每 50 次調用觸發一次）。避免空轉並精準對齊實際程式碼修改強度。
架構規範 · CAP & Hook評估自學習技能的指標非離線 Benchmark，而是模型在後續實戰中是否主動遵循。零調用的技能會隨機會率下降而自動被冷落。
設計哲學 · Adherence Metric帳本計數器精細記錄行為：真正的 Skill 調用（Load）權重最高，單純的檔案目錄檢視（View）不灌水，而修補（Patch）能重置維護指標。
狀態管理 · MNG 機制新提煉技能擁有專案級 100 次請求或全域 300 次請求的試用保護期（Maturity Probation）。保護期內不受容量上限與低採納率淘汰機制清除。
生命週期 · Probation Policy當技能庫超過容量（預設專案 50 個 / 全域 20 個），淘汰的技能會被移動至 .archive/ 目錄保留完整歷史與帳本，絕不直接 rm。
安全設計 · Archive Strategy專案技能存於 .claude/skills/，全域通用技能存於 ~/.claude/skills/。兩者容量獨立計算，背景分析器嚴禁跨層越權混雜。
目錄結構 · State Isolationautoharness 只管理自身帶有 .ledger.jsonl 標記的自動產生物件。使用者自行手動編寫的自訂技能完全受到寫入豁免與保護。
合規保證 · Self-Authored Immunity注入 Context 的技能描述強制截斷為 60 字元以內。將最關鍵的觸發條件放在前 40 字元，避免重要語意在 Context 壓縮時遺失。
調優實務 · IDX Truncation以下展示 Claude Code 結合 autoharness 的真實對話進程：會話啟動時自動注入現存技能索引，工程編程累積達到 50 次調用門檻時觸發背景唯讀分析，提煉出專案技能經 Promoter 嚴格校驗後原子化落盤，並於後續會話精準命中與修補。
stripe-webhook-verify
我將依照該規範更新 Redis 冪等鎖與指數退避演算法，並加入 Alembic 資料庫防護。
✓ SKILL.md body line count: 21 lines (limit: ≤25 lines)
✓ description character count: 58 chars (limit: ≤1024 chars)
✓ evidence slice stored: references/evidence-20261002-patch.md
✓ atomic rename: .claude/skills/stripe-webhook-verify/SKILL.md
✓ appended ledger: .claude/skills/stripe-webhook-verify/.ledger.jsonl
Claude ›
已完成指數退避與 409 冪等處理，測試均已通過。
autoharness 背景分析器已同步將本次冪等最佳實踐修補回 stripe-webhook-verify 技能。
You › claude --resume
· stripe-webhook-verify: Stripe 簽章校驗與重試指數退避冪等快取 (loads: 13, patched: 1)
傳統手動編寫 Skill 常面臨「寫完即遺忘」或「重複造輪子」的問題。autoharness 透過背景唯讀分析器與唯一的寫入門戶 Promoter，在維持零延遲體感的同時，確保每一個落地技能皆附帶可回溯的 .ledger.jsonl 歷史與證據切片。
當既有技能需要微調時，分析器優先選擇 patch 現有規則而非盲目新增，徹底杜絕了提示詞庫隨時間無限膨脹的惡性循環。
python3 --version 低於 3.11，Claude Code 外掛攔截器將於背景靜默失敗。請確保 PATH 中 Homebrew 或 pyenv 之 Python 3.11+ 優先級高於系統預設。
AUTOHARNESS_INDEX_SUSPENDED=1。
SKILL.md 本體不得超過 25 行。過於冗長或結構複雜的流程會被直接拒絕入庫。
~/.claude/skills/）會影響所有專案的對話 Context。提煉分析器預設僅落盤至專案層，手動提升為全域前務必審查其通用性與潛在副作用。
autoharness 提供彈性鉤子與環境變數，方便開發者將技能自學習能力與既有的 CI/CD 流程、通知中心及外部自動化管線深層整合。
1. 桌面與 Webhook 事件通知。設定 AUTOHARNESS_NOTIFY=webhook 與 AUTOHARNESS_NOTIFY_CMD，在背景分析器提煉出新技能或完成全庫整併時，自動發送系統推播或通知至 Slack/Discord 頻道。
2. Fork Carrier 快取預熱機制。在高並發會話環境中，將 AUTOHARNESS_CARRIER=fork 啟用程序級分叉載入，大幅縮短每次會話啟動時讀取檔案系統索引與歷程的延遲至毫秒級。
3. 提取 LED 證據切片合成測試套件。利用 references/evidence-*.md 中記錄的真實對話輸入與失敗情境，作為離線單元測試與 Regression Test 的合成輸入素材。
4. 定期手動整併與清理。隨時執行 /learn compact 觸發 Curator 的全庫去重邏輯，檢視相似度高於 85% 的微技能並將其合併為結構化規則。
① README.md——架構總覽、Hook 生命週期與配置規格完整清單。
② agents/reflector.md——背景提煉分析器之唯讀 Intent 生成原理與 Prompt 規範。
③ agents/curator.md——週期性全庫去重整併演算法與快照備份機制。