Claude 代码安全指导插件实用指南
开发速度已经超越了用于审查代码的机制。工程师带着编程智能体干活，一个下午就能动十几个文件、做跨文件重构、然后提交代码。围绕这些工作的审查防线基本还停在老地方：CI里的静态分析、按计划运行的依赖扫描、等到pull request阶段才让人工审阅diff。这些防线假设写代码是最慢的步骤——但那个假设已经不再成立，代价就是延迟。一段有漏洞的查询在被任何人检查之前就已经写完、提交、推送了。最终把它揪出来的工具，描述的是作者几个小时前完成的工作，而作者早就不去想那回事了。这些防线本身没错，只是涌进来的diff数量已经超出了它们原本能处理的范围，而且问题发现得越晚，修复成本就越高。
Anthropic 的 security-guidance 插件把第一道检查搬到了对话窗口本身。Claude 写代码，插件审查改动，审查结果直接在同一轮对话里返回给 Claude。不需要调用什么命令，也不用记什么指令。我花了一个晚上在小仓库里把它搭起来，然后试着让它的三个层面各自触发——用专门写来“踩雷”的代码来检验。这篇东西就是记录这个过程，以及如何判断每个层面是真的在跑、而不只是装上了。
插件做什么
这个插件基于 Claude Code 的生命周期钩子（lifecycle hooks）构建。它注册了 SessionStart 来初始化 Python 环境，UserPromptSubmit 来获取本轮对话开始前的 git 基线，对编辑工具注册 PostToolUse 做模式检查，Stop 做轮次结束时的审查，以及对 Bash 工具（过滤出 git commit 和 git push 时）注册 PostToolUse 做深度审查。如果你对这些事件名不熟，可以查 hooks 参考文档了解每个事件何时触发。
这些注册带来了三个层面，深度和开销逐层递增。第一层是字符串和正则匹配，不调用模型，所以免费且即时。
它覆盖了动态执行（如 eval 和 os.system）、不安全的反序列化（如 pickle）、DOM 注入（如 .innerHTML = 和 dangerouslySetInnerHTML），以及对 .github/workflows/ 下的编辑——这类操作可能悄然授予仓库权限。这些是你在编写任何自定义规则之前就获得的内置检查。你在 security-patterns.json 中自定义的规则也会在同一趟检测中运行，后面会详述。
Layer 2 在每个回合结束时，对工作树进行差异比较，并将结果发送给一个单独的 Claude 调用，该调用使用仅限安全的提示。它覆盖了字符串匹配无法检测的内容：注入、服务端请求伪造（SSRF）、弱加密、权限绕过。它后台运行，不会延迟 Claude 的回复，每回合最多可检查 30 个变更文件。
Layer 3 会在 Claude 通过 Bash 工具执行 git commit 或 git push 时触发。这个审查者会读取周围代码（包括调用者和数据清洗函数），然后判断问题是否真实。每滚动小时最多进行 20 次审查。
有一点值得尽早跟团队说明，因为这是他们最容易误解的地方：这些层都不会阻断任何操作。它们只是发现问题并交给 Claude，由它在对话中修复。什么都不会被阻止。如果你想强制停止，需要自己通过 PreToolUse 钩子或 CI 检查来实现。
前提条件
- Claude Code 2.1.144 或更高版本（如果你用 OpenRouter，请拉到文末看说明）
- Python 3.10 或更高版本，以及一个 git 仓库
- 一个值得攻击的仓库：下面的所有检查对空目录都没有意义，所以我首先构建了一个小型的 Python 服务，包含几个文件：一个数据层、几个路由存根、以及一个前端文件，这样 JavaScript 模式就有了落脚点。基线故意保持干净，这样当 Claude 按请求添加不安全的内容时，对比就会显而易见。然后执行
git init和首次提交。Layer 2 比较工作树，Layer 3 仅在git commit或git push时触发，所以如果没有仓库，三层检查中的两层会安静地不做任何事。
Claude Code 安全指导插件实用指南
安装安全指导插件
- 在 Claude Code 会话中运行以下命令，从 Anthropic 安装官方插件：
/plugin install security-guidance@claude-plugins-official - 安装时会询问作用域（scope）。选择「为该仓库的所有协作者安装」，这样会自动写入
.claude/settings.json并启用该插件。 - 然后应用到当前会话：
/reload-plugins
确认 settings.json 文件已出现在项目根目录下的 .claude 文件夹中。
注意：如果机器上尚未注册插件市场，请先执行以下命令添加，再重试安装：
/plugin marketplace add anthropics/claude-plugins-official
仓库中会留下什么
安装程序会写入三个文件中的一个。另外两个需要你手动编写——因为插件不了解你的代码库，不会自动生成它们。完整的工作示例（包括这些代码片段来源的演示仓库）可在 [GitHub] 上找到。
这些文件是配置，理应放在所保护的代码旁边。对它们进行版本管理意味着规则变更会像其他代码改动一样，在代码审查中体现出来。
你的威胁模型，用通俗英语描述
两个基于模型的审查看文件会加载 .claude/claude-security-guidance.md 作为额外上下文，与内置的漏洞检查清单一起工作。没有专门的领域特定语言（DSL）。编写规则时，就像在跟新人解释一样写清楚即可。
这个文件承载了通用扫描器无法获得的知识。例如，org_id 并非通用概念——它是你特有的数据模式，审核者之所以知道它，完全是因为你写下来了。
免费层的自定义模式
Anthropic 的安全插件在 patterns.py 中内置了检测模式。你可以用以下命令找到该文件：
find ~/.claude/plugins -path '*security-guidance/hooks/patterns.py'
你可以在 .claude/security-patterns.json 中添加自己的自定义模式。这些会注入免费的第1层检查中，因此无需额外模型成本即可即时运行。
插件也支持 .yaml、.yml 和 .json 格式，使用相同的模式。YAML 需要单独安装 PyYAML，而 JSON 在任何标准 Python 环境中都能直接使用。
每一层能看到什么
理解分层机制很重要，这能帮你决定要为哪些部分付费。