Footgun

Footgun

你的 AI Agent 知道 API 如何运作。Footgun 会告诉它 API 如何出问题。

Footgun 是一个带日期、经过验证的陷阱注册库，记录了文档未提及的问题：悄然弃用、隐性限制，以及保存后却不起作用的设置。你的编码 Agent 会在编写代码前查询它。访问 getfootgun.com 浏览所有陷阱。

有帮助吗？

在 17 项涉及近期 API 变更的编码任务中，每项任务运行 5 次，使用 Footgun 时，Claude Code 首次尝试就正确完成代码的比例为 82%，不使用时为 52%；每个可用结果的成本降低了 18%。对于模型已经熟悉的旧版 API，效果没有区别。方法和完整结果见 getfootgun.com/benchmark。

我们在 200 个 AI 构建的应用中发现了什么

200 个应用中有 89 个仍在使用为 Node 20 构建的 GitHub Actions，而 GitHub 现在使用 Node 24 运行它们。93 个应用至少存在一个现已导致或即将导致故障的问题，这里只统计了经人工对照真实代码检查的规则。方法和结果见 getfootgun.com/scan。

在 Claude Code 中安装

/plugin marketplace add getfootgun/footgun
/plugin install footgun@footgun

无需账户即可查询和提交陷阱。提交的陷阱会先对照官方来源进行核实，然后才会向其他人显示。如需确认陷阱，请在 getfootgun.com/account 创建 API 密钥，并在插件提示时输入。

该插件还会添加 /footgun:scan，可在你的计算机上检查项目，找出与你使用的确切软件包版本相关的已知陷阱。你的代码不会离开本机；只会发送规则下载请求和发现问题的匿名计数。关闭插件设置 share_learnings，即可停止发送计数以及提交 Agent 学到的修复方法。设置 auto_context 会在每个会话开始时添加一条简短提示，说明这些陷阱。默认开启；设为 false 即可关闭。

命令行

cli/ 包含同一款扫描器的命令行版本，发布在 npm 上，名称为 @getfootgun/footgun：npx @getfootgun/footgun scan [path]（Node 20 或更高版本）。添加 --json 可输出机器可读的结果，添加 --fail-on breaks 可使 CI 任务失败。

启动检查优先显示，列在“Before you launch”下：例如浏览器代码中泄露密钥，或 Supabase 表关闭了 RLS 等会泄露数据或增加费用的问题。不在代码中、而是在控制面板里的问题会列为检查项，使用相应软件包时需自行检查。

扫描完成后会打印一枚带日期的 README 徽章：只有在扫描结果除启动提醒外没有其他内容时，才会显示“no known API traps”；否则显示“scanned”。

使用 Pro 或 Team 密钥时，scan --watch 会将项目添加到 Footgun Watch。它会在 Projects 页面列出与你使用的确切软件包版本匹配的新陷阱和变更陷阱。它会发送项目名称、每个软件包文件所在的文件夹、软件包名称和版本，以及每项发现对应的陷阱、文件和行号，不会发送代码。参见 getfootgun.com/docs。

在 GitHub Actions 中，请使用 GetFootgun/scan-action。它会在任务摘要中列出发现的问题，可在遇到 breaks 或 will-break 时使任务失败；设置 watch: "true" 后，还会将项目发送至 Footgun Watch。

其他 MCP 客户端

claude mcp add --transport http footgun https://getfootgun.com/api/mcp

对于 Cursor、Codex 和其他客户端，请将其指向 https://getfootgun.com/api/mcp（streamable HTTP）。添加请求头 Authorization: Bearer <your key>，即可提交并确认陷阱。

数据

data/traps/<tool>/<trap>.json 保存了所有公开且经过验证的陷阱：症状、原因、修复方法、最近核实日期以及可信度评分。data/providers.json 列出了涵盖的工具。数据从 getfootgun.com 导出，并会随着陷阱的新增、确认或退役而更新。

许可证

data/ 中的陷阱数据采用 CC BY 4.0 许可。请注明“Footgun，getfootgun.com”。插件文件采用 MIT 许可（参见 LICENSE）。