improve：用强模型审计代码库，生成便宜模型可执行的计划
给 Agent Skills 用户审计代码库并产出计划，执行交给便宜模型，合并仍由人掌控。
GitHub shadcn/improve 更新 2026-11-12 分支 main 星标 10.9K 分叉 443
Agent Skills 代码审计 实现计划 GitHub Issues Git worktree

🧭 决策指南

为什么现在热： 无法从材料判断

适合，如果你

  • 你希望强模型负责审计和规格编写，再让便宜模型执行计划。
    README 正文开头说明：使用最强模型理解代码库、判断优先级并写规格，再交给便宜模型执行。
  • 你的 Agent 支持 Agent Skills 格式，并需要 `/improve` 的代码库审计。
    Install 章节写明：Works in any agent that supports Agent Skills format.
  • 你需要用 `execute` 在隔离 git worktree 中执行并复核计划。
    Closing the loop 章节说明：`execute` 会派发 cheaper executor、复核 diff，并返回 approve、revision 或 block。
  • 你想把计划交给人或其他 Agent，并用 GitHub Issues 保存任务上下文。
    README 说明计划是 plain markdown，`--issues` 会发布包含相同自包含正文的 GitHub issues。

不适合，如果你

  • 你需要工具直接修改当前工作树或直接提交源代码。
    Hard rules 明确：不会修改源代码，只写入 `plans/`；执行器只编辑 disposable worktrees，合并由用户完成。
  • 你需要工具运行会改变工作树的命令。
    Hard rules 明确：Never runs commands that mutate your working tree。
  • 你期待安装包提供现成版本或发布产物。
    项目元数据显示版本发布为 0 个，最新版本为 No releases。

前置条件

  • 安装命令为 `npx skills add shadcn/improve`。
  • 运行环境需要支持 Agent Skills format。
  • 执行计划时需要可用的 git worktree，因为 `execute` 使用 isolated git worktree。
  • 计划会写入 `plans/`；执行器会在 disposable worktrees 中编辑。

第一步命令（README 原文）

npx skills add shadcn/improve

要注意

  • `execute` 的 approve 不会自动合并，合并决定仍由你完成。
    Closing the loop 章节写明：Verdict 为 approve，merging stays your call。
  • 计划针对写入时的 git commit，执行前会做机械 drift check。
    What makes the plans executable 章节说明每个计划会记录生成时的 git commit，并要求执行器先检查漂移。
  • `reconcile` 会处理 DONE、BLOCKED、漂移计划以及已独立修复的 finding。
    Closing the loop 章节列出了 `reconcile` 的四类处理行为。
  • `/improve deep` 会检查 every package、every category，成本范围高于 `/improve quick`。
    Usage 章节将 `quick` 定义为 cheap pass，将 `deep` 定义为 exhaustive。

替代方案

  • 直接将 `plans/001-*.md` 交给其他 Agent：你不需要 `execute` 的隔离 worktree 和 tech-lead 式复核，只想让其他 Agent 按 plain markdown 计划执行时更合适。
    How to use
  • 手动编写实现计划：你不需要 `/improve` 的九类审计、finding 优先级或 `reconcile` backlog 管理时更合适。
    How it works

材料未说明

  • README 没有说明支持哪些具体模型、模型版本或 Agent 产品。
  • README 没有说明运行所需的 Node.js、npm 或 npx 版本。
  • README 没有给出不同代码库规模下的运行时间、token 消耗或费用。
  • README 没有说明九类审计的并发数、失败重试策略或权限要求。
  • README 没有说明 `execute` 使用的 cheaper executor 具体模型和配置。
  • README 没有说明 Windows、macOS、Linux 等操作系统的兼容范围。
  • README 没有提供 releases，因此无法从发布记录判断版本稳定性。

💡 深度解析

6
适合 我正在准备 Pull Request，只想审计当前分支相对基线的变更，不希望为整个仓库付出完整审计成本；improve 能满足吗？
适合读者： 准备提交 Pull Request、只想检查当前分支变更而不扫描整个仓库的软件工程师

适合，因为 README 提供了专门的 branch 模式，用于把审计范围限制在当前分支的变更。

  • 命令 /improve branch 的定义是 “audit only what the current branch changes”，与 PR 前检查的范围约束直接对应。
  • 它仍沿用发现、证据复核、优先级排序和计划生成流程，因此结果不只是一次聊天建议，而可以落入 plans/。
  • 如果发现已经明确，也可以使用 /improve plan <description> 跳过完整审计，直接编写一个事项的实施规格。
  • 计划执行并不等于自动合并：execute 会在隔离 worktree 中审查实现，但 README 明确保留合并决定给用户。
  • Usage: `/improve branch` — “audit only what the current branch changes”
  • Usage: `/improve plan <description>` — “skip the audit, spec one thing”
  • How to use: “Before a PR, `/improve branch` does the same thing scoped to just what your branch changes”
  • Closing the loop: “Merging stays up to you”
/improve branch
材料未说明：README 未说明 branch 模式如何确定比较基线、是否支持未提交变更，以及是否会读取合并目标分支。；README 未提供 branch 审计对大型 PR 或跨 package 变更的性能数据。
适合 我现在使用支持 Agent Skills 格式的代理工具，并要求计划能被人工或其他代理直接接手；improve 的安装和交接方式符合这个约束吗？
适合读者： 使用支持 Agent Skills 格式的代理工具、希望让人工或其他代理接手 Markdown 计划的开发者

适合，因为项目要求宿主支持 Agent Skills 格式，而输出是普通 Markdown，不把计划锁定在某个代理平台。

  • 安装命令是 npx skills add shadcn/improve，README 明确写着 “Works in any agent that supports Agent Skills format”。
  • 计划写入 plans/，每个文件包含自包含上下文、精确路径、当前代码摘录、仓库惯例和已验证命令，因此其他代理不需要读取原始顾问会话。
  • --issues 可以把同一份自包含计划发布为 GitHub Issue，人工或其他代理可从已有位置继续执行。
  • 限制是 README 没有给出具体宿主的兼容矩阵；实际安装、工具权限和交互体验取决于宿主代理是否完整支持该格式。
  • Install: `npx skills add shadcn/improve`
  • Install: “Works in any agent that supports Agent Skills format”
  • What makes the plans executable: “Self-contained”
  • Closing the loop: “--issues publishes plans as GitHub issues”
npx skills add shadcn/improve
材料未说明：README 未列出 Claude Code、Cursor 或其他具体宿主的兼容性和版本要求。；README 未说明 Agent Skills 宿主必须提供哪些工具权限才能运行完整流程。
适合 我想把修复计划交给一个从未看过仓库、能力较弱的执行代理；improve 生成的计划能否把上下文和边界说清楚，避免它自行扩大改动？
适合读者： 想把计划交给不熟悉仓库、能力较弱的执行代理来实现的项目维护者

适合，因为计划被设计成给“最弱的合理执行者”使用，并明确限制执行代理的判断空间。

  • 计划会内联精确文件路径、当前代码摘录、仓库约定、示例文件和已验证命令，不要求执行者依赖顾问会话中的隐含上下文。
  • 每一步都有命令和预期输出，完成标准可机器检查；这让执行代理能按验证门推进，而不是自行猜测是否成功。
  • 计划还包含 out-of-scope 列表和 STOP 条件，遇到现实与计划不一致时应停止并报告，而不是扩大范围。
  • execute 会在隔离 worktree 中执行并复查 diff；项目支持 approve、revision 或 block，但最终合并仍由维护者决定。
  • What makes the plans executable: “Plans are written for the weakest plausible executor”
  • What makes the plans executable: “Self-contained” and “Verification gates”
  • What makes the plans executable: “Hard boundaries”
  • Closing the loop: “Verdict: approve ... send back for revision ... or block”
/improve execute <plan>
材料未说明：README 未说明执行代理使用的具体模型、工具权限、最大执行轮数或两轮 revision 的具体判定规则。；README 未证明复杂业务规则、跨服务契约或运维知识也能被计划完整表达。
适合 我想让最强模型负责理解代码库、筛选高价值问题和写计划，再让更便宜的模型执行；这个工作流是否适合我控制 AI 开发成本？
适合读者： 希望用高能力模型做判断、再交给低成本模型执行的个人开发者或小型工程团队

适合，因为项目明确把高能力模型用于审计和规划，把较便宜的模型用于执行，且本身不直接修改源码。

  • 典型流程是 /improve 生成发现和 plans/ 计划，再由其他代理执行；计划是普通 Markdown，可交给任意代理或人工。
  • /improve execute <plan> 会在隔离 Git worktree 中调度 cheaper executor，并依据计划复核 diff、完成条件和范围。
  • 每个计划包含文件路径、代码上下文、验证命令、完成标准和 STOP 条件，降低小模型自行判断的空间。
  • 但合并仍由用户负责，项目也没有提供不同模型的成本、质量或速度基准，因此节省幅度无法从 README 确认。
  • README: “use your most capable model ... and hand execution to cheaper models”
  • README: “The skill never implements anything itself. The plan is the product.”
  • How to use: “It dispatches a cheaper model in an isolated worktree”
  • What makes the plans executable: “Verification gates” and “Hard boundaries”
/improve quick
材料未说明：README 未说明支持哪些具体模型、模型调用价格、上下文窗口或实际成本下降比例。；README 未提供较弱执行模型的成功率、返工率或任务规模上限。
视情况 我需要检查安全问题，但要求审计工具不能直接改源码、不能复制秘密值，并且要能记录误报；improve 是否符合这些安全约束？
适合读者： 需要审计安全问题、同时要求工具不改源码且不泄露凭据的仓库维护者

视情况，符合只读审计和凭据处理约束，但不能单独承担完整的安全验证责任。

  • Hard rules 明确规定它不直接修改源代码，只写入 plans/；执行代理也只在 disposable worktree 中编辑，合并由用户负责。
  • 对秘密值，项目规定不复现实际内容，只描述位置和凭据类型，并建议轮换；这适合需要避免敏感信息进入报告的流程。
  • /improve security 可运行聚焦安全审计，Vet 阶段会重新检查引用位置，删除误报并记录拒绝理由。
  • 但 README 明确指出模型驱动发现不能替代专门的静态分析器、依赖漏洞扫描器、动态安全测试或人工复核，因此安全结论不能只依赖 improve。
  • Usage: `/improve security` — “focused audit”
  • Hard rules: “Never modifies source code itself”
  • Hard rules: “Never reproduces secret values”
  • How it works — Vet: “false positives get dropped ... rejections get recorded”
  • Usage limitations: “cannot replace dedicated static analyzers ... dynamic security testing”
/improve security
材料未说明：README 未说明安全审计覆盖哪些漏洞类型、是否集成具体 CVE 数据库或依赖扫描器。；README 未说明宿主代理的日志、上下文缓存或错误报告是否可能暴露敏感路径和环境信息。
视情况 我维护一个包含多个 package 的历史代码库，想覆盖正确性、安全、性能、测试和技术债；应该用 improve 做全量审计吗？
适合读者： 维护包含多个 package、需要系统审计历史代码库的技术负责人

视情况，适合做证据驱动的审计和计划整理，但不应把它当成完整的静态分析、安全扫描或性能测试平台。

  • deep 会覆盖每个 package 和每个审计类别；Audit 阶段并行检查正确性、安全、性能、测试覆盖、技术债、依赖迁移、DX、文档和方向。
  • Recon 会识别技术栈、约定以及准确的 build/test/lint 命令，并把它们写入计划的验证门；存在 ADR、PRD、CONTEXT.md、DESIGN.md 或 PRODUCT.md 时也会读取。
  • Vet 阶段会重新阅读每条 file:line 证据，删除误报并记录拒绝理由，这比直接接受扫描结果更适合历史仓库。
  • 但大型仓库运行 deep 可能消耗较多模型调用；README 也明确说它不能替代专门扫描器、动态测试、压测或人工架构评审。
  • Usage: `/improve deep` — “exhaustive: every package, every category”
  • How it works — Audit: “nine categories”
  • How it works — Recon: “exact build/test/lint commands” and intent documents
  • How it works — Vet: “false positives get dropped, wrong attributions get corrected”
  • Usage limitations: “cannot replace dedicated static analyzers ... dynamic security testing, performance load testing, or human architecture review”
/improve quick
材料未说明：README 未说明仓库规模、package 数量、支持的编程语言或 deep 审计的耗时上限。；README 未提供审计召回率、误报率或与现有扫描器的对比数据。

✨ 核心亮点

  • 用强模型审计代码库，把执行交给更便宜的模型
  • 每个计划含命令、预期输出与可机检完成标准
  • `execute` 在隔离 git worktree 中复核执行结果
  • 仅写入 `plans/`，不会直接修改源代码

🔧 工程化

  • `/improve` 审计代码库并生成优先级计划
  • `/improve execute` 派发便宜执行器并复核 diff
  • `reconcile` 检查 DONE、BLOCKED 与漂移计划
  • `--issues` 将自包含计划发布为 GitHub Issues

⚠️ 风险

  • README 明确不会直接实现代码，只写入 `plans/`
  • `execute` 最多返工 2 轮，仍可能进入 block
  • 执行器只在 disposable worktree 修改，合并仍由你负责
  • 仓库只有 5 位贡献者且没有发布版本

👥 适合谁？

  • 需要审计大型代码库并拆分计划的 Agent Skills 用户
  • 使用 `/improve branch` 检查分支变更的开发团队
  • 希望让便宜模型执行、人工掌握合并权的团队