soplint：AI Agent 紀律 Linter（「悔過書制度」開源工具）（2026-06-11）
🔗 GitHub：https://github.com/zaxardery8011-design/soplint 🔗 FB 貼文：https://www.facebook.com/groups/1224997379198346/permalink/1319036503127766/（Claude Taiwan 社團） 平台：GitHub repo（技術版）+ Facebook 社群貼文（故事版）｜ 作者：韓瑞晏（zaxardery8011-design）｜ 分類：知識管理工具
維度 1：定性（基本資料）
- 平台：雙來源 —— ① GitHub repo
zaxardery8011-design/soplint（技術文件型）② Facebook「Claude Taiwan」社團貼文（社群貼文型，作者自述） - URL：見上方兩連結
- 作者：韓瑞晏（FB 顯示名）/ zaxardery8011-design（GitHub）。自述「跑了一個個人 AI agent 一整年」，並先前發過「會自己指揮 AI 軍團的 AI 主腦」貼文（同一系統的延續）
- 發布日期：FB 貼文約 2026-06-10（讀取時顯示「21 小時前」）；repo 同期開源
- 互動數據：FB 貼文 326 讚 / 多則留言（留言含「那天你把自己刪了我就相信你成功了」「天網不遠了」等調侃，1 則認真提問配備、1 則質疑「AI 寫悔過書」的對齊邏輯）
- 內容類型：技術文件型（repo）+ 社群貼文型（FB），雙層互補
- 可信度評估：中偏高。技術面 README 結構完整、機制具體可驗證（JSONL schema / PowerShell AST / cron checks），非空泛宣稱；故事面為作者第一人稱行銷敘事（誇飾語氣「半夜自己加班」「會自己省錢」需折算），但底層機制與 repo 一致，可交叉驗證。作者一年實戰 + 開源可審視程式碼 → 比純口頭分享可信度高。
維度 2：讀取記錄
- 讀取方式：repo → WebFetch（README 全文問答）；FB → Chrome MCP navigate + read_page（accessibility tree，已登入）
- 內容完整性：完整。repo README 三大機制 + 技術棧 + 目錄結構 + 設計哲學齊全；FB 貼文正文 12 段全讀到（ref_843–864）+ 作者留言確認開源連結 = soplint repo
- 讀取限制：①
get_page_text首次抓到錯誤元素（FB 推薦欄的 TZLTH 自家「習得性無助」貼文），改用 read_page accessibility tree 才取得正確貼文正文 —— 已修正，無推斷成分 ② repo 未逐檔讀取程式碼（checks/ rules/ hooks/ lib/ 內部實作未展開），機制描述以 README 自述為準，標注：細部演算法為README 宣稱非逐行驗證
維度 3：核心概念五欄比較
| 概念 | A 是什麼 | B 解決什麼問題 | C 我們目前做法 | D 來源做法 | 比較結論 |
|---|---|---|---|---|---|
| 信念變更審計軌跡（Belief Revision Audit Trail，「悔過書」） | Agent 每次推翻先前判斷，寫一筆結構化 JSONL：from_belief/to_belief/trigger（受控 enum 非自由文字）/confidence_shift。檔案外置 → 缺檔可被 lint 偵測 |
AI 最危險的失敗：偷偷改口還裝沒事（silent contradiction）；prompt 指令可被無聲忽略，但缺少的 log 檔抓得到 | RCF 決策記錄（為什麼這樣改）+ audit-log.md（改善追溯）+ reflection-log。有「為何變更」但為人讀 Markdown 散文，無結構化欄位、無受控 enum、無「缺檔即違規」的 lint | 結構化 JSONL + 受控 enum trigger + 外置檔 + lint 檢查存在性 | A：高；B：可用；C：改善（概念已有，缺結構化+自動檢查存在性）；D：部分採（借鑒「外置可 lint」原則，不照搬 JSONL 全套） |
| 每日紀律檢查（Daily Discipline Checks，cron/CI lint） | 四個自動檢查：decision_propagation（政策決策有沒有傳到操作指令）/belief_revision_audit（審計軌跡有在寫）/memory_frontmatter（記憶檔有必填中繼資料）/index_health（索引過大或重複偵測） |
長時間運行系統的「政策漂移」——行為逐漸退回舊模式、決策悄悄失效 | stop-quality-hook.py（每回合 IMP 掃描+staleness）+ query-gate-hook.py（PreToolUse）+ 規則盤點 SKILL（手動，>90天觸發）+ 整理知識庫 Step 7.5 lint（手動/月頻）。多為每回合 hook 或手動 SKILL，無「每日自動 CI lint 套件」 | cron/CI 每日自動跑一組機械式檢查 | A：高；B：可用；C：改善（機制散落且偏手動）；D：部分採（decision_propagation=部門同步/Source-of-Truth 三步協議可自動 lint；index_health=CLAUDE.md 行數膨脹偵測） |
| 行動前閘門（Pre-Action Gate，pretool-guard.ps1） | Hook 在工具執行前解析 PowerShell 指令 AST，套用 Deny 規則（硬禁止，如禁止 daemon 重生）+ Novelty Gate（建新工具前必須先確認已掃過既有工具） | 防止 agent 重複造輪子、執行危險操作 | query-gate-hook.py（PreToolUse，_pending.flag 攔截）+ RCF-082（建 SKILL 第一輪全讀會碰的資料檔）+ 新建檔前 Grep 確認無重複定義（📝 模式） | AST 解析 PowerShell + Deny + Novelty Gate | A：高；B：驗證現有做法；C：保留（概念已覆蓋：query-gate + RCF-082 Novelty Gate + Grep 前置）；D：不採（不換 PowerShell 重寫，現有 Python hook 已等效） |
| 成本路由（任務難度→模型） | 簡單活自動判斷「不用出動貴的 AI」丟給本機免費小模型，難的才派最強模型；一個月帳單差很多 | 降低長時間運行的 token 成本 | agent路由 SKILL + Codex 雙軌路由評估（tool-inventory Section 六-B）+ 月底 IMP 雙視角對辯 | 自動 free-local-model fallback（需本機小模型基建） | A：中；B：可參考；C：保留（Claude+Codex 雙軌已足）；D：不採（1 人工作室導入本機小模型基建成本>效益） |
| 「疤痕組織編碼化」設計哲學（scar tissue codified） | 每個檢查都因「某事已經失敗過」而存在 = 已知失敗模式的回歸測試套件，非通用對齊方案。核心洞察：學到教訓寫進 memory 還不夠，必須持續測試它，把 hope 變成可量測的 regression signal | 防止「已知問題被遺忘、下次再犯」 | improvements.md（每個 IMP = 踩過的坑）+ CLAUDE-detail.md（13 類前車之鑑）+ 每條 HARD STOP 都源於失敗。哲學完全一致，但 HQ 的「測試」是 agent 讀的散文規則，非持續執行的回歸測試 | 把教訓變成「持續執行的 lint 回歸測試」 | A：高（最高相關）；B：驗證現有做法 + 補充缺口；C：改善（哲學一致，缺「持續自動驗證」執行層）；D：部分採（機械式可自動的 lint 借鑒，語意式維持人工） |
維度 4：可採用點（具體行動）
- 【開發部/DEV + 策略部/STR】機械式 lint 補進 stop-quality-hook.py 或新 lint 腳本：借鑒 soplint 四檢查中「機械可靠」的子集 —— ①
index_health：CLAUDE.md 行數膨脹/重複章節自動偵測（目前 80 行靠手動封存）②decision_propagation：主 CLAUDE.md HARD STOP 修改後，掃描部門 CLAUDE.md / Source-of-Truth 是否同步（目前靠人記三步協議）→ 補強現有自動化、非新架構 → 難度：中 → P3 - 【知識庫/KM】RCF / 改善追溯加「信念變更」結構化欄位：在 RCF 模板或 audit-log 改善追溯格式中，補一個輕量結構化區塊（from→to→trigger→信心變化），讓「為什麼改口」可被機器掃描（呼應 belief_revision_audit「外置可 lint」原則，不照搬 JSONL）→ 難度：低 → P3
- 【內容部/CNT + 社群部/SOC】「AI 員工會自己寫悔過書」Threads/電子報素材：FB 貼文 326 讚的爆款敘事結構（24 小時加班 / 自己省錢 / 寫悔過書）可轉化為「我如何管理我的 AI 員工」職涯數位力內容（呼應 @peter B1 職涯垂直 AI 內容 + W6 AI 員工教學素材）→ 難度：中 → P3
維度 5：明確不採用
- 整套 soplint（PowerShell 7 框架）導入 —— 不採用原因：HQ 已有 Python hooks（query-gate-hook.py / stop-quality-hook.py / knowledge-hook.py），導入整套 PowerShell 獨立框架 = 重複建設 + 雙語言維護成本；正確做法是借鑒概念補進現有 Python hook，非換框架
- pretool-guard Novelty Gate 重寫 —— 不採用原因：HQ 的 RCF-082（建 SKILL 第一輪全讀資料檔）+ 📝 模式 Grep 前置確認無重複，已是同等概念的等效實作，無須重寫
- 本機免費小模型成本路由 —— 不採用原因：需本機 LLM 基建（Ollama 等）+ 路由邏輯維護，1 人工作室規模 Claude+Codex 雙軌已覆蓋，基建成本 > 省下的 token 成本
維度 6：整體對比判斷
- 與現有系統的關係：驗證現有做法 + 補充缺口。soplint 是一位獨立開發者跑一年 agent 後得出的結論，與 TZLTH-HQ 的核心哲學（每條 HARD STOP = 踩過的坑、improvements.md = 失敗記錄、RCF = 為何這樣改）獨立地高度一致 → 強力外部驗證 HQ 路線正確。同時精準點出 HQ 真實缺口：規則齊全（HARD STOP/RCF/IMP 三層完備），但「持續自動驗證規則仍被遵守」這層偏薄弱（規則盤點 >90 天、stop-hook 每回合、Tim 親自追問）。
- 與既有分析的連結：① 2026-04-27 @zarqarwi AI 治理（憲法/ADR/Skill/Memory + git hooks + daily scanner）—— soplint 正是 zarqarwi「daily scanner / governance-lint.sh」的產品化實作 ② 2026-04-28 @shareuhack（錯誤閾值/規則老化）→ 已促成 RCF-015 + 季度盤點 Step 2.5a ③ 2026-06-10 Agent 學習迴路自動化缺口（當時結論：全自動計次屬語意分類、低價值不建）—— soplint 提供關鍵新角度：不是自動計次（語意，不可靠），而是自動檢查檔案存在/結構/索引大小（機械，可靠）。這為先前「關閉」的缺口開了一道窄縫：機械式 lint（檔案存在、frontmatter、索引大小）確實值得自動化，與語意式 IMP 計次的不可靠性不同。
- 最有價值的一點：把「學到的教訓」從靜態散文規則升級為持續執行的回歸測試——hope → measurable regression signal。HQ 缺的不是規則，是規則的自動驗證層。
- 最需要注意的風險：別被故事行銷帶偏去導入整套框架；真正該做的是借鑒「機械式 lint」概念補進現有 Python hook（低成本高槓桿），而非換 PowerShell。
- 整體評分：★★★★☆（高價值參考）。獨立外部驗證 HQ 哲學 + 精準點出自動驗證缺口 + 為已關閉的「自動化缺口」議題提供可靠的機械式切角；扣半星因整套工具不直接導入，價值在概念借鑒。
維度 7：立即行動（0–3 條）
本次無立即執行的系統修改（採用點均為 P3，需走步驟九 Tim 確認後進 tasks.md）。已完成：完整八維分析存檔（維度 8 三步）。
維度 8（確認）
- Step A condensed entry 已寫入：
references/知識管理工具.md✅ - Step B 完整八維分析已寫入：本檔 ✅
- Step C index 已更新：
analyses/README.md+analyses/topic-index.md✅