shadcn/improve 使用指南：让最聪明的模型审计代码，便宜的模型来干活（6K Stars）

引言

你有没有这样的经历：让 Claude、GPT-4 帮你改代码，改得确实不错，但一次就要花掉几万 token。如果整个团队每天都用，月底账单能让你怀疑人生。

但反过来想，代码审计和方案设计才是最需要"高智商"的部分——真正理解整个代码库、判断哪里值得改、写详细的实施计划。至于"照着计划把代码敲出来"这种体力活，完全可以用更便宜的模型来做。

这就是 shadcn 最新开源项目 improve 的核心思想。

improve：用你最贵的模型审计代码库、写实施计划，然后交给便宜的模型去执行。

项目在 GitHub 上发布不到两周就获得了 6063 星，shadcn（shadcn/ui 作者）又一次精准命中了开发者痛点。今天我就带大家从安装到实战，完整走一遍 improve 的使用流程。

什么是 improve

improve 是一个 Agent Skill，专门给 AI 编程助手（如 Claude Code、Codex 等）用的技能。它本身不会直接改动你的代码——它的产出是计划（plan），是一份份 Markdown 文件，详细描述要改什么、怎么改、改完怎么验证。

整个工作流是这样的：

开发者 → /improve 审计指令 → (最贵的模型：审计代码库，找出问题)
       → plans/001-fix-n-plus-one.md (自包含的计划文件)
       → (便宜的模型：照着计划实现、测试、提交)

核心设计哲学

1. 智能集中在最需要的地方：代码审计需要理解全局架构、识别潜在问题、评估技术债务——这些需要"高智商"。而具体实现是机械性的，谁来做都差不多。
2. 计划是产品：improve 产出的是可审查、可执行的 Markdown 计划文件。人类可以读，便宜的 AI 也可以读。
3. 可复现的审计：每次运行都做同样的分类覆盖，不会遗漏。

安装 improve

improve 的安装极其简单，一行命令搞定：

npx skills add shadcn/improve

这条命令会从 shadcn/improve 仓库拉取最新的 skill 定义，安装到你的 AI 编程助手的技能目录中。

兼容的 AI 编程助手

improve 使用标准的 Agent Skills 格式，支持以下工具：

• Claude Code（Anthropic 官方 CLI）
• Codex CLI（OpenAI）
• Cursor（通过 Skills 插件）
• 任何支持 Agent Skills 标准的 AI 编程工具

安装完成后，在你的项目目录中启动 AI 编程助手，就可以使用 /improve 命令了。

基础用法

首次运行全流程审计

在你的项目根目录中，直接输入：

/improve

或者，如果你想快速了解一下代码库的健康状况（更省 token）：

/improve quick

improve 会做以下几件事：

1. Recon（侦察）：扫描整个代码仓库，了解技术栈、目录结构、构建命令、测试命令。它会读取项目中的 ADR（架构决策记录）、DESIGN.md、CONTEXT.md 等文档，确保后续不会把已经决策的问题当成"发现"上报。
2. Audit（审计）：派出多个并行子代理，覆盖 9 个审计维度：
   • 正确性
   • 安全性
   • 性能
   • 测试覆盖度
   • 技术债务
   • 依赖与迁移
   • 开发者体验
   • 文档
   • 方向建议（每个建议都必须有代码库中的证据支撑）
3. Vet（复核）：主代理会重新读取每一个被引用的代码位置，剔除 false positive，纠正错误归因，记录被剔除的理由。
4. Prioritize（排序）：所有发现按"影响度 ÷ 工作量"排序，置信度加权。你看到的就是一个清晰的优先级表格。

查看审计结果

审计完成后，你会看到一个类似这样的表格：

#	发现	类别	工作量	置信度
1	shadow-config 在 search.ts/view.ts 中重复，已经出现分歧	技术债务	M	高
2	migrate-icons.ts:168 存在 O(n²) 图标迁移逻辑	性能	S	高

如果某个问题被故意剔除，也会给出理由，比如：

SEC-01 https_proxy 环境变量"SSRF 风险"：这是标准代理约定，所有 CLI 都遵守。不是安全问题。

生成实施计划

看到表格后，回复你想要规划的问题编号：

plan 1, 3, 5

improve 会为每个选中的问题生成一个独立的 Markdown 计划文件，存放在 plans/ 目录中，同时生成一个索引文件标明推荐的执行顺序。

实战：用 improve 审计一个开源项目

为了让你更直观地理解 improve 的威力，我们用一个真实场景来演示。

假设你正在维护一个 React 组件库项目，团队最近发现构建越来越慢、代码质量参差不齐。你想知道到底有哪些地方需要改进。

第一步：运行审计

cd /path/to/your-project
# 启动 Claude Code 后输入：
/improve

等待约 1-3 分钟（视项目大小而定），你会收到一份详尽的审计报告。

第二步：分析发现

审计可能给出如下发现：

📋 审计发现（按优先级排序）

# │ 发现                                  │ 类别     │ 工作量 │ 置信度
──┼───────────────────────────────────────┼──────────┼────────┼──────
1 │ Button 组件重复渲染（memo 缺失）       │ perf     │ S      │ HIGH
2 │ useAuth hook 缺少错误边界              │ security │ M      │ HIGH
3 │ 3 个组件使用已废弃的 colors API        │ deps     │ S      │ HIGH
4 │ utils/format.ts 单元测试覆盖率 < 30%   │ tests    │ L      │ MEDIUM
5 │ 全局样式混入导致组件样式冲突           │ tech-debt│ M      │ HIGH

第三步：生成计划

你选择优先处理前 3 个：

plan 1, 2, 3

得到三个计划文件：

plans/
├── index.md
├── 001-button-memo-optimization.md
├── 002-useauth-error-boundary.md
└── 003-migrate-deprecated-colors.md

每个计划文件都是自描述的 Markdown，包含：

• 当前代码摘录
• 具体修改步骤
• 验证命令和预期输出
• 终止条件（当现实与假设不符时停止执行的条件）

第四步：执行计划

你可以自己读计划后手动修改，也可以让 improve 调度便宜的模型来执行：

/improve execute 001

improve 会在一个隔离的工作目录中调度便宜的模型执行计划，修改完成后会对比 diff 与计划的一致性，给出执行报告。合并代码的权力始终在你手上。

进阶用法

分支审计（适合 PR 评审）

当你只关心当前分支改了什么时：

/improve branch

这只会审计当前分支相对于 main 的变更，非常适合 Code Review 场景。

专项审计

improve 支持指定审计维度：

/improve security    # 只看安全问题
/improve perf        # 只看性能问题
/improve tests       # 只看测试覆盖
/improve bugs        # 只看可能的 bug

自定义计划（跳过审计）

如果你已经知道要改什么，只是想生成一个规范的计划：

/improve plan "重构 users API 的路由，将 /api/users/* 改为 RPC 风格"

它会跳过审计阶段，直接根据你的描述生成一个规范的计划文件。

审阅已有计划

如果团队成员写了一个计划，你想让 AI 帮忙审查：

/improve review-plan docs/refactor-plan.md

同步工作进度

在新一轮工作开始前，更新 backlog：

/improve reconcile

这会验证已完成的工作、更新已漂移的计划、标记变更的计划。

发布为 GitHub Issues

如果你想把计划同步到 GitHub Issues：

/improve ... --issues

每个计划会自动创建一个 Issue，方便团队协作。

技术原理深度解析

Recon 阶段：理解代码库

Recon 是 improve 最聪明的设计之一。它不只是 grep 找问题，而是先理解项目：

• 读取 package.json、Cargo.toml、pyproject.toml 等技术栈文件
• 获取构建和测试命令
• 理解项目约定和架构模式
• 读取 ADR、DESIGN.md 等设计文档

这意味着 improve 知道你的项目用的是 npm 还是 pnpm，测试用的是 Jest 还是 Vitest，代码风格是什么——这些信息会被写入每个计划文件，确保执行代理不需要额外猜测。

并行子代理架构

Audit 阶段会派出 9 个并行子代理，每个专注于一个维度。这种"分而治之"的方式相比让一个模型逐行扫描，效率高得多——子代理可以同时分析不同文件的不同方面。

而且子代理有"过度报告"的倾向（宁可误报也不漏报），但主代理会逐一复核，大幅降低 false positive。

计划的可执行性

plans 是为"最弱执行者"设计的——一个从未参与过审计对话、可能更小的模型。三个特性保证可执行：

1. 自包含：所有上下文都在计划中——精确文件路径、当前代码摘录、项目约定示例、已验证的命令。不会出现"如上所述"这种模糊表述。
2. 验证关卡：每个步骤都以一个验证命令结尾，并写明预期输出。执行完后运行命令就知道对不对。
3. 终止条件：当实际情况与计划假设不符时，执行代理会停止并报告，而不是盲目修改。

与其他工具的对比

特性	shadcn/improve	CodeRabbit	SonarQube	手动Code Review
审计维度	9个	代码质量+安全	代码质量+安全	依赖人员经验
生成可执行计划	✅	❌	❌	❌
多模型调度	✅	❌	❌	❌
假阳性自动过滤	✅	部分	部分	人工过滤
分支审计	✅	✅	✅	✅
PR 集成	手动	自动	自动	手动
成本控制	灵活（贵+便宜模型）	固定定价	企业许可	人力成本

适用场景与最佳实践

最适合的场景

1. 大型代码库审计：几千个文件的项目，人工 review 太慢，单模型全量扫描太贵
2. 新手 onboarding：新成员加入项目后，跑一次 /improve 快速了解代码库的质量问题和约定
3. 版本发布前检查：Release 之前跑一次 /improve security 和 /improve bugs
4. 技术债务梳理：每个季度跑一次 /improve deep，系统化地梳理和规划技术债务
5. 开源项目维护：让社区 PR 通过 /improve branch 自动审计，减轻维护者负担

成本优化建议

improve 的价值在于节省成本而不是增加成本。参考配置：

• 日常开发：用 /improve quick（便宜模型审计重点文件）
• 深度审计：用 /improve deep（最贵模型全量扫描）
• 执行阶段：用便宜模型（如 Claude 3 Haiku、GPT-4o-mini）执行计划
• 安全审计：必须用最贵模型（Claude Opus、GPT-4.5）

团队协作流程建议

周一: /improve reconcile → 清理 backlog
周二: 团队评审当前 plans/
周三: /improve execute → 调度执行已审计划
周四: Code Review + 合并
周五: /improve branch → PR 审计

常见问题

improve 会修改我的代码吗？

不会。improve 从来不直接修改代码。它的产出是 Markdown 计划文件。修改代码的是你指定的执行代理，或者你自己手动修改。

需要 API Key 吗？

improve 本身是免费的 skill，但底层的 AI 编程助手（Claude Code、Codex 等）需要对应的 API Key。

可以在没有 AI 编程助手的项目中使用吗？

可以。improve 产生的计划是纯 Markdown 文件，任何代理（甚至人类开发者）都可以读取和执行。你只需在支持 Agent Skills 的工具中运行 /improve 生成计划，然后将计划文件交给其他开发者。

会不会漏掉问题？

任何代码审计工具都有一定的漏报率。improve 通过以下方式降低漏报：

• 9 个并行子代理覆盖不同维度
• 子代理"过度报告"策略 + 主代理复核过滤
• 支持深度模式（/improve deep）进行更彻底的扫描

但作为最佳实践，建议关键变更仍然加上人工 Code Review。

总结

shadcn/improve 代表了一种新的 AI 辅助开发范式：让智能专注于最需要的地方。

不是让一个模型做所有事情，而是把"理解-诊断-规划-执行"这个链条拆开，用最合适的模型做最合适的事。代码审计、架构分析、方案设计交给最强的模型；照着计划实现的体力活交给更便宜的模型。

这种思路不仅省钱，产出质量也更高——因为每个环节都用了最合适的工具。

如果你正在管理一个中型以上的代码库，或者想系统化地梳理技术债务，improve 值得一试。

---

💡 你可以在 zidongai.com.cn 找到更多 AI 编程效率工具和自动化工作流指南。如果你在使用 improve 的过程中有好的经验，也欢迎在评论区分享交流。