shadcn/improve：让贵的 AI 模型做顾问，便宜的去干活

用 Claude Opus 写代码太贵？没关系——让它只做「读代码、找问题、写计划」的顾问工作，真正改代码的活交给便宜模型。shadcn（对，就是那个 shadcn/ui 的作者）昨天开源了一个叫 improve 的 Agent Skill，一天拿下 846 颗星，核心思路就这一句话。

一、这是什么

shadcn/improve 是一个遵循 Agent Skills 格式的 AI 编程技能。它的定位很明确：

永远不自己改代码。 它只做三件事：审计你的代码库、生成优先级排序的发现列表、把每个发现写成一份自包含的可执行计划。计划写到 plans/ 目录，然后由另一个（更便宜的）模型去执行。

1
2
3

你           →  /improve              （贵模型，做顾问）
plans/       →  001-fix-n-plus-one.md （自包含的规范文档）
其他 agent   →  实现、测试、提交       （便宜模型，干执行的活）

这个理念用一句话概括：让智力在理解、判断、规划这些「复合」环节积累，把执行这种「体力活」交给成本更低的模型。

二、为什么需要它

先看传统方式的问题：

传统 AI 编程助手的模式是「一个模型干所有事」——让它读代码、分析问题、写修复、跑测试、提交 PR，全程上下文不断膨胀，Token 成本线性增长。一旦中间出错，还得从头来一轮。

improve 的解法是把「规划」和「执行」拆开：

贵模型（如 Claude Opus、GPT-4o）只在规划阶段在线——它读代码、判断问题的严重性、写出详细的实现计划
便宜模型（如 Claude Sonnet、GPT-4o-mini）拿到计划后去执行——计划已经包含了所有上下文、验证命令、边界条件，不需要额外的推理能力
计划是纯 Markdown 文件，任何模型（甚至人类）都能直接用

关键洞察：代码审计和规划是「智力密集型」工作，需要理解全局架构、判断优先级、预见副作用——这些能力只有高端模型才有。而「按照详细规范改代码」是「执行密集型」工作，一个中等模型加上完整的上下文就能做好。

三、工作流详解

Phase 1：Recon（侦察）

先摸清仓库的「地形」：

读 README、CLAUDE.md/AGENTS.md、CONTRIBUTING 等文档
识别语言、框架、包管理器、构建/测试/lint 命令
记录代码风格、命名规范、目录结构等约定
检查 git 信号（哪些文件在活跃变更）

这些信息会成为后续每份计划的「验证门」——每个步骤都附带确切的验证命令。

Phase 2：Audit（审计）

审计覆盖 9 大类别：

对于大型仓库，会并行派出子代理（subagents），每个负责一个或几个类别。每个发现必须包含：

证据：file:line 引用，不是「感觉这里有问题」
影响：这个问题会导致什么后果
成本：修复的工作量估算（S/M/L）
风险：修复本身可能引入的问题
置信度：HIGH/MEDIUM/LOW

Phase 3：Vet（审查+排序）

这是 improve 最有特色的一点：子代理会过度报告（宁可多报不可漏报），然后由顾问模型逐一验证每个发现。

验证时会遇到三类问题：

设计如此：比如 https_proxy 环境变量被标记为 SSRF 漏洞——这是标准代理约定，不是安全问题
证据错位：发现是真的，但引用了错误的文件或行号
重复发现：不同子代理报告了同一个问题

验证后的发现按「杠杆率」（影响 / 成本，加权置信度）排序，展示给用户选择要规划哪些。

Phase 4：Plan（生成计划）

每个被选中的发现会生成一份独立的计划文件，放在 plans/ 目录下。计划的格式经过精心设计，确保最弱的可执行模型也能完成。

计划的三个核心属性：

自包含：所有上下文都内联——文件路径、当前代码摘录、仓库约定、示例文件。没有「如上所述」这种指代
验证门：每一步都附带命令和期望输出。执行者不需要判断「这步做对了没有」——跑命令看结果就知道
硬边界：明确的范围限制（哪些文件可以改、哪些绝对不能碰）和 STOP 条件（遇到什么情况必须停下来报告）

每份计划还会标记它基于的 git commit hash，执行者开始前先做 drift 检查——如果代码已经变了，计划就失效了。

四、怎么用

安装很简单：

1	npx skills add shadcn/improve

支持所有兼容 Agent Skills 格式的 AI 编程工具（Claude Code、Cursor 等）。

然后在你的项目里运行：

/improve                        完整审计 → 排序 → 生成计划
/improve quick                  快速扫描：只看热点，成本低
/improve deep                   深度审计：每个包、每个类别
/improve security               聚焦某个类别（也支持 perf、tests 等）
/improve branch                 只审计当前分支的变更
/improve plan <描述>             跳过审计，直接写一个计划
/improve execute <计划>          派便宜模型执行，审查结果
/improve reconcile              清理计划状态：验证、解锁、退役

典型使用流程：

运行 /improve，它会扫描仓库并给出发现列表
你选择要规划的发现（比如「规划 1、3、5」）
计划文件生成到 plans/，你审阅一下
运行 /improve execute 001，它会在隔离的 git worktree 里派一个便宜模型执行，然后审查 diff，给你一个裁决（approve/revise/block）
下次运行 /improve reconcile，清理计划状态

五、实际案例

shadcn 用这个工具审计了他自己的 shadcn/ui 仓库，发现了这样的问题：

| # | 发现                                              | 类别      | 成本 | 置信度 |
|---|---------------------------------------------------|-----------|------|--------|
| 1 | shadow-config 在 search.ts 和 view.ts 中重复实现  | tech-debt | M    | HIGH   |
|   | 两份代码已经漂移（search.ts:31 有 TODO）            |           |      |        |
| 2 | O(n²) 的图标迁移（migrate-icons.ts:168）           | perf      | S    | HIGH   |

同时也拒绝了一些误报，并记录了拒绝理由：

1 2	- [SEC-01] https_proxy 环境变量 "SSRF"：设计如此 — 标准代理约定，所有 CLI 都遵循。不是一个发现。

选择第一个发现后，生成的计划包含了完整的上下文：当前代码摘录、确切的修改步骤、验证命令、测试计划、STOP 条件。这份计划可以在 examples/ 目录看到。

六、硬规则

improve 有几条不可违反的规则：

绝不自己改代码：唯一的写入目标是 plans/ 目录
绝不执行变更性命令：不安装依赖、不提交代码、不做格式化。只做只读分析
绝不泄露密钥：如果审计发现凭证泄露，只记录位置和类型，建议轮换，不复制值本身
被要求直接实现？拒绝：会指向计划，或提供 execute 命令

这些规则不是建议，是写进 SKILL.md 里的硬约束。

七、和现有方案的对比

维度	传统 AI 编程助手	improve
模型使用	一个模型干所有事	贵模型规划，便宜模型执行
成本	全程高价模型在线	贵模型只在关键环节在线
可审计性	黑盒，不知道 AI 改了什么	每个决策都有证据和理由
可复用性	每次对话独立	计划可被任何模型/人类复用
质量控制	依赖模型能力	结构化的验证门和 STOP 条件
执行隔离	直接在工作目录改	隔离 worktree，审查后合并

八、局限性

需要支持 Agent Skills 的工具：目前主要适配 Claude Code，其他工具的支持程度不一
首次使用有学习成本：需要理解「规划-执行」分离的思维模式
对小项目可能过度工程化：如果项目只有几百行代码，直接让 AI 改可能更高效
计划质量取决于顾问模型：如果用便宜模型做审计，产出的计划质量会下降——这恰恰违背了设计初衷
执行者仍然可能出错：计划再完美，便宜模型也可能误解或跳过步骤——所以有 execute + review 的闭环

九、为什么是 shadcn

shadcn 不需要过多介绍——shadcn/ui 是近两年最火的 UI 组件库之一，被 Vercel 的 v0、Cursor 等产品广泛集成。他选择在 AI 编程工具领域发力，方向选得很精准：

Agent Skills 格式正在成为行业标准
「规划-执行分离」是 AI Agent 架构的前沿方向
他自己就是重度用户——用 Opus 做审计、Sonnet 做执行，每天都在吃自己的狗粮

一天 846 颗星，不意外。