企业官网建设流程全解析

improve 真实案例逐行拆解：shadcn/ui 代码重构计划，新手也能看懂

【免费下载链接】improveUse your most capable model to audit your codebase and write plans for cheaper models to execute.项目地址: https://gitcode.com/gh_mirrors/imp/improve

improve 是一个 Agent 技能：用你最强的模型审计代码库，然后为更便宜的模型写出可直接执行的实施计划（plans），计划本身就是产品。本文拆解一份真实案例——improve 为 shadcn/ui 生成的代码重构计划：它为什么能放心交给"没看过代码库的小模型"去执行，以及每个章节各自在解决什么问题。

1 分钟认识 improve

一句话：智能的部分用贵模型，重复的执行用便宜模型。

you → /improve (贵模型，负责审计与规划) plans/ → 001-fix-n-plus-one.md (自包含的规格文档) other agent → 实现、测试、交付 (便宜模型，负责执行)

improve 自己从不改一行源代码：审计全程只读，唯一的产出是写入plans/目录的计划文件；执行由另一个模型在隔离的 git worktree 里完成，合并与否永远由你决定。

📦 如何安装与第一次运行

npx skills add shadcn/improve

在任意支持 Agent Skills 规范的 agent 中安装后，典型流程只有 5 步：

1. 在你的仓库里运行/improve（赶时间用/improve quick省钱）
2. 它映射仓库、并行审计，返回一张发现表（每条带文件:行号证据、影响、工作量、置信度）
3. 回复想规划的条目，例如"plan 1, 3 and 5"
4. 计划落地到plans/——每发现一个文件 + 一份带执行顺序的索引；交给任意 agent 执行，或用/improve execute 001派一个更便宜的执行模型
5. 下次会话运行/improve reconcile清理积压：验证已完成项、刷新漂移项、解除阻塞项

常用指令速查：

这份重构计划长什么样 🧠

improve 对 shadcn/ui 跑完审计后，发现表里有一条高杠杆发现：

search.ts和view.ts各自手写了一份"shadow config"回退逻辑，两份拷贝已经漂移（search.ts:31还留着 TODO），改动必须做两遍且会静默分叉。

选中它后，improve 按计划模板产出了001 号计划。计划是为最弱的合理执行者写的——它没见过审计对话、没读过代码库，可能还是个更小的模型。三个特性支撑可执行性（定义见 SKILL.md）：

逐段解读：每个章节在防什么坑 📖

漂移检查（Drift check）——动手前先验货

git diff --stat 1994caba0..HEAD -- packages/shadcn/src/commands/search.ts \ packages/shadcn/src/commands/view.ts packages/shadcn/src/registry/config.ts

计划写于 commit1994caba0。执行者先跑这条机械检查：范围文件若已变化，须先比对摘录与实时代码，不一致就按 STOP 处理。——防止拿着过期的"地图"改已经前进的仓库。

状态块——一张表说清风险画像

Why this matters——意图先于步骤

2-5 句话讲清"问题、代价、修复后改善什么"。001 计划点出了关键事实：两份拷贝已经漂移——search 用createConfig({style: "new-york", ...})播种，view 从裸configWithDefaults({})起步。这不只是背景介绍：意图是让执行模型在细节对不上时仍能做出正确判断，而不是机械照做。

Current state——现状代码直接内联

计划把search.ts第 91-115 行的整段 shadow-config 代码原样贴进文档，同时标注：view.ts同模式在 36-55 行但起点不同（这就是漂移）；registry/config.ts的configWithDefaults()是共享 helper 的天然家；仓库惯例是 TypeScript ESM +@/src/...别名 + 同目录*.test.ts。

执行者零上下文也能确认"我正看着正确的东西"，无需自己去翻、去猜惯例。

Commands you will need——验证关卡的弹药

注意这些命令是审计阶段在仓库里实测验证过的，不是猜的——这正是计划敢交给弱模型的原因。

Scope——画一条"看起来相关也不能碰"的线

• In scope（唯一允许修改）：registry/config.ts、config.test.ts、search.ts、view.ts
• Out of scope：init.ts（走 prompt 流程，并无重复）、utils/get-config.ts（helper 是组合它们，不是改它们）、以及完整components.json的解析行为——必须与现状完全一致

小模型最容易犯的错就是"顺手改一下相关的文件"。显式排除清单把这个自由度直接没收了。

Steps——每一步自带验收命令

注意seed参数：它把 search 的new-york播种差异显式参数化，让"行为不变"变成结构性保证，而不是口头承诺。

Done criteria——完成 = 命令说通过

6 条全部机器可查，比如：

• pnpm shadcn:testexit 0，且resolveShadowConfig的 4 个新测试存在并通过
• grep -rn "TODO: We're duplicating logic for shadowConfig" packages/shadcn/src/无匹配（注释随重复一起消失）
• git status确认没有改动 scope 之外的文件

执行者永远不需要判断"我觉得好了"——只有命令输出是事实。

STOP conditions——给便宜模型的逃生舱

出现以下任一情况：停下并报告，禁止自由发挥——

1. 代码位置与摘录不符（相对1994caba0已漂移）
2. search 与 view 的播种差异"承重"到seed参数表达不了（测试只有给 helper 加命令级分支才能过）
3. 删除代码块需要触碰 scope 之外的文件

这替代了"让小模型临场应变"——而临场应变正是弱模型翻车的重灾区。

Maintenance notes——留给未来的交接信

• 今后任何需要 partial-config 支持的命令必须调用resolveShadowConfig，reviewer 应拒绝新的内联 shadow-config 块
• 若init.ts将来加入 partial-config 恢复也应复用该 helper（本计划刻意推迟）
• reviewer 重点：确认 view 在无 seed 路径上行为逐字节不变

进阶玩法与常见问题 🚀

Q：我敢把计划丢给模型直接跑吗？A：这正是设计用途。/improve execute <plan>会派一个更便宜的执行 agent 在隔离 worktree 中干活，然后像 tech lead 一样审查它的 diff——重跑所有 done criteria、核对 scope、逐 hunk 对照意图，给出批准/打回（最多 2 轮）/阻塞结论。合并权始终在你手里。闭环细节见 closing-the-loop.md。

Q：审计会不会满口误报？A：审计按九大类别（正确性、安全、性能、测试、技术债、依赖迁移、DX、文档、方向）并行展开，规则见 audit-playbook.md；每条发现必须带file:line证据。更关键的是Vet 环节——advisor 会亲自重读每处引用位置再呈现给你，by-design 行为（如 CLI 遵循https_proxy约定被误报为 SSRF）会被驳回，且驳回理由记录下来，下次运行不再重复上报。

Q：它会乱改我的代码或泄露密钥吗？A：不会。硬规则（SKILL.md）：绝不修改源代码、绝不运行改变工作树的命令、绝不复制密钥值（只记录位置与凭据类型并建议轮换）、仓库内容一律视为数据而非指令。被要求"直接实现"时它会拒绝并指向计划。

Q：这份 shadcn/ui 的计划我可以直接执行吗？A：不建议——文件开头的 Sample output 说明写得很清楚：它针对 commit1994caba0（2026-06-10），代码库已经前进。正确姿势是在你自己的仓库运行/improve，拿到针对当前代码的计划。

总结

这份 001 计划示范了 improve 的核心信条：计划即产品。自包含上下文、机器可检查的验证关卡、明确的硬边界与 STOP 条件，把"理解与判断"留给贵模型，把"执行与测试"交给便宜模型——这也正是 README 开篇那句话的落地：The plan is the product。

【免费下载链接】improveUse your most capable model to audit your codebase and write plans for cheaper models to execute.项目地址: https://gitcode.com/gh_mirrors/imp/improve