shadcn/improve

shadcn/improve 快速入门

shadcn 出品——用最强模型做代码审计，让便宜模型执行修改，大幅降低 AI 编码成本

一、产品介绍

shadcn/improve 是由 shadcn（shadcn/ui 的创作者）于 2026 年 6 月发布的开源 AI 代码审计与改进工具。它的核心创新是”分层模型策略”：用最强的 AI 模型（如 Claude Opus）审计代码库并生成详细的改进计划，然后用便宜的模型（如 Claude Haiku）按计划执行修改。

这种设计解决了 AI 编码的两大痛点——成本和质量：你不需要为每一次代码修改都支付顶级模型的费用，只在”思考”阶段用贵的，“执行”阶段用便宜的——据实测，相比全程用 Opus 可节省 60%-80% 的 API 费用。

核心能力

improve 支持 9 类并行审计，覆盖代码质量的完整链路：

它不是一个独立 CLI 工具，而是以 Agent Skill 形式运行，依赖宿主 Agent（如 Claude Code）。在 Agent 中通过 /improve 斜杠命令唤醒，交互式选择发现的问题，生成自包含的改进计划。

安全设计

improve 有三条硬规则，写在 README 最显眼的位置：

• 从不修改源码：只写 plans/ 目录下的计划文件，不碰代码
• 从不运行变更命令：只读分析，不执行 git commit 或 npm install
• 从不复现 secret 值：检测到 API Key、Token 等敏感值时只标记位置，不输出明文

适合谁？不适合谁？

适合：有大量遗留代码需要重构的团队、希望引入 AI 编码但担心成本的开发者、需要定期代码质量审计的开源项目维护者。

不适合：全新项目（没有代码可审计）、对成本完全不敏感的团队、纯 Windows 环境用户（improve 依赖 git worktree，不支持 Windows 原生）。

二、安装上手

准备工作

在安装之前，请确保你具备以下条件：

1. 宿主 Agent：安装并配置好 Claude Code 或其他支持 Agent Skills 的 Agent
2. Node.js 18+：node -v 确认版本（npx 命令会用到，即使不手动运行也确保环境就绪）
3. LLM API Key：推荐 Anthropic API Key —— 审计用 Claude Opus 4.5（$15/M output），执行用 Claude Haiku 4.5（$1.25/M output）。也支持 OpenAI 模型
4. 目标代码库：建议是 Git 仓库，在干净状态下运行（便于回滚不满意的修改）
5. API 配额：大型代码库（100K+ 行）首次全库审计可能消耗 $2-5 的 API 费用，确保账户余额充足

安装

在宿主 Agent 中执行一行命令：

npx skills add shadcn/improve

这条命令会将 improve 作为 Skill 注册到你的 Agent 中。安装完成后，在 Agent 对话中输入 /improve 即可唤醒。

配置 API Key

首次运行 /improve 时，Agent 会提示你配置 LLM API Key。按提示设置环境变量即可：

export ANTHROPIC_API_KEY="sk-ant-xxx"

你可以在 Agent 的配置文件中永久写入这个环境变量，避免每次重新设置。

如果使用 OpenAI 模型做执行层，额外配置：

export OPENAI_API_KEY="sk-xxx"

模型选择建议

三、核心用法

3.1 基础审计

在 Agent 对话中，进入目标项目的根目录，输入：

/improve

improve 会启动 9 类审计流程。这个过程可能需要数分钟（取决于代码库大小），但设计上采用了 vet 机制来降低误报：subagent 先过一遍报出所有发现，然后 advisor 重新读取每个引用位置，过滤掉不实的问题并记录拒绝理由，避免下次重复误报。

3.2 审查改进计划

审计完成后，improve 会生成一份交互式的改进计划。每条计划都是自包含的：

• 包含完整的文件路径和代码片段
• 每步附 expected output 命令（验证修改是否成功）
• 含 STOP 条件（如果便宜模型跑偏了，自动停）
• stamp git commit 做漂移检测（执行前打 commit，后续对比确保修改符合预期）

你可以在 Agent 中逐条确认或跳过。确认后，计划被打包成纯 Markdown 文件存入 plans/ 目录——这意味着计划可以跨 Agent 移交，不绑定当前会话。

3.3 执行改进

确认计划后，执行修改：

/improve execute

Agent 会使用配置的低成本模型（如 Haiku）按计划逐条执行修改。由于是”按图索骥”而非”自由发挥”，便宜模型完全胜任。

执行完成后，用 git diff 查看变更，决定是否保留。不满意？git stash 即可回到审计前的状态。

3.4 维护改进看板

如果你在一个大型项目中持续运行 improve，计划会累积。用 reconcile 命令维护：

/improve reconcile

这会生成一个改进看板：哪些计划已完成、哪些仍需执行、哪些在新代码中已不再适用。适合嵌入日常开发流程——每天花 5 分钟过一遍看板，逐步消灭技术债。

3.5 一键发布到 GitHub Issues

如果你的项目在 GitHub 上，improve 支持将审计发现直接转换为 Issues：

/improve --issues

每个发现生成一个带有完整上下文（代码片段、文件路径、建议方案）的 GitHub Issue，方便团队协作和追踪。这个功能特别适合开源项目——让社区贡献者参与到技术债清理中。

3.6 CI/CD 集成

improve 可以嵌入 PR 流程：

1. 在 CI 中运行 /improve 审计 PR 涉及的代码
2. 将改进计划作为 CI artifact 输出
3. 评审者在 PR Review 中参考改进建议
4. 不阻塞合并——improve 的建议是参考性质，不是硬性门禁

定期全量审计：设置 cron 任务每周运行一次全库审计，追踪代码质量趋势。配合 --issues 参数，每周自动生成一批技术债 Issue。

四、常见问题 FAQ

Q: improve 和 Copilot / Cursor 有什么区别？

Copilot 和 Cursor 做的是实时代码补全——你在写代码时它们给你下一行建议。improve 做的是全库审计 + 计划生成——它不帮你写代码，而是帮你发现已经存在的代码问题并给出改进方案。两者定位互补，可以考虑同时使用：Copilot 写新代码，improve 审旧代码。

Q: 为什么不能用 Windows？

improve 内部依赖 git worktree 机制来安全地操作文件（在隔离的工作树中执行修改，不影响原代码）。这个机制在 Windows 上不被完整支持。如果你在 Windows 上开发，可以考虑在 WSL 或 Dev Container 中运行 improve。

Q: 便宜模型执行修改会不会”改坏”？

improve 有三层防护：① 计划中内嵌 STOP 条件——便宜模型跑偏时自动中止；② stamp git commit 做漂移检测——修改前后 diff 如果与预期不符，立即警告；③ 只读分析不改源码——所有修改先在 plans/ 目录内进行，你确认后才手动应用到源码。总体来说，破坏性远低于让 AI 直接改代码。

Q: 大型 monorepo 能用吗？成本多少？

可以用，但建议分批审计而不是一次性全库跑。100K 行代码的首次审计大约消耗 $2-5（Opus 审计费），后续增量审计（只审变更的文件）成本大幅降低——通常 < $0.5。如果使用 Sonnet 替代 Opus 做审计，成本还可再降 50%+。

Q: 审计结果有误报怎么办？

improve 的 vet 机制已经过滤了大部分常见误报，但不可能 100% 消除。如果你发现了误报，可以在审计结果中直接标记”拒绝”，improve 会记录拒绝理由，同类问题下次不再报出。多次使用后，误报率显著下降。

Q: improve 会把我项目的代码发给第三方吗？

审计过程在宿主的 Agent 内完成，代码通过 LLM API 发送给 Anthropic 或 OpenAI，数据链路与使用 Claude Code / ChatGPT 一致。improve 本身不收集、不存储你的代码。如果你对隐私要求极高，可以等待未来支持本地模型（如用 Ollama 跑审计和执行，但审计质量会下降）。

五、注意事项与最佳实践

1. 从单个模块开始：首次使用不要直接审计整个 monorepo，选一个 500-2000 行的模块练手，熟悉流程后再扩大范围
2. 确保所有测试通过：审计前跑一遍测试套件，避免在已有 Bug 的代码上叠加改进
3. Git 干净状态：审计前确保 git status 无未提交的变更，便于随时回滚
4. 分批执行：对于大型改进计划，分批执行（每批 3-5 条），每批后运行测试，确认无回归
5. 关注安全相关发现：improve 对安全问题的审计质量最高——这是 LLM 最擅长的”找茬”任务。对安全类发现优先处理
6. 不要完全信任自动修改：涉及业务逻辑、核心算法、安全敏感的代码，人工走一遍修改，不要只看 diff
7. 保存审计报告：/improve 的输出可以重定向保存，作为项目文档的一部分
8. 配合其他工具使用：improve 产出改进计划，SonarQube 做静态分析、CodeRabbit 审 PR diff——各司其职，不互相替代