claude-mem Anti-Pattern Czar基于 Agent 命令与自动扫描器的错误处理反模式系统化治理【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem本文以 claude-mem 仓库中的 Agent 命令anti-pattern-czar.md为主体完整拆解“反模式沙皇”Anti-Pattern Czar这一角色如何配合自动扫描器detect-error-handling-antipatterns.ts对 TypeScript 代码库中的静默失败、空 catch、字符串匹配错误类型等错误处理反模式进行系统性定位、分级与修复。读完本篇你将掌握一套可复制的错误处理治理工作流如何运行检测器、如何解读报告、如何用[ANTI-PATTERN IGNORED]标记申请例外豁免以及如何用关键路径规则保护核心链路不出现“吞错继续”。1. 背景静默失败是如何吃掉开发者的时间的claude-mem 是一个跨会话持久上下文工具它在会话中捕获 Agent 的全部操作用 AI 压缩后再注入未来会话。这类系统的核心资产是「会话数据 → 摘要 → 检索」这条链路其中任何一处被静默吞掉的错误都会直接导致记忆丢失或数据损坏且极难复现。项目的 CHANGELOG.md 中记录了这一治理体系诞生的直接原因8.5.3 版本发布说明中提到「一个过宽的 try-catch 曾因静默吞错导致了一次长达 10 小时的调试」。正是这个事件催生了仓库里两样配套产物自动检测器detect-error-handling-antipatterns.ts一个用 Bun 运行的静态扫描脚本逐行分析src/下的 TypeScript 文件Agent 角色命令anti-pattern-czar.md把「修复反模式」这件事固化为一个有明确流程、明确边界、明确输出格式的标准作业程序SOP供 AI 编码助手按章执行。本文主体即围绕这份 SOP 命令展开并结合扫描器源码解释每个环节背后的实现依据。2. 工作流第一步运行检测器anti-pattern-czar.md定义的第一步是运行检测器bun run scripts/anti-pattern-test/detect-error-handling-antipatterns.ts从 扫描器源码 可以确认其运行边界扫描范围以当前工作目录为项目根递归遍历src/目录只处理.ts文件见findFilesRecursive函数目录排除自动跳过以.开头的隐藏目录以及node_modules、dist、plugin三个目录失败即拦截扫描结束后只要存在任何severity ISSUE的条目脚本会向 stderr 输出❌ FAILED: N error handling anti-patterns must be fixed.并以退出码1结束全部通过则以退出码0结束。这意味着该脚本天然可以挂进 CI 作为硬性门禁。3. 检测器识别哪些反模式源码级清单SOP 命令中提到「统计 CRITICAL、HIGH、MEDIUM 与 APPROVED_OVERRIDE 问题」这些问题的具体定义全部来自扫描器。逐段阅读 detectAntiPatterns 与 analyzeTryCatchBlock 两个函数检测器实际覆盖以下模式类别模式 ID检测目标典型描述EMPTY_CATCHcatch 块内除注释外没有任何内容「错误被静默吞掉用户将浪费数小时调试」NO_LOGGING_IN_CATCHcatch 块内既无logger.*也无console.error/warn、无process.stderr.write、无throw「错误发生时无从可见」PROMISE_EMPTY_CATCH.catch(() {})空 Promise 处理器「错误消失进虚空」PROMISE_CATCH_NO_LOGGING多行.catch()处理器内无任何日志调用「错误被静默吞掉」LARGE_TRY_BLOCKtry 块显著行数超过 10 行「范围过宽多种错误被混在一起处理」GENERIC_CATCHcatch 有参数但不做instanceof Error/.name 等类型判别「所有错误被无差别地同等处理」ERROR_STRING_MATCHING用err.message.includes(...)之类字符串匹配来判定错误类型「脆弱且掩盖真实错误应记录完整错误对象」PARTIAL_ERROR_LOGGING只把err.message传给 logger/console而非完整错误对象「丢失了堆栈、错误类型与全部属性」ERROR_MESSAGE_GUESSING对错误消息做多个\|\|串联的字符串检查来「猜」错误类型「停止猜测记录完整错误对象」CATCH_AND_CONTINUE_CRITICAL_PATH关键路径文件上 catch 后仅记录日志、既不throw也不return/process.exit就继续执行「可能导致静默数据损坏」值得注意的是CATCH_AND_CONTINUE_CRITICAL_PATH的实现细节扫描器先检查 catch 内容是否包含throw若没有再判断是否存在return或process.exit这样的「终止执行」语句只有当 catch 里有日志但不终止执行时才会触发该模式。换句话说扫描器对关键路径的底线是「错误要么可见后终止要么抛出去」与 SOP 命令中「fail loud, not silent」大声失败而不是静默的原则一一对应。检测器输出统一由 formatReport 渲染成两栏报告❌ ISSUES TO FIX逐条列出文件:行号 - 模式ID - 描述⚪ APPROVED OVERRIDES逐条列出豁免理由与代码片段。报告尾部固定附一段「每个 try-catch 必须回答的五个问题」我捕获的是哪个具体错误说出名字给我看能证明该错误确实可能发生的文档为什么这个错误无法被预防catch 块做什么记录后重抛降级回退为什么这个错误不该传播给调用方4. 第二步解读报告并排定优先级SOP 命令要求对检测结果做三件事计数统计 CRITICAL、HIGH、MEDIUM 各级问题与 APPROVED_OVERRIDE 的数量优先关键路径先把落在关键路径文件上的 CRITICAL 问题排到最前归类合并把相似模式如一批PARTIAL_ERROR_LOGGING分组处理。仓库中确实留存了一份真实的治理台账 docs/anti-pattern-cleanup-plan.md当时共132 个反模式待修按文件拆成了逐项打勾的进度清单例如worker-service.ts (36)、SearchManager.ts (28)、SessionStore.ts (18)并规定最终验证必须「运行检测器确认 0 个 issue保留已批准的 override、全部测试通过、提交变更」。这份计划文档是 SOP「按文件逐个击破 每批改完重跑检测器」工作流的一次落地实例。5. 第三步对每个 CRITICAL 问题的四选项决策法这是 SOP 命令的核心方法论。对每一个 CRITICAL 问题要求 Agent 依次完成五个动作a. 先读代码用 Read 工具通读问题代码理解上下文b. 解释问题为什么危险会造成什么样的调试噩梦具体吞掉了什么错误c. 判定正确修法——四选一选项适用场景Option 1补上正确的日志这是真实错误应当被看见Option 2添加[APPROVED OVERRIDE]属于预期/已文档化的行为申请豁免Option 3整个删掉 try-catch错误本就应该向上传播Option 4添加具体错误类型检查只有特定错误才需要被捕获d. 提出修复方案并请求用户批准e. 批准后落地修改。这个决策框架与扫描器的判定逻辑严格对齐例如 Option 3 对应GENERIC_CATCH或LARGE_TRY_BLOCK中「不该 catch」的情形Option 4 直接满足GENERIC_CATCH对instanceof Error/.name 检查的要求Option 1 则消除NO_LOGGING_IN_CATCH与PARTIAL_ERROR_LOGGING且日志参数必须传完整错误对象而非err.message。6.[ANTI-PATTERN IGNORED]豁免体系批准条件与真实案例当 catch 块确实无需或不能记录日志时扫描器支持行内豁免在被标记行或其上一行写上// [ANTI-PATTERN IGNORED]: 具体且技术性的理由扫描器通过正则/\[ANTI-PATTERN IGNORED\]:\s*(.)/i提取理由文本将该条目从ISSUE降级为APPROVED_OVERRIDE并计入报告的「已批准豁免」栏——豁免不会让问题消失只是被显式登记、供后续人工复核报告标题原文即提示「Review reasons for accuracy」。SOP 命令对「什么理由才配得上豁免」给出了硬性标准四条必须同时成立该错误可预期且高频发生例如对可选字段的 JSON 解析打日志会产生过多噪音高频操作路径存在显式的恢复逻辑回退值、重试、优雅降级理由具体且技术性而非「看起来没事」这类模糊表述。命令文档同时给出了正反例对照✅ 好的理由「可选数据字段的 JSON 解析失败属预期情况频率太高不适合打日志」「logger 无法记录自身的失败用 stderr 作为最后手段」「健康检查端口扫描探测空闲端口时连接失败是预期行为」「Git 仓库检测不在 git 目录时失败属预期」❌ 坏的理由「错误不重要」那为什么还要 catch、「偶尔会发生」何时为何、「不打日志也没事」出事时就晚了、「可选的」可选错误同样需要可见性。这些标准不是空话仓库源码里保存着大量按此规范写就的真实豁免。例如 src/utils/logger.ts 中的三处// [ANTI-PATTERN IGNORED]: this is the loggers own file-write failure path — // calling the logger here would recurse into the same failing appendFileSync, // so the error is surfaced via emitDiagnostic to real stderr instead.又如 src/services/worker-service.ts 中的健康探测豁免// [ANTI-PATTERN IGNORED]: health probe — connection refused/timeout IS the // worker not running answer, polled on every status check; logging would // spam. null is the documented recovery value the callers branch on.两条理由都完整覆盖了四条批准标准错误可预期高频、日志会刷屏、有明确的恢复路径stderr 诊断 / 返回 null 供调用方分支、理由技术性强。而 8.5.3 版本的 CHANGELOG.md 记录了该体系建成时的量化成果163 个反模式 → 26 个已批准豁免静默失败减少 84%后续 8.5.4 版本还修复了 ChromaSync 中「连接错误被误判为 collection 不存在」这类由过宽 catch 引出的真实 bug印证了治理的长期价值。7. 关键路径规则核心链路不允许「catch 后继续」SOP 命令对关键路径文件单列了一节铁律绝不在关键路径上批准 override除非有极特殊理由关键路径上的错误必须可见打日志或致命抛出关键路径上「catch 后继续」是被禁止的除非被显式批准拿不准时宁可让它 throw——大声失败不要静默。命令文本中列出的关键路径文件是SDKAgent.ts、GeminiAgent.ts、OpenRouterAgent.ts、SessionStore.ts、worker-service.ts而从 扫描器源码 的CRITICAL_PATHS数组看当前实际生效的名单为const CRITICAL_PATHS [ ClaudeProvider.ts, GeminiProvider.ts, OpenRouterProvider.ts, SessionStore.ts, worker-service.ts ];从源码结构看SDKAgent.ts/OpenRouterAgent.ts与ClaudeProvider.ts/OpenRouterProvider.ts属于同一批 Agent/Provider 模块在不同时期的命名当前仓库中 ClaudeProvider.ts、GeminiProvider.ts、OpenRouterProvider.ts 均位于src/services/worker/下SessionStore.ts 位于src/services/sqlite/下。可以推断该名单随代码重构做过同步更名但语义始终一致凡是负责「AI 摘要生成」与「SQLite 会话持久化」的文件都是记忆数据的咽喉catch 后继续执行意味着可能把损坏的数据写进长期记忆库。检测器通过filePath.includes(cp)做文件名级匹配来判定关键路径这也是为什么重命名文件时需要同步维护这份名单。8. 第四步与收尾小批量推进 标准化输出格式SOP 命令对执行节奏与汇报格式做了模板化约束这是 Agent 工作流可审计性的关键推进节奏一次只修一个或一小批每修完一批立即重跑检测器用「Fixed 3/28 critical issues」这样的口径跟踪进度。单点修复汇报✅ Fixed: src/utils/example.ts:42 Pattern: NO_LOGGING_IN_CATCH Solution: Added logger.error() with context Progress: 3/28 critical issues remaining批次完成汇报重跑检测器并展示新报告。最终统计对比修复前后的 CRITICAL / HIGH / MEDIUM / APPROVED OVERRIDES 数量并在完成时向用户发起下一轮询问「Ready to fix error handling anti-patterns? Ill start with the critical issues.」命令文档末尾还固化了四条元规则先读代码再提方案拿不准就问用户绝不盲批 override要逐个挑战拿不准时优先加日志而不是加豁免增量推进小批量、频繁验证。9. 小结一套可迁移的错误处理治理方法claude-mem 的 Anti-Pattern Czar 体系本质上把「代码评审中最依赖经验的错误处理审查」拆解成了机器可执行的三层结构检测层扫描器十余种模式、关键路径加严、退出码门禁让反模式数量变成可回归的指标决策层SOP 命令四选项修法 豁免四条件 关键路径铁律把「怎么修」收敛为有限决策且每一步要求先读代码、先求批准台账层清理计划 与 CHANGELOG按文件登记 132 项待修清单、逐版本记录 163→26、91 文件 301 项、331 项清零等治理进度使豁免理由长期可审计。如果你在自己的项目中遇到「静默失败难以排查」的问题这套「扫描器 SOP 豁免台账」的组合是值得直接参考的起点先用正则/AST 扫描把反模式计数成指标再用强制的五问清单与四选项决策约束修复过程最后用行内豁免注释保留所有「明知故犯」的技术决策依据。【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考