improve

核心思路

把「智能」用在复利最高的环节——理解代码库、判断什么值得做、写规格——执行交给更便宜的模型。计划本身就是产品，质量决定执行成败。

你（昂贵模型）  →  /improve              理解、判断、写 spec
plans/          →  001-fix-n-plus-one.md   自包含规格
其他代理（廉价）  →  实现、测试、交付        按 plan 执行

仓库地址：github.com/shadcn/improve · 本地路径：/Users/admin/Repos/improve

安装

npx skills add shadcn/improve

适用于任何支持 Agent Skills 格式的代理。产出的计划是纯 Markdown，任意代理或人类都能接手。

仓库结构

运行时产物（在被审计的目标仓库，非本 repo 内）：

plans/
  README.md          # 索引、依赖图、状态表
  001-<slug>.md
  002-<slug>.md

Skill：improve

工作流

Phase 1 — Recon（侦察）

• 读 README、CLAUDE.md/AGENTS.md、CI、包管理配置
• 确定 build / test / lint 命令（成为每份 plan 的验证门）
• 吸收 ADR、PRD、CONTEXT.md、DESIGN.md、PRODUCT.md 等意图文档
• 看 git 信号（churn 热点、近期变更）

Phase 2 — Audit（审计）

按 audit-playbook.md 九类并行子代理审计。每个 finding 需 file:line 证据、影响、工作量（S/M/L）、置信度。

审计深度由调用关键词决定：

Phase 3 — Vet & Prioritize（验证与排序）

• 顾问亲自复核每个 finding（子代理易误报）
• 按 leverage（影响 ÷ 工作量 × 置信度）排序
• 方向类 finding 单独呈现，等用户选择再写 plan

Phase 4 — Write Plans（写计划）

按 plan-template.md 写 plans/NNN-slug.md + plans/README.md 索引。摘录必须来自顾问自己的阅读，非子代理报告。每份 plan 记录 Planned at git SHA，执行前做 drift check。

九类审计类别

详见 skills/improve/references/audit-playbook.md

1. 1Correctness / Bugs — 错误处理、async 竞态、空值流、边界条件、并发、资源泄漏
2. 2Security — 凭证卫生、注入、访问控制、输入校验、依赖漏洞、生产配置
3. 3Performance — N+1、错误复杂度、缓存缺口、payload 体积、构建/CI 慢
4. 4Test Coverage — 关键路径未测、高 churn 无测、测试质量、验证基础设施
5. 5Tech Debt & Architecture — 重复、分层违规、死代码、God object、模式不一致
6. 6Dependencies & Migrations — 主版本滞后、废弃 API、废弃依赖、重复依赖
7. 7DX & Tooling — 缺失/损坏的 typecheck、lint、formatter、pre-commit
8. 8Docs — README 过时、API 文档缺失、注释与代码漂移
9. 9Direction — 功能与产品方向建议（必须有仓库内证据，禁止泛泛而谈）

调用方式

典型首次使用

1. 在目标仓库运行 /improve（或 /improve quick 控制成本）
2. 从 findings 表选择要规划的项，例如「plan 1, 3 and 5」
3. 审阅 plans/ 下的文件与索引
4. 交给任意代理实现，或 /improve execute 001 让 skill 派执行者
5. 下次会话 /improve reconcile 清理 backlog

PR 前可用 /improve branch，只审计分支变更范围。

计划的三项可执行属性

计划写给「最弱可想象的执行者」——从未见过顾问会话、可能更小的模型。

闭环工作流

详见 skills/improve/references/closing-the-loop.md

• execute <plan> 在隔离 worktree 派执行子代理；顾问重跑 done criteria、查 scope、读 diff。裁决：APPROVE / REVISE（最多 2 轮）/ BLOCK。合并始终由用户决定。
• reconcile DONE 抽查、BLOCKED 调查重写、TODO 刷新漂移、REJECTED 退役。
• --issues 用 gh issue create 发布计划。公开仓库对安全类 finding 需用户确认。

Reference 文档

• audit-playbook.md 九类审计检查项、finding 格式、优先级 rubric。Phase 2 子代理 prompt 必须引用。
• plan-template.md 计划结构（Status、Why、Current state、Steps、Done criteria、STOP conditions）、索引格式、质量检查清单。
• closing-the-loop.md execute 派发与复审流程、reconcile 状态机、GitHub Issues 发布规则。

硬规则

与目标仓库文档的协作

若被审计仓库已有 ADR（docs/adr/）、CONTEXT.md、DESIGN.md、PRODUCT.md 等，improve 会读取并用于：

• Vet — 已决策的不算 finding
• Direction — 建议 grounded 于 stated product intent
• Plan — 匹配文档词汇与设计系统

示例 Findings

对 shadcn/ui 的真实审计产出：

示例计划：examples/001-extract-shadow-config-resolution.md — 含当前代码摘录、精确步骤、repo 自身的 test/lint 命令作为验证门、以及 reality 不匹配时的 STOP 条件。