improve：用强模型审计、让弱模型执行的"计划即产品"工作流

<blockquote><p>&quot;The plan is the product.&quot;<br>计划才是产品。</p><p>——shadcn&#x2F;improve README</p></blockquote><p>shadcn 是谁，不用多介绍。他创建的 shadcn&#x2F;ui 是 GitHub 上 Star 数最高的 React 组件库之一，11 万+，几乎凭一己之力改变了前端组件库的交付范式——不是&quot;装一个 npm 包&quot;，是&quot;把源码拷进你的项目，你拥有它，你改它，你对它负责&quot;。这种对控制权和所有权的执念，是他所有作品的设计 DNA。</p><p>2026 年 6 月，他在这个 DNA 上又加了一层——开源了一个叫 improve 的 Agent Skill。一周之内，5000+ star。</p><p>improve 做的事情，说穿了就是一句话：用最贵的模型读代码库、找问题、写执行计划，用最便宜的模型照着计划敲代码。它自己不碰源码，产出只有一种东西——计划。</p><p>这个分工背后是一笔所有用 AI 写代码的人都在付、但很少认真算过的账。用 Opus 读代码库、找 bug、排优先级，值。用 Opus 敲每一行代码、跑每一个测试、写每一句 commit message，不值。但现在的 AI 编程工具不管这些——你给它们什么模型，它们就全程用什么模型。预算好的团队手动切模型——研究阶段用 Opus，实现了切 Sonnet，跑测试了再切 Haiku。切来切去，时间都花在模型下拉菜单上了。</p><p>improve 把这个手动切换内建成了自动分工：强模型只负责判断。执行扔给最便宜的、够用的模型。</p><span id="more"></span><p><img src="/images/image-20260620033121755.png"></p><p>第 13 章讲 GSD Core 用阶段循环、子智能体和持久化工件对抗上下文腐化。GSD 的回答是&quot;给每个 Agent 一份干净的上下文&quot;。本章讲同一个问题的另一个切面：不是管上下文，管成本。GSD 默认质量优先，谁干活无所谓。但真金白银的 API 账单不这么想。improve 的回答是：强模型做判断，弱模型做执行——把账单和质量一起管了。</p><h2 id="14-1-improve-是什么"><a href="#14-1-improve-是什么" class="headerlink" title="14.1 improve 是什么"></a>14.1 improve 是什么</h2><p>安装一行：</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">npx skills add shadcn/improve</span><br></pre></td></tr></table></figure><p>MIT 开源，遵循 Agent Skills 格式（agentskills.io），Claude Code、Cursor、Codex、OpenCode 装完就能调。</p><p>但它跟前面章节讲的技能有一个根本区别。Mattpocock 的 <code>/diagnose</code> 帮你修 bug。gstack 的 <code>/review</code> 帮你查代码。Goal Workflow 的 <code>/goal</code> 帮你实现功能。improve 反着来。你让它&quot;帮我实现这个&quot;，它说不。你让它&quot;帮我修这个 bug&quot;，它说不。它只做一件事：读你的代码库，找出该做什么，写成一份计划。</p><p>README 里有两句话定义了它的全部边界。第一句：&quot;你是一个高级顾问，不是实现者。&quot;第二句：&quot;计划才是产品——它的质量决定了执行者能不能成功。&quot;理解 improve 所有设计决策的钥匙就是这两句话。它不是执行工具，是决策工具。交付物不是代码，是决策。</p><p>这带来一个权力反转。大多数 AI 编程工具把写代码当作正事，写计划是可有可无的前置步骤。improve 反过来：计划是一等公民，代码只是计划的衍生品。一份好计划应该自包含到什么程度？你把它交给一个完全不了解这个项目的人，或者 Agent，他能照着做完，不用你坐在旁边解释。需要你解释，计划没写好。</p><h2 id="14-2-核心思想：能力与成本的分离"><a href="#14-2-核心思想：能力与成本的分离" class="headerlink" title="14.2 核心思想：能力与成本的分离"></a>14.2 核心思想：能力与成本的分离</h2><p>improve 的经济账一句话：高杠杆的思考给贵模型，高重复的执行给便宜模型。</p><p><img src="/images/image-20260620033329316.png"></p><p>听起来像废话，谁不知道贵的模型好？但 improve 做的不是&quot;用贵的 &#x3D; 更好&quot;这种粗糙选择。它分了工：</p><table><thead><tr><th>工作</th><th>性质</th><th>需要的智能</th><th>交给</th></tr></thead><tbody><tr><td>读懂整个代码库</td><td>一次性、高杠杆</td><td>跨文件推理、架构判断、安全直觉</td><td>Opus&#x2F;GPT-4 级别</td></tr><tr><td>判断什么值得做</td><td>一次性、高杠杆</td><td>权衡、优先级、成本估计</td><td>Opus&#x2F;GPT-4 级别</td></tr><tr><td>写规格和计划</td><td>一次性、高杠杆</td><td>精确表达、边界定义、验证设计</td><td>Opus&#x2F;GPT-4 级别</td></tr><tr><td>照着计划写代码</td><td>重复、低杠杆</td><td>按指令执行、跑测试、报结果</td><td>Haiku&#x2F;GPT-4o-mini 级别</td></tr></tbody></table><p>这个分工和第 12 章的 maker-checker 分离、第 13 章的瘦编排者模式有同一个源头：不同性质的活交给不同的 Agent。但分工轴不同。GSD 按阶段分（研究员 vs 执行器 vs 验证者），improve 按智能密度分。读代码、做判断、写规格，这些活智能密集，强模型贵得值。敲代码、跑测试、报结果，智能稀疏，弱模型够了。</p><p>improve 的 README 用一句话概括了这个经济逻辑：昂贵的、天花板高的模型做智能会累积的那部分——理解、判断、写规格；便宜的模型做执行。翻译过来就是：让最贵的模型做它最擅长的事，然后让便宜的照着做。</p><p>这里藏着一个关键前提，也是 improve 最深的洞见：执行的质量上限是计划的质量。弱模型拿烂计划产出烂代码。拿好计划——内联了文件路径、代码摘录、验证命令、STOP 条件——产出接近强模型。弱模型的瓶颈不是不会写代码，是没有上下文。自包含的计划刚好补上。</p><p>说白了，improve 干的事就是把强模型对代码库的理解蒸馏到一份 markdown 里，这份文件变成弱模型的上下文。强模型烧一次 token，弱模型烧很多次。只要计划好，每次执行都复用那一次深度分析。总账是省的。</p><h2 id="14-3-五阶段流水线：Recon-→-Audit-→-Vet-→-Prioritize-→-Plan"><a href="#14-3-五阶段流水线：Recon-→-Audit-→-Vet-→-Prioritize-→-Plan" class="headerlink" title="14.3 五阶段流水线：Recon → Audit → Vet → Prioritize → Plan"></a>14.3 五阶段流水线：Recon → Audit → Vet → Prioritize → Plan</h2><p>improve 的工作流五步，每步明确的输入、输出和质量标准。</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line">Recon → Audit → Vet → Prioritize → Plan</span><br><span class="line"> │ │ │ │ │</span><br><span class="line"> │ │ │ │ └── 为每个选中发现写可执行计划</span><br><span class="line"> │ │ │ └── 按杠杆率排成优先级表</span><br><span class="line"> │ │ └── 重读源码剔除误报</span><br><span class="line"> │ └── 并行子智能体扫九大类</span><br><span class="line"> └── 画仓库地图</span><br></pre></td></tr></table></figure><p><img src="/images/image-20260620033637279.png"></p><h3 id="14-3-1-Recon：画地图"><a href="#14-3-1-Recon：画地图" class="headerlink" title="14.3.1 Recon：画地图"></a>14.3.1 Recon：画地图</h3><p>Recon 不分析，只测绘。规划前回答几个最基本的问题：</p><ul><li><strong>技术栈</strong>。语言、框架、包管理器、构建系统。读 <code>package.json</code>、<code>Cargo.toml</code>、<code>go.mod</code>，不猜。</li><li><strong>目录结构</strong>。<code>src/</code> 还是 <code>app/</code>？monorepo 还是单包？测试放哪？配置放哪？</li><li><strong>构建&#x2F;测试&#x2F;Lint 命令</strong>。精确到能粘贴进终端的程度。<code>npm test</code> 还是 <code>pytest</code>？有没有覆盖率阈值？</li><li><strong>代码约定</strong>。命名风格、文件组织模式、已有的 lint 规则。</li><li><strong>意图文档</strong>。如果项目里有 <code>CONTEXT.md</code>（第 13 章）、<code>STRATEGY.md</code>（第 15 章）、ADR 目录、PRD 文件，Recon 优先吸收。别人花 token 讨论出来的决定，不要重新花 token 再讨论一遍。</li></ul><p>Recon 的输出是一份代码库地图，后续所有阶段共享。它自己不产生发现，但所有发现依赖它。一个审计员不知道项目是 monorepo，可能把&quot;每个子包有自己的 <code>tsconfig.json</code>&quot;标记为冗余。实际上是设计决定。</p><h3 id="14-3-2-Audit：九类并行扫描"><a href="#14-3-2-Audit：九类并行扫描" class="headerlink" title="14.3.2 Audit：九类并行扫描"></a>14.3.2 Audit：九类并行扫描</h3><p>整个流水线最烧 token 的阶段，也是强模型最值钱的地方。</p><p>improve 派出多个子智能体，每个扫一个维度，并行跑：</p><table><thead><tr><th>维度</th><th>关心什么</th></tr></thead><tbody><tr><td>正确性</td><td>逻辑错误、边界条件、空值处理、竞态条件</td></tr><tr><td>安全</td><td>OWASP Top 10、注入、敏感信息泄露、不安全的依赖</td></tr><tr><td>性能</td><td>不必要的分配、N+1 查询、阻塞 I&#x2F;O、内存泄漏</td></tr><tr><td>测试覆盖</td><td>缺测试、脆弱的测试、不可测的代码结构</td></tr><tr><td>技术债</td><td>重复代码、死代码、过度抽象、违反约定的模式</td></tr><tr><td>依赖与迁移</td><td>过时的依赖、未解决的迁移、版本漂移</td></tr><tr><td>开发者体验</td><td>类型安全缺失、构建慢、开发环境摩擦</td></tr><tr><td>文档</td><td>缺失或过时的文档、误导性的注释</td></tr><tr><td>方向</td><td>缺失的功能、架构演进机会、roadmap 对齐</td></tr></tbody></table><p>每个维度的子智能体独立工作，和第 13 章 GSD 的并行 mapper 同一个模式。并行跑，总时间等于最慢的那一个。</p><p>每条发现带四样东西：<code>file:line</code> 证据，不写&quot;可能有注入风险&quot;写 <code>src/auth/login.ts:42</code>；影响评估，如果不管会怎样；预估工作量，S&#x2F;M&#x2F;L&#x2F;XL；置信度。</p><p>有一个重要选择：子智能体默认过度上报。宁可多报 100 个最后被筛掉的疑似问题，不能漏一个真的。假阳性浪费的是 Vet 阶段的 token，假阴性浪费的是将来的线上事故。token 比事故便宜。</p><h3 id="14-3-3-Vet：剔除误报"><a href="#14-3-3-Vet：剔除误报" class="headerlink" title="14.3.3 Vet：剔除误报"></a>14.3.3 Vet：剔除误报</h3><p>Audit 产出发现，Vet 做质量控制。</p><p>做法很暴力：顾问角色重新读每一个被引用的源码位置，逐条核实&quot;真的有问题吗？&quot;</p><p>第 12 章说过 maker-checker 分离，写代码和查代码的不能用同一个 Agent，自己给自己打分太客气。Audit 也一样：发现者对自己的发现有确认偏差。子智能体找到一个问题的时候，已经带着&quot;这里有问题&quot;的假设读了那段代码。让它再读一遍，大概率还是觉得有问题。</p><p>Vet 用一个独立的 Agent 重新读，带着&quot;这条可能是错的&quot;的假设。被踢掉的发现记进误报清单，下次审计直接跳过。这个记仇机制很重要。没有它，每次审计都重新报同样的假阳性，你很快就学会忽略所有发现。</p><h3 id="14-3-4-Prioritize：按杠杆率排序"><a href="#14-3-4-Prioritize：按杠杆率排序" class="headerlink" title="14.3.4 Prioritize：按杠杆率排序"></a>14.3.4 Prioritize：按杠杆率排序</h3><p>Vet 之后一批确认的发现。全做不现实。Prioritize 排优先级。</p><p>基础公式：</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">杠杆率 = 影响 ÷ 工作量</span><br></pre></td></tr></table></figure><p>影响和工作量都有不确定性，改进后：</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">加权杠杆率 = (影响 × 影响置信度) ÷ (工作量 × 工作量置信度)</span><br></pre></td></tr></table></figure><p>一个影响极高但置信度低的发现（&quot;可能&quot;有严重安全漏洞），和一个影响中等但置信度高的发现（&quot;确定&quot;有个性能瓶颈），后者的加权杠杆率可能更高。公式把&quot;把握有多大&quot;算进去了。</p><p>输出是一张表，不是指令。Prioritize 不说&quot;你应该做前三个&quot;，那是人做的决定。但它把信息排清楚，你花最少的时间就能选。</p><h3 id="14-3-5-Plan：写执行手册"><a href="#14-3-5-Plan：写执行手册" class="headerlink" title="14.3.5 Plan：写执行手册"></a>14.3.5 Plan：写执行手册</h3><p>最后一步，对你选中的每个发现写一份可执行计划。存在 <code>plans/</code> 目录，一个发现一个文件，纯 markdown，人读得了，Agent 也读得了。</p><p>计划有索引文件，记录顺序和依赖。计划 C 依赖计划 A 完成后的文件结构，依赖图会标出来。</p><p>五步走完就是&quot;计划即产品&quot;的完整闭环：Audit 告诉你有什么值得做，Vet 确认真的值得，Prioritize 告诉你先做哪个，Plan 告诉执行者怎么干。</p><h2 id="14-4-命令全景"><a href="#14-4-命令全景" class="headerlink" title="14.4 命令全景"></a>14.4 命令全景</h2><p>improve 的命令设计有个原则：从最常用的路径出发，用标志而不是子命令表达变化。默认无参数走完整流水线，大多数时候这就是你要的。其他命令是变体。</p><p><img src="/images/image-20260620101223900.png"></p><table><thead><tr><th>命令</th><th>做什么</th><th>什么时候用</th></tr></thead><tbody><tr><td><code>/improve</code></td><td>完整流水线</td><td>日常改进</td></tr><tr><td><code>/improve quick</code></td><td>只扫热点，返回最优先的发现</td><td>快速体检</td></tr><tr><td><code>/improve deep</code></td><td>穷尽扫描每个包、每个维度</td><td>上线前、接手新项目</td></tr><tr><td><code>/improve security</code></td><td>只做安全审计</td><td>合规、安全评审前</td></tr><tr><td><code>/improve perf</code></td><td>只做性能审计</td><td>优化轮</td></tr><tr><td><code>/improve tests</code></td><td>只做测试覆盖</td><td>补测试前摸底</td></tr><tr><td><code>/improve bugs</code></td><td>只做正确性审计</td><td>Bug bash 前</td></tr><tr><td><code>/improve branch</code></td><td>只审计当前分支变更</td><td>PR 前自查</td></tr><tr><td><code>/improve next</code></td><td>功能建议、roadmap 方向</td><td>下轮规划</td></tr><tr><td><code>/improve plan &lt;描述&gt;</code></td><td>跳过审计，直接为一件事写计划</td><td>需求已明确</td></tr><tr><td><code>/improve execute &lt;计划&gt;</code></td><td>隔离 worktree 派廉价执行器，完事审查 diff</td><td>执行已批准的计划</td></tr><tr><td><code>/improve review-plan &lt;文件&gt;</code></td><td>强模型评审已有计划</td><td>计划评审</td></tr><tr><td><code>/improve reconcile</code></td><td>刷新 backlog，验证完成、解除阻塞、退役过时的</td><td>定期维护</td></tr></tbody></table><p>带 <code>--issues</code> 时，improve 同时把计划发成 GitHub Issue，每个计划一个 Issue，带标签和依赖引用。计划从 <code>plans/</code> 目录走出来，进入团队工作流，可以被 assign、comment、close。</p><h3 id="14-4-1-execute-的设计"><a href="#14-4-1-execute-的设计" class="headerlink" title="14.4.1 execute 的设计"></a>14.4.1 execute 的设计</h3><p><code>/improve execute</code> 是唯一碰代码的命令，唯一偏离&quot;improve 不碰源码&quot;的地方。但它很克制：</p><ol><li>在隔离的 git worktree 里开全新上下文。</li><li>派一个廉价执行 Agent，只给它目标和计划文件。</li><li>执行 Agent 按计划写代码、跑验证门禁、报告结果。</li><li>执行完后，improve 用强模型审查 diff，确认改动严格符合计划，没多干，没漏验证。</li></ol><p>有一个人的决策点：审查通过后 diff 摆在你面前，你决定合不合。improve 不替你 commit，不开 PR，不 merge。它把执行自动化了，接受权在你手里。和第 11 章 kanbots 的&quot;晋升永远是手动操作&quot;同一个道理：代码最终要有人对它负责。</p><h3 id="14-4-2-实战：一个开发者的一小时"><a href="#14-4-2-实战：一个开发者的一小时" class="headerlink" title="14.4.2 实战：一个开发者的一小时"></a>14.4.2 实战：一个开发者的一小时</h3><p>原理和命令都讲完了。下面走一遍真的——假设你维护一个 TypeScript monorepo，<code>packages/</code> 下十几个子包，pnpm + vitest + tsup。你想看看代码库里藏着什么债。</p><p><strong>第 1 步：装 improve。</strong></p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">$ npx skills add shadcn/improve</span><br></pre></td></tr></table></figure><p>几秒装完。不需要配置，不需要 API key，不需要连什么外部服务。它就是一个技能文件加一组指令，装进你已有的 Agent。</p><p><strong>第 2 步：跑一次全面审计。</strong></p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">$ /improve</span><br></pre></td></tr></table></figure><p>Agent 开始干活了。先吐出来的是 Recon 摘要——它读了 <code>package.json</code>、<code>tsconfig.json</code>、<code>.github/workflows/ci.yml</code>、<code>pnpm-workspace.yaml</code>，把技术栈和构建命令摸清楚了。你扫一眼，没问题，等它继续。</p><p>接下来几分钟终端持续滚动。九个子智能体在并行跑，每个盯一个维度。你会看到进度提示：<code>[Audit] correctness... done.</code>、<code>[Audit] security... done.</code>、<code>[Audit] performance... running...</code>。总时间差不多等于最慢的那个维度，通常两三分钟。</p><p><strong>第 3 步：看 Vet 结果。</strong></p><p>Audit 跑完，improve 自动切到 Vet。它把 Audit 报的每一条发现重新读一遍源码，验证是不是真的。停下来的输出是这样的：</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line">[Vet] 32 findings → 23 confirmed, 6 rejected, 3 merged</span><br><span class="line"></span><br><span class="line">Rejected (false positives):</span><br><span class="line"> ✗ SEC-03: https_proxy in src/fetch.ts:10 flagged as SSRF</span><br><span class="line"> → By-design: standard proxy convention. Added to veto log.</span><br><span class="line"> ✗ TYPE-01: strict:false in tsconfig.json flagged as missing type safety</span><br><span class="line"> → Monorepo root config. Sub-packages each enable strict independently.</span><br></pre></td></tr></table></figure><p>被踢掉的写进了 <code>plans/.veto-log.md</code>。下次审计这两个位置直接跳过。你注意到 23 个确认发现里有些你看一眼就知道是边角料——变量命名可以更好、注释可以补一补。快速往下翻，找那些你也不知道存在的问题。</p><p><strong>第 4 步：看 Prioritize 排序表。</strong></p><p>Vet 结束，Prioritize 把 23 条发现排成了一张表。前面几行是这样的：</p><table><thead><tr><th>#</th><th>发现</th><th>分类</th><th>位置</th><th>影响</th><th>工作量</th><th>杠杆率</th></tr></thead><tbody><tr><td>1</td><td><code>migrate-icons.ts:168</code> 图标迁移循环内全量扫描，O(n²)</td><td>性能</td><td>perf-04</td><td>中</td><td>S</td><td><strong>很高</strong></td></tr><tr><td>2</td><td><code>getShadowConfig</code> 逻辑在 <code>search.ts</code> 和 <code>view.ts</code> 里分别实现，已有偏离</td><td>技术债</td><td>debt-02</td><td>中</td><td>M</td><td>高</td></tr><tr><td>3</td><td>CI 只跑 <code>packages/core</code>，<code>packages/cli</code> 零覆盖</td><td>测试</td><td>test-01</td><td>高</td><td>M</td><td>高</td></tr><tr><td>4</td><td><code>colorUtils.ts:34</code> 暴露了内部函数 <code>parseAlpha</code>，公开 API 已覆盖</td><td>技术债</td><td>debt-07</td><td>低</td><td>S</td><td>中</td></tr><tr><td>...</td><td>...</td><td>...</td><td>...</td><td>...</td><td>...</td><td>...</td></tr></tbody></table><p>你在这张表前面花了五分钟。不是看每条发现是什么——而是判断哪条值得现在修。发现 #1 工作量 S 杠杆率很高，闭着眼勾。发现 #2 你之前隐约感觉两处代码有重复但没细查过，improve 证实了而且偏离已经在发生，勾。发现 #3 是真实问题但需要写一整组 CI 测试，今天不想干这个，标记一下以后回来。发现 #4 和后面的十几条要么影响太低、要么你现在有别的事，不勾。</p><p><strong>第 5 步：看生成的 Plan。</strong></p><p>你勾了 #1 和 #2。improve 为每条生成一个 markdown 计划文件。你打开 <code>plans/001-fix-icon-migration-o-n2.md</code>：</p><figure class="highlight markdown"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br></pre></td><td class="code"><pre><span class="line">---</span><br><span class="line">id: PLAN-001</span><br><span class="line">title: 修复 migrate-icons.ts 的 O(n²) 图标迁移</span><br><span class="line">category: performance</span><br><span class="line">effort: S</span><br><span class="line"><span class="section">based<span class="emphasis">_on_</span>commit: e4f8a2c</span></span><br><span class="line"><span class="section">---</span></span><br><span class="line"></span><br><span class="line"><span class="section">## 现状</span></span><br><span class="line"><span class="code">`packages/cli/src/migrate-icons.ts:168`</span> 对每个待迁移的图标文件</span><br><span class="line">在整个文件系统里做正则搜索，循环嵌套，文件多时 O(n²)：</span><br><span class="line"></span><br><span class="line">// migrate-icons.ts:165-175</span><br><span class="line">for (const file of iconFiles) &#123;</span><br><span class="line"> const pattern = new RegExp(escapeRegex(file.oldName), &#x27;g&#x27;)</span><br><span class="line"> for (const target of allProjectFiles) &#123; // 内层全量扫描</span><br><span class="line"><span class="code"> ...</span></span><br><span class="line"><span class="code"> &#125;</span></span><br><span class="line"><span class="code">&#125;</span></span><br><span class="line"><span class="code"></span></span><br><span class="line"><span class="section">## 目标</span></span><br><span class="line">将内层循环替换为一次性构建的全局替换映射，单次遍历所有文件。</span><br><span class="line"></span><br><span class="line"><span class="section">## 修改范围</span></span><br><span class="line"><span class="bullet">-</span> packages/cli/src/migrate-icons.ts，约 165-200 行</span><br><span class="line"><span class="bullet">-</span> 新增 packages/cli/src/<span class="strong">__tests__</span>/migrate-icons.test.ts</span><br><span class="line"></span><br><span class="line"><span class="section">## 验证</span></span><br><span class="line"><span class="bullet">1.</span> pnpm --filter @shadcn/cli typecheck —— 零错误</span><br><span class="line"><span class="bullet">2.</span> pnpm --filter @shadcn/cli test -- --grep &quot;migrate&quot; —— 全过</span><br><span class="line"><span class="bullet">3.</span> pnpm --filter @shadcn/cli lint —— 零警告</span><br><span class="line"></span><br><span class="line"><span class="section">## STOP 条件</span></span><br><span class="line"><span class="bullet">-</span> migrate-icons.ts 在 commit e4f8a2c 之后有改动，停，报告</span><br><span class="line"><span class="bullet">-</span> 改动涉及 packages/cli/src/ 下超过 2 个文件，停，报告</span><br><span class="line"><span class="bullet">-</span> 任一验证步骤连续失败 2 次，停，报告</span><br></pre></td></tr></table></figure><p>你扫了一眼。路径对。命令对。STOP 条件合理。份量够一个人（或一个 Haiku）30 分钟内干完。你把这份文件也扔给旁边新来的同事看了一眼，他点点头——项目他完全不了解，但这份计划他看得懂要改哪里、怎么验证、什么情况该停。</p><p><strong>第 6 步：执行计划。</strong></p><p>你决定先修 #1。</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">$ /improve execute plans/001-fix-icon-migration-o-n2.md</span><br></pre></td></tr></table></figure><p>improve 在隔离 worktree 里切出一个干净分支，派 Haiku 干活。你的终端开始滚动：</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br></pre></td><td class="code"><pre><span class="line">[Execute] Worktree created at .worktrees/improve-001/</span><br><span class="line">[Execute] Executor: Haiku (cheapest available)</span><br><span class="line">[Execute] Reading plan... applying changes...</span><br><span class="line">[Verify] pnpm typecheck... PASS</span><br><span class="line">[Verify] pnpm test --grep &quot;migrate&quot;... 3 passed, 0 failed</span><br><span class="line">[Verify] pnpm lint... PASS</span><br><span class="line">[Review] Diff review by Opus... PASS</span><br><span class="line"> → Changes strictly match plan scope</span><br><span class="line"> → No unplanned modifications detected</span><br><span class="line"> → All verification gates passed</span><br><span class="line"></span><br><span class="line">Diff ready for review. Accept? [y/N]</span><br></pre></td></tr></table></figure><p><strong>第 7 步：审 diff，合入。</strong></p><p>你打开 diff 看了一眼。改了一个文件，新建了一个测试文件，改动范围刚好在 165-200 行，测试覆盖了 3 个边界情况。没有顺手改别的。你敲了 <code>y</code>。commit 落地，worktree 自动清理。</p><p>第 2 个计划 <code>plans/002-extract-shadow-config.md</code> 你决定下午再跑。一样的流程——<code>/improve execute</code>，等两分钟，审一眼 diff，合。</p><p><strong>一个小时下来你做了什么。</strong></p><p>你打了两次 <code>/improve execute</code>。看了两张表（Prioritize 排序表、diff）。在 Prioritize 表前花了五分钟想&quot;现在修哪个&quot;。其余所有事——读代码库、找问题、验证真伪、排优先级、写执行手册、切 worktree、跑验证门禁、审查产出——全是 Agent 干的。强模型干了一次性的、判断密集的活（审计、核实、排优先级、写计划、审查 diff），弱模型干了重复的、跟随指令的活（敲代码、跑测试）。你的时间是花在了只有你能做的两件事上：决定什么值得修，确认修得对不对。</p><h2 id="14-5-安全边界"><a href="#14-5-安全边界" class="headerlink" title="14.5 安全边界"></a>14.5 安全边界</h2><p>improve 有几条硬边界，写在指令里，不是建议。</p><p><strong>不修改源码。</strong> 审计和计划阶段只读。分析代码、记录位置、写计划，写操作只在 <code>plans/</code> 目录。这个边界让它能在任何代码库上安全跑，无论是个人项目还是生产环境核心服务。</p><p><strong>不改动工作树。</strong> 审计在当前 checkout 上读，计划写到 <code>plans/</code>。不切分支，不 stash，不改任何工作状态。跑完一次 improve，<code>git status</code> 唯一的变化是 <code>plans/</code> 下多了几个 untracked 文件。</p><p><strong>不复现 secret 值。</strong> 审计发现硬编码密钥（这也是安全审计的一项），只记录文件路径、行号和密钥类型，比如 <code>src/config.ts:15 — AWS_ACCESS_KEY_ID</code>，不把密钥值拷进计划。计划引用行号，执行者读源文件，密钥值不会在 markdown 里到处复制。</p><p><strong>拒绝&quot;帮我实现&quot;。</strong> 对它说&quot;帮我实现这个计划&quot;，标准回答：我不实现任何东西。要执行计划用 <code>/improve execute</code>。要改进计划，描述你的疑虑。别让我即兴写代码。</p><p>这四条的意义不只在安全。它们定义了一种信任模型：improve 能在任何代码库上放心跑，因为它能造成的最坏结果是 <code>plans/</code> 下多几个 markdown 文件。这种只读的安全性，是它和&quot;让我帮你重构整个项目&quot;那类 Agent 最根本的区别。</p><h2 id="14-6-与全书方法论的对接"><a href="#14-6-与全书方法论的对接" class="headerlink" title="14.6 与全书方法论的对接"></a>14.6 与全书方法论的对接</h2><p>improve 单看是一个技能，放进全书的方法论地图，补了几个空白。</p><p><strong>和第 3 章 SDD。</strong> improve 的&quot;计划即产品&quot;是规格驱动的极致版：规格不是开发的输入，规格就是交付物。OpenSpec 和 Spec-Kit 把规格当人和 AI 的合约，improve 把这份合约写到弱模型能照做的粒度。同根，improve 走得更远。</p><p><strong>和第 8 章 Goal Workflow 互补。</strong> <code>/improve plan</code> 类似 <code>/prd-to-spec</code>，都是模糊需求到精确方案。方向不同：Goal Workflow 从人的需求往下游走（&quot;我想要这个&quot;），improve 从已有代码往上游走（&quot;这个代码库还缺什么&quot;）。<code>/improve execute</code> 类似 <code>/goal</code>，都是规格变代码，但 improve 显式分离了计划模型和执行模型。两个流程能拼起来：improve 审计产出一批 plan，Goal Workflow 的 <code>/goal</code> 逐个实现，<code>/review-it</code> 审查，<code>/ship-it</code> 交付。</p><p><strong>和第 12 章 Loop Engineering 上下游。</strong> improve 可以当 Loop 里的&quot;审计-排序&quot;环节。Loop 定时触发 improve 做审计，产出排序后的计划，自动化层挑高杠杆率的派给执行循环。知识生产（improve）和执行调度（Loop）分开，各自用最合适的模型。</p><p><strong>和第 13 章 GSD Core 分工。</strong> GSD 管全阶段循环（Discuss → Plan → Execute → Verify → Ship），improve 只管前半段（审计和计划），执行留给别的工具。不冲突，一条链上的不同环节。GSD 管怎么做一个功能，improve 管该做哪些功能。一个负责过程可靠，一个负责方向正确。</p><p><strong>和第 15 章 Compound Engineering。</strong> improve 的 <code>plans/</code> 目录是一个在累积的知识库。每次审计的误报清单让下一次更准，已完成计划的记录让 reconcile 能自动检测漂移。Recon 阶段读取的意图文档也在持续更新，审计随项目演进变精准。这和 Compound Engineering 的核心主张一样：每次工作让下次更容易。</p><p><strong>和第 33 章 &#x2F;review-it 互补。</strong> improve 是事前主动审计，还没动手先想清楚。review-it 是事后审查，做完了回来检查。两个方向都重要，结合起来就是一个完整的质量闭环：improve 告诉你该做什么、怎么写，&#x2F;goal 实现，&#x2F;review-it 验货。</p><h2 id="14-7-本章小结"><a href="#14-7-本章小结" class="headerlink" title="14.7 本章小结"></a>14.7 本章小结</h2><p>improve 把一个简单的经济逻辑做成了一个完整的工作流：贵的模型做判断，便宜的做执行。但它真正贡献的不是省钱，是重新定义了什么东西值得用最强模型。</p><p>Recon → Audit → Vet → Prioritize → Plan，五步流水加九类并行审计加加权杠杆率排序。它是一条&quot;该做什么&quot;的生产线，输出不是代码，是决策。写得够细的决策，细到一个人或一个弱模型能照着做到底。</p><p>&quot;计划即产品&quot;背后是一整套工程纪律：自包含上下文、机器可校验的验证门禁、硬 STOP 条件、Git Commit 戳、漂移检查。这些纪律回答一个问题：你不亲自写代码，怎么确保写的人不会搞砸？答案是把判断力蒸馏进计划，不只告诉它做什么，告诉它怎么判断做得对不对。</p><p>shadcn 把这个项目开源不到一周 5000+ star。社区的热情不是因为新技术，并行子智能体、验证门禁、worktree 隔离这些前面都讲过了。热的是它的主张：AI 编程的成本不必是刚性的。你不用为了质量把 Opus 用在每一行代码上。让 Opus 做它最擅长的，理解、判断、规划，执行外包给便宜的。在 AI API 按 token 计费的现实里，这个主张比任何架构模式都更直接地改变了你的开发成本。</p><p>最后，improve 最值得记的，不是它的命令和流水线。计划不是代码的附属品。计划是独立的、可积累的、随项目演进的知识资产。写好计划，今天能执行，下周能执行，换了三个 Agent 之后还能执行。</p>