shadcn/improve：让最贵的模型只做一件事——想清楚，然后交给便宜模型去写代码

来源：shadcn/improve · TypeScript · 333 stars today

一个反直觉的分工

你有一个能跑的代码库，想让 AI 帮你改进它。直觉告诉你：把代码丢给最强的模型，让它一口气把审计、规划、实现全干了。

shadcn 的 improve 偏不这么干。

它的核心设计只有一句话：用你最贵的模型审计代码库、写实施计划，然后把执行交给更便宜的模型。 技能本身从不实现任何东西——计划才是产品。

你           →  /improve          （贵模型，出主意）
plans/       →  001-fix-n-plus-one.md  （自包含规格书）
其他 agent   →  实现、测试、上线    （便宜模型，干活）

这听起来像废话——不就是分工吗？但仔细想想，当前 AI 编程的主流叙事是"一个模型干所有事"。Cursor 让一个模型写代码，Claude Code 让一个模型从审计到提交一条龙。improve 的设计假设是：智能的边际收益在递减，而上下文理解的边际收益在递增。 一个 $20/M token 的模型和一个 $0.50/M token 的模型，在"理解这个代码库为什么需要重构"这件事上差距巨大，但在"按规格书把函数从 O(n²) 改成 O(n)"这件事上差距很小。

把贵的 token 花在前者，把便宜的 token 花在后者。

五步流水线：侦察、审计、审查、排序、规划

improve 不是简单的"让 GPT-5 看看你的代码"。它是一条结构化流水线：

侦察（Recon）：先摸清仓库全貌——技术栈、约定、构建/测试/lint 命令。这些命令后来会变成每个计划里的"验证门"。它还会读 ADR（架构决策记录）、PRD、CONTEXT.md、DESIGN.md——已经做出的权衡不会被重新标记为问题。

审计（Audit）：并行子 agent 分九个类别扫描：正确性、安全、性能、测试覆盖、技术债、依赖与迁移、DX、文档、方向（功能建议）。每个发现必须带 file:line 证据、影响、工作量和置信度。不允许"通用 idea-slop"——每条建议必须引用仓库自身的代码。

审查（Vet）：子 agent 会过度报告，所以主 agent 会亲自重新阅读每个被引用的位置。误报被丢弃，错误归因被修正，被拒绝的发现会记录原因——这样下次扫描不会把同一个"问题"再报一遍。

排序（Prioritize）：按杠杆值排序（影响 ÷ 工作量，加权置信度）。你选哪些变成计划。

规划（Plan）：每个选中的发现生成一个独立文件，写入 plans/ 目录，带索引、优先级和依赖图。

这里最值得注意的是审查阶段。大多数 AI 代码审计工具的失败模式是"报了 200 个问题，180 个是误报"。improve 的设计者很清楚：子 agent 会过度报告，所以必须有一个"二审"环节，由主 agent 亲自验证每个引用点。这和人类代码审查的实践一致——初级开发者提 PR，高级开发者 review，但高级开发者不会只看 diff 摘要，会亲自打开文件看上下文。

计划为"最弱的执行者"而写

这是整个设计最精妙的部分。

improve 生成的计划不是给"同一个模型在另一个会话里"看的，而是给一个从未见过这个审计会话、可能小得多的模型看的。为了让这种跨模型交接可靠，计划必须满足三个属性：

自包含：所有上下文内联——精确文件路径、当前代码摘录、仓库约定和示例文件、已验证的命令。不允许出现"如上所述"。

验证门：每一步以一个命令和其预期输出结尾。完成标准是机器可检查的。执行者永远不需要判断自己是否成功了——跑命令，看输出，匹配就过。

硬边界：显式的范围外清单，以及 STOP 条件——"如果 X 发生，停下来报告"。不让小模型在现实与计划不符时即兴发挥。

每个计划还盖一个 git commit 戳，执行者在动手前做一个机械的漂移检查：如果代码已经变了，停下来。

这像什么？像一个资深工程师给新人写的设计文档。不是"帮我改一下这个函数"，而是"文件 X 第 42 行的函数 Y，当前实现是 O(n²)，因为嵌套循环在 Z 条件下会触发。改成用哈希表预建索引，预期测试命令 npm test -- --grep 'search' 通过，预期 lint 无新警告。如果发现 search.ts 里还有其他地方依赖原始顺序，停下来报告。"

这种文档的价值不在于"指导新人写代码"——而在于把判断和执行解耦。判断是贵的，执行是便宜的。当你把判断固化成文档，执行就变成了可以并行、可以外包、可以用更便宜算力完成的工作。

闭环：执行、审查、对账

计划不是发完就忘：

• execute <plan>：在隔离的 git worktree 里生成一个更便宜的执行者子 agent，交给它计划，然后像技术负责人一样审查结果——重跑每个完成标准、检查范围合规性、对照意图读 diff。裁决：批准（合并仍由你决定）、退回修改、或拒绝。
• reconcile：下次会话时刷新待办列表——验证哪些已落地、刷新哪些已漂移、解锁哪些卡住了。

这形成了一个循环：审计 → 规划 → 执行 → 审查 → 对账 → 再审计。每个环节的输出都是下一个环节的输入，每个环节都可以用不同复杂度的模型。

为什么这个设计值得认真对待

shadcn（本名 Sahil）不是在真空中设计这个的。他是 shadcn/ui 的作者——一个被数十万开发者使用的 React 组件系统。他每天面对的问题就是"如何让 AI 帮我维护一个大型设计系统"。improve 最初就是跑在 shadcn/ui 自身上的。

README 里给了一个真实例子：跑 improve 审计 shadcn/ui 仓库，发现了 search.ts 和 view.ts 之间重复的 shadow-config（副本已经漂移，TODO 标记还在），以及 migrate-icons.ts:168 的 O(n²) 图标迁移。同时它拒绝了 SEC-01 发现（https_proxy 环境变量的"SSRF"风险），理由是"标准代理约定，每个 CLI 都遵守，不是发现"。

这个拒绝记录很重要——它说明系统在积累判断力。每次拒绝都会被记录，下次扫描不会重复报告。这和人类团队的实践一致：好的代码审查不是"报告所有可能的瑕疵"，而是"在团队约定和真实问题之间做区分"。

更大的图景：Agent 技能生态

improve 通过 npx skills add shadcn/improve 安装，遵循 Agent Skills 格式。这意味着它可以工作在任何支持该格式的 agent 里——Claude Code、Cursor、Codex、Windsurf。计划是纯 Markdown，任何 agent 或人类都能接手。

这是一个更大的趋势：技能作为跨平台的能力包。不是"Cursor 插件"或"Claude Code 扩展"，而是一个中立的格式，可以在不同 agent 之间迁移。技能本身不绑定执行环境——它只定义"如何思考一个问题"，不定义"如何运行代码"。

improve 的定位很清晰：它是审计和规划层，不是执行层。它不试图成为"全能 agent"，而是做好一件事——把代码库的改进机会变成可执行的规格书。剩下的交给别人。

一句话总结：improve 把 AI 编程从"一个模型干所有事"拆成了"贵的模型想清楚，便宜的模型干清楚"。计划是产品，执行是商品。在 token 价格差 40 倍的今天，这个分工的经济学意义比技术意义更大。