Stats
Actions
Tags
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.