From kflow
Guides code refactoring for structure, performance, and readability without behavior changes. Runs scan → design → apply phases with human checkpoints. Activates on 'refactor' type intentions.
How this skill is triggered — by the user, by Claude, or both
Slash command
/kflow:k-refactorThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
开始任何判断或动作前,先读取 `.kflow/attention.md`;缺失则视为骨架不完整,提示先补齐或运行 `k-onboard`。
开始任何判断或动作前,先读取 .kflow/attention.md;缺失则视为骨架不完整,提示先补齐或运行 k-onboard。
AI 自己重构有两个稳定失败模式:一是不知道模块真实需求和约束,改出来的东西功能不等价;二是一次吞掉的范围超过上下文承载,改到后面忘了前面的约束。这流程在"想优化"和"动手改"之间塞了扫描清单 + 方法库,让 AI 只接自己能稳定做对的活。
scan(扫优化点清单)→ design(和用户定做哪几条 + 顺序)→ apply(逐条执行,每步人工放行)
核心纪律:行为等价是底线。一旦会改外部可观察行为 → 不走 refactor,走 feature(需求变)或 issue(bug 修)。
单函数 / 单组件 / 1-3 处优化 / 有测试可自证 / 不需要目视——走完整三阶段太重。触发 k-refactor-ff:直接识别、一次对齐、原地改、跑测试自证,不产 scan / design / checklist。
触发:"小重构"、"快速重构"、"简单优化下 XX 函数"、"直接改"、"别那么多步骤"。
别走 ff:改动跨 > 1 文件 / 预计动点 > 3 处 / 需要目视验证 / 改公开接口(要 Parallel Change)/ 没有测试覆盖 / 跨模块。遇到劝用户走标准流程。ff 开干后发现变复杂切回完整流程从 scan 开始。
.kflow/refactors/{YYYY-MM-DD}-{slug}/
├── {slug}-scan.md ← 阶段 1 优化点清单
├── {slug}-refactor-design.md ← 阶段 2 执行方案
├── {slug}-checklist.yaml ← 阶段 2 生成,阶段 3 推进
└── {slug}-apply-notes.md ← 阶段 3 执行记录
目录命名同 feature / issue。slug 短到一眼看出改的是什么(user-form-split、export-perf)。
为什么单独开目录不混进 features:refactor 产物是"代码当前状态扫描 + 执行记录"时效性强;feature 产物是"为什么这样设计"时效性弱。归档逻辑不一样。
| 阶段 | 产出 | 谁主导 |
|---|---|---|
| 1 scan | scan.md | AI 扫 + 前置检查,用户勾选 |
| 2 design | refactor-design.md + checklist.yaml | AI 起草,用户整体 review |
| 3 apply | 代码改动 + apply-notes.md | AI 执行,每步人工放行 |
阶段间有 checkpoint:scan 不勾选不进 design;design 不放行不动代码;apply 里 HUMAN 验证项不点头不推进下一步。
动笔扫之前先跑一遍。命中任何一条 → 中止 scan,给路由建议,不要硬凑。7 条检查和输出格式见 reference/refusal-routing.md。
零条合法输出——扫完真的没发现值得做的就老实说不要凑。
进 scan 前确认:这次扫哪些文件。默认:
范围里要包含测试文件(用来判断第 2 条前置检查的测试覆盖)。
按方法库四层当模板找:
完整方法库在 reference/methods.md,扫描时全量加载作匹配表。
{slug}-scan.md 两部分:
reference/scan-checklist-format.md整份交给用户,用户勾选 ✓ / ✗(✗ 写理由)后进阶段 2。不要替用户勾选。
{slug}-scan.mdstatus: approved---
doc_type: refactor-design
refactor: {YYYY-MM-DD}-{slug}
status: draft | approved
scope: {扫描范围一句话}
summary: {本次要做的几条是什么,一句话}
---
# {slug} refactor design
## 1. 本次范围
- 从 scan 勾选了哪几条(编号)
- 明确不做的(被 ✗ 的)和理由
- 预估总工作量 / 总风险档位
## 2. 前置依赖
- 测试覆盖补齐(如需)
- 调用方搜索(如需)
- 其他一次性准备
## 3. 执行顺序
按步骤列,每步一块:
- 步骤 N:{一句话动作}
- 引用方法:M-Ln-NN {方法名}
- 具体操作:{照方法库步骤落到本项目具体文件 / 函数}
- 退出信号:{AI 跑什么测试 / HUMAN 看什么页面}
- 验证责任:AI 自证 | HUMAN
- 回滚:{出问题怎么还原,通常 git revert 某步}
## 4. 风险与看点
- 高风险步骤汇总
- 容易出错的点(跨步骤数据流变化等)
---
doc_type: refactor-apply-notes
refactor: {YYYY-MM-DD}-{slug}
---
# {slug} apply notes
## 步骤 1: {动作}
- 完成时间: {date}
- 改动文件: {file list}
- 验证结果: {测试输出 / HUMAN 确认语录}
- 偏离: {无 / 具体描述}
## 步骤 2: ...
{slug}-scan.md 用户已勾选(✓/✗)status: approvedvalidate-yaml.pyk-refactor-ff/SKILL.md — 小重构超轻量通道reference/scan-checklist-format.md — scan 清单条目字段 / 顺序 / 硬约束reference/refusal-routing.md — scan 前置检查 7 条 + 路由表reference/methods.md — 方法库(L1-L4 四层分类).kflow/reference/shared-conventions.md — 跨工作流共享口径npx claudepluginhub kunbo928/kflowCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.