claude-code-mistake-guards：为 Claude Code 提供基于真实错误日志的钩子与发版检查防护

hadiux0295/claude-code-mistake-guards · 7 Claude Code guards (hooks + pre-ship checks), each born from a real logged agent mistake, with tests that prove they block. Plus 50 of the mistakes in English.

GitHub原文发布未知首次收录 2026-11-02上架 2026-11-05 07:03

☆ 收藏查看项目 ↗

ELI5：它是什么，解决什么问题

该项目面向 Claude Code，提供 3 个钩子和 4 个发版前检查脚本，用于在命令执行、MCP 保存、对话结束以及上架、生成、添加记录、场景渲染等环节拦截已知易错操作。每条规则都源自一次真实记录过的智能体失误，并配有测试，用于验证该拦截的规则会拦截、不该拦截会放行。项目同时提供 MISTAKES.md，用英文列出 50 条失误记录；完整 300+ 条记录仅有韩文版。

# Claude Code # hooks # 护栏 # Agent 工具调用 # 规则拦截

核心能力与快速开始

★ 0 · Python

能做什么: 提供 7 个防护规则：guard_bash.py 拦截会命中自身 shell 的 pkill -f、pgrep -f 等待循环等命令，并可选拦截裸 git pull、指定站点访问和上传目录布局问题；guard_short_save.py 拦截过短的整条记录覆盖保存；stop_check.py 在 Stop 阶段拦截已记录过的错误判断表述；ship_check.py、gen_gate.py、add_unique.py、baseline_check.py 分别覆盖上架前检查、生成批次事实与兜底答案、重复记录、场景精灵脚底落地检查。防护规则会在自身出现缺陷时放行并输出到 stderr，支持用显式覆盖令牌放行，Stop 钩子只拦截一次，以避免循环。
适用场景: 适用于日常使用 Claude Code 处理真实项目的开发者，尤其是希望把反复出现的智能体失误（如误杀自身 shell、虚报测试结果、错误覆盖保存、把搜索结论或流量当作事实）变成可执行拦截规则的团队；也可作为编写同类 BASH 或流程钩子的参考实现。
项目形态: 可直接使用的工具
部署方式: 插件方式：通过 /plugin marketplace add hadiux0295/claude-code-mistake-guards 与 /plugin install synura-mistake-guards@synuracore 安装，零配置，仅启用自杀防护；复制方式：克隆仓库后把 hooks/*.py 与 tools/*.py 拷入项目，并合并 settings.json 的 hooks 配置，使用前需按注释设置各文件顶部的值。
主要依赖: Python 3；baseline_check.py 需要 Pillow；ship_check.py 的视频检查需要 ffmpeg。README 称已在 Claude Code 2.1.310 和 2.1.316 上测试。
使用限制: 每条规则只检查能到达它的内容：guard_bash.py 看不到 $VARIABLES 或 ssh 命令内的上传路径，也无法检查运行前值未知的 pkill -f "$PATTERN"；较旧 procps 与 BusyBox 没有 -A；heredoc 写入文件的文本不按命令处理；ship_check.py 不读取 PDF 或图片内的文字；stop_check.py 按词模式匹配，只能捕获重复出现的已知错误说法，不能发现一般性错误判断。项目作者明确说明代码按原样提供，使用前应在自己的环境测试；许可证为 MIT，但未说明是否适合特定商用场景。
许可证: MIT
最近推送: 2026-11-01 12:18

核对 README 依据 ↗

资料检查：2026-11-02 07:00 · 卡片整理：2026-11-05 07:00
卡片由 AI 根据仓库资料整理，未进行安装或运行验证

职业应用

程序员

在 Claude Code 中通过钩子拦截已知易错的命令执行（如 pkill -f 误杀自身 shell、共享工作区裸 git pull），并在发版前用检查脚本校验标签、禁用词、预览视频等，减少智能体重复失误。

查看内容依据

7 Claude Code guards (hooks + pre-ship checks), each born from a real logged agent mistake, with tests that prove they block.

官方使用入口 ↗

由 AI 根据来源材料整理，未进行安装或运行验证

相似资源

Catpilot AI Guardrails：面向 AI 编程智能体与智能体框架的安全技能集

该项目以 Agent Skills 格式提供面向 AI 编程智能体、AI 辅助开发者以及团队自建智能体框架的安全指导技能，仓库中包含两个技能：面向非开发者 AI 辅助构建场景的 catpilot-safe-building（八个通俗检查点，覆盖提示中的数据、访问与身份、托管、共享、密钥与凭据、第三方服务、不可信输入以及何时求助人类）和面向真实代码库编码智能体的 catpilot-security-core（九个工程组件，涉及云 CLI、数据库、本地 shell、Docker、硬编码密钥、密钥生命周期、供应链、PII 与测试数据、安全编码模式）。此外还提供 Agent 框架相关的标准指导、shell 工具凭据门禁 hook（secret_gate.py）以及重试、定时运行、委派和自修改的参考规则，并附带一个只读参考 MCP 服务器用于查询检查点指导、构建计划检查、常见应用安全起点和已批准策略。项目声明其技能属于建议性指导，只有两个 Claude Code PreToolUse hook（Bash 凭据拦截与 Write/Edit 私钥块拦截）构成实际执行控制。

Context Mode：为 AI 编程代理优化上下文窗口的 MCP 服务器

Context Mode 是一个 MCP 服务器，用于解决 AI 编程代理的上下文窗口占用问题。它通过沙箱工具把原始工具输出隔离在上下文窗口之外（官方称 315 KB 可降至 5.4 KB，约 98% 缩减），将文件编辑、git 操作、任务、错误和用户决策等会话事件记录到 SQLite 并用 FTS5 索引，压缩对话后通过 BM25 检索只取回相关内容以保持会话连续性；同时通过 MCP + hooks 在 17 个平台上强制实施路由，并倡导让模型编写脚本来分析数据（Think in Code）而非把数据读入上下文。仓库为 TypeScript 实现，采用 ELv2 许可，支持 Claude Code、Gemini CLI、VS Code Copilot、JetBrains Copilot、GitHub Copilot CLI 等多种客户端。

Agent Skills：面向 AI Agent 的可复用技能、工作者契约与生命周期钩子合集

该项目是作者用于 AI Agent 工作的共享工具箱与实践场，收录可复用能力（skills）、有边界的 agent 工作者、persona 契约以及生命周期 hooks。仓库以 SKILL.md 作为能力契约、run.sh 作为稳定入口、sanity.sh 作为本地验证，并包含 monitor-skill-health 等维护巡检与 triage 报告流程。作者明确说明这是公开的蓝图与研究场，而非开箱即用的 SDK，部分路径依赖私有基础设施（记忆服务、浏览器绑定、模型网关、凭据等），新克隆环境下部分命令需要先做环境配置。

claude-code-config：个人 Claude Code 配置仓库（agents、skills、hooks 与设置参考）

这是作者个人 Claude Code 配置的版本管理仓库，直接在 ~/.claude/ 下用 Git 追踪，登记树与 Claude Code 实际读取的配置为同一份文件。内容涵盖用户级记忆（CLAUDE.md）、skills（含针对其他项目运行的技能与操作 Claude Code 自身配置的技能）、按文件匹配触发的 language/project rules、由 settings.json 中 hooks 块挂载的 shell 脚本、settings.json 以及说明运行时路径排除原因的 .gitignore。仓库明确说明它不是入门模板：直接覆盖克隆会冲掉你自己的设置、记忆与凭据，建议只阅读并取用适合自己工作流的部分。另有一个仓库外前置条件——code-* 审查技能会把结果写入所运行项目的根目录 .issues/，依赖 ~/.gitignore（通过 core.excludesfile）中含 .issues 使其不被提交，缺失时技能会检查失败并拒绝写入。

这是基于来源内容整理的摘要。原文链接失效后，本页摘要和讨论仍会保留。