Boffin：为 AI 编程代理加上架构约束与验证层

Boffin 是一个面向 AI 编程代理（Cursor、Claude Code、Codex、OpenCode）的「架构约束控制层」。它不取代 AGENTS.md，也不充当静态提示包，而是在代理每次打开一个文件时，按需注入与该文件相关的架构约束，并在编辑完成后要求按变更规模进行验证。项目已在 npm 上以 boffinit 包名发布，并在 Show HN 上以 DuckDB、FastAPI、LangChain 等开源仓库的「引导式重构」作为案例公开佐证。

解决的问题

开发者向 AI 编程代理请求 15 行修复，结果常常拿到一份 500 行的「翻新」。Boffin 把这种现象归因于：代理缺乏对当前文件的局部架构契约认知，也没有强制验证环节。其设计目标是让「昂贵的细节」在合并前显式化，而不是让代理变保守。

与 AGENTS.md 的关键差异

交付方式：AGENTS.md 倾向整库一份静态指令块；Boffin 只把与「正在编辑的文件」相关的约束路由给代理。
验证要求：AGENTS.md 本身不要求验证；Boffin 要求与变更规模成正比的检查。
证据形式：Boffin 附带可复现的案例研究，记录行数变化、测试通过数等具体数字。

已公开的引导式重构案例

DuckDB：+17 / -17 行，8 个测试文件共 2,104 条断言全部通过，分支延续与恢复路径被保留。
FastAPI：+16 / -33 行，49 个测试通过，未改动公开 API。
LangChain：同步/异步边界被保留，4 个测试通过。

作者明确说明，这些是可复现的案例研究，并非对照 A/B 基准测试，因此更适合作为方向性参考而非能力评级。

安装与接入

Boffin 要求 Node.js 18 及以上版本，支持四类宿主：

Cursor：在项目目录下执行 npx boffinit cursor。
Claude Code：通过 /plugin marketplace add MicSm/boffin 与 /plugin install boffin@boffin 安装。
Codex：通过 codex plugin 命令安装，并需在 Codex 内运行一次 /hooks 以授信钩子，否则仅技能可用、自动每会话激活保持关闭。
OpenCode：执行 npx boffinit opencode，通过 opencode.json → .boffin/AGENTS.md 落地常驻指导，也可使用 /boffin、/boffin-review 按需触发。

卸载可通过 npx boffinit cursor uninstall 或 npx boffinit opencode uninstall 完成，仅清理对应宿主的托管文件，共享的 .boffin/packs 与 .boffin/VERSION 会保留。

设计边界

定位不是 lint 也不是 CI 门禁，它在编辑前后介入；不追求速度，框架优先级是「审阅安全」。
不是命令沙箱或安全工具，不隔离进程、不过滤 shell 命令、不限制文件与网络访问。
不替代测试与代码评审，只决定哪些契约值得代理关注、并要求外部检查。
「lite / full / max」三个档位只调节清理力度，不改变正确性下限：信任边界校验、防数据丢失、安全、可访问性等早期正确性阶段与拒绝规则在所有档位下保持一致。

约束本身以可读的版本化 Markdown 形式存放在仓库的 packs/ 目录，并由 GPG 签名，安装时无任何隐藏内容；代理编辑时再由其路由引擎挑选适用于当前文件的规则集。