justinstimatze/plancheck

# plancheck _三思而后行。_ [](LICENSE) plancheck 可以预测 AI 编程代理会遗漏哪些文件。它通过运行实现冲刺（一个用于探索和原型化更改的 LLM 代理）、编译器验证（`go build -overlay`）和引用图查询，来找出计划中未涵盖的文件。 仅支持 Go。引用图查询需要 [defn](https://github.com/justinstimatze/defn)。 **在 4 个 Go 仓库的 180 个任务中。53 个任务得到改善 (29%)，1 个任务变差 (0.6%)。** ^{[单次运行基准测试](#methodology)} ## 三种模式 ### `plancheck check ` — 编码前 LLM 代理会阅读计划文件，使用工具（定义查找、影响分析、grep）探索代码库，然后编写原型实现。它所触及的文件将成为预测结果。结合编译器验证和结构信号，这会生成一份该计划可能遗漏的文件的排名列表。 **在 cli/cli 上召回率提升了 +17.7pp（50 个任务，单次运行）。** 预计成本约为 ~$0.05-0.15/任务（Sonnet 定价，未实际测量）。 ### `plancheck review [base_ref]` — 编码后 分析你已经修改过的文件，并指出你可能遗漏的内容。使用编译器探测（添加虚拟结构体字段，检查哪些地方会报错）、引用图调用者和 git 共同修改模式。LLM 零成本，几秒内即可运行。 ``` plancheck review # uncommitted changes plancheck review HEAD~3 # last 3 commits ``` ### `suggest` MCP 工具 — 编码中 在通过 PostToolUse 钩子编辑 Go 文件后自动触发。“考虑到你目前触及的文件，还有哪些需要更改？”与 `review` 使用相同的信号，以 MCP 工具调用的形式交付。LLM 零成本，即时返回。 ## 需要 [defn](https://github.com/justinstimatze/defn) plancheck 需要一个 [defn](https://github.com/justinstimatze/defn) 数据库来进行引用图查询。请先在你的 Go 项目中运行 `defn init .`。 ## 安装 ``` go install github.com/justinstimatze/defn@latest go install github.com/justinstimatze/plancheck@latest ``` ## 配置 (Claude Code) ``` cd your-go-project defn init . # create reference graph plancheck setup # configure MCP server, hooks, skill (once per user) plancheck doctor # verify everything ``` `plancheck setup` 会配置： - **MCP 服务器** — 在所有会话中提供 check_plan、suggest 及其他工具 - **门禁钩子** — 在退出计划模式前强制检查计划质量 - **建议钩子** — 在编辑 Go 文件后显示经编译器验证的建议 - **Check-plan 技能** — 基于角色的计划验证 - **Git pre-commit 钩子** — 在每次提交前运行 `go vet`、简短测试和 `plancheck review` 配置会写入指向 `~/go/bin/plancheck`（稳定的 `go install` 路径）的钩子和 MCP 配置。这意味着运行 `go install github.com/justinstimatze/plancheck@latest` 会直接原地升级——无需重新运行配置。项目本地的 `.mcp.json` 文件应遵循相同的模式：优先使用 `~/go/bin/defn` 和 `~/go/bin/plancheck`，而不是本地开发构建的产物，否则过时的二进制文件会在版本升级后继续残留。 ## 信号来源 | 信号 | 置信度 | 来源 | 成本 | |--------|------------|--------|------| | 编译器 (`go build -overlay`) | 非常高 | 探测导出的符号，找到报错的调用方 | 免费 | | 引用图 (defn) | 高 | 已修改定义的调用方、被调用方、构造函数 | 免费 | | Git 共同修改 | 中等 | 历史上经常一起更改的文件 | 免费 | | 实现冲刺 | 中等 | LLM 编写原型，通过数据流发现文件 | 预计约 ~$0.05-0.15 | | 探索信号 | 中低 | 冲刺代理主动调查过的文件 | 免费 | _置信度层级是根据基准测试观察估算的，未经过正式测量。冲刺成本是根据 Sonnet token 定价估算的；成本测量工具已计划开发但尚未完成。_ ## 跨仓库结果 | 仓库 | 任务数 | 召回率提升 | F1 提升 | 改善 | 变差 | |------|-------|------------|---------|----------|----------| | cli/cli | 50 | **+17.7pp** | **+5.2pp** | 21 (42%) | 0 | | revive | 45 | +10.5pp | +6.1pp | 12 (27%) | 0 | | nats-server | 37 | +7.5pp | ~0pp | 9 (24%) | 0 | | helm | 48 | +5.8pp | -1.6pp | 11 (23%) | 1 | **方法论说明：** - 结果来自使用 `scripts/system_benchmark.py` 进行的单次基准测试运行，未在多次试验中取平均值。请将其视为单点估算。 - 仓库是为兼容 defn（Go，大小合理）而选择的，并非随机抽样。 - “改善/变差”统计的是每个任务的召回率变化。如果 plancheck 的建议提高了召回率，则任务被“改善”；如果降低了召回率，则被“变差”。 - helm 的 F1 值为负，意味着 plancheck 找到了更多的文件，但同时在该仓库中建议了更多错误的文件——这可能是由于其扁平的包结构产生了噪声较大的结构信号。 - 快速模式（仅建议，无 LLM）：在 cli/cli 上召回率提升 +7.9pp，12/50 得到改善。尚未进行跨仓库基准测试。 **术语表：** - **Recall** (召回率)：plancheck 建议的、实际需要更改的文件的比例。越高 = 遗漏的文件越少。 - **Precision** (精确率)：plancheck 的建议中正确部分的比例。越高 = 误报越少。 - **F1**：召回率和精确率的调和平均数。平衡了发现文件与不推荐错误文件的能力。 - **pp** (百分点)：绝对变化量。“+17.7pp recall”表示召回率从例如 40% 上升到了 57.7%。 - **Recall lift / F1 lift**：与基线（没有 plancheck 的代理）相比，plancheck 对该指标的提升程度。 ## CLI 命令 | 命令 | 描述 | |---------|-------------| | `plancheck check ` | 完整的计划验证（冲刺 + 结构） | | `plancheck review [base_ref]` | 审查 git 更改以寻找遗漏的文件 | | `plancheck simulate [cwd] ...` | 针对引用图模拟变异（forward、cascade、backward-scout、replay 模式） | | `plancheck forecast ` | 对计划进行蒙特卡洛结果预测 | | `plancheck history` | 显示项目最近的计划检查历史 | | `plancheck stats` | 跨所有项目的聚合统计 | | `plancheck outcome` | 记录已检查计划的结果 | | `plancheck reflection` | 记录执行后的反思 | | `plancheck setup` | 配置 Claude Code 集成 | | `plancheck doctor` | 验证配置 | | `plancheck disable` / `enable` | 全局禁用或重新启用门禁钩子 | ## 配置项 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `PLANCHECK_NO_SPIKE` | *(未设置)* | 设为 `1` 可跳过 LLM 冲刺（仅保留结构信号） | | `PLANCHECK_SPIKE_MODEL` | `claude-sonnet-4-6` | 用于实现冲刺的模型 | | `PLANCHECK_SPIKE_DEBUG` | *(未设置)* | 设为 `1` 可将冲刺工具调用打印到 stderr | | `PLANCHECK_JSON` | *(未设置)* | 设为 `1` 可让 `simulate` 和 `forecast` 输出 JSON | ## 许可证 [Apache-2.0](LICENSE)

标签：AI编程助手, DevTools, EVTX分析, Git集成, Golang, Go语言, MCP, SOC Prime, Sonnet, 云安全监控, 人工智能, 代码审查, 代码审查工具, 代码搜索, 代码缺失检测, 代码补全, 依赖图分析, 参考图, 增量构建, 威胁情报, 安全编程, 实现原型, 开发工具, 开发者工具, 影响分析, 数据管道, 日志审计, 用户模式Hook绕过, 程序破解, 编译器验证, 网络安全研究, 覆盖度分析, 软件工程, 重构, 静态分析, 预测模型