메뉴
代码优化的子流程入口，处理"行为不变、结构变"的工作（结构 / 性能 / 可读性），按 scan → design → apply 分步执行每步人工放行。触发：用户说"优化一下 / 重构 / 重写 / 拆一下 / 性能不行 / 代码太长"且不夹带行为改动。不处理新需求 / bug / 跨模块架构重划。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
维护 `.kflow/architecture/` 这份只记现状的系统地图，三种模式 update / check / backfill。触发：用户说"刷新 architecture"、"做架构检查"、"补这个模块的架构文档"、"方案和代码对得上吗"，或 feature 阶段需要先做架构动作。不写未来规划（走 k-roadmap）。
feature 流程阶段 3——验收闭环：对照 design 核实现 + 回写 architecture / requirement / roadmap，最后产出 {slug}-acceptance.md。触发：用户说"功能写完了验收一下"、"做最后检查"、"准备 merge"、"出验收报告"。前置依赖 k-feat-impl 完成。
feature 流程阶段 1——为新功能起草 {slug}-design.md 作为后续实现和验收的唯一输入，拍板后抽出 checklist。触发：用户说"开始设计方案"、"写 design doc"、"准备实现 XX"，前提是已知道做什么、为谁、怎么算成功。
feature 流程阶段 2——按 {slug}-checklist.yaml 里 design 切好的 paradigm 维度 steps 推进，每步具体改哪个文件由 implement 自决，写完用统一格式汇报。触发：用户说"方案确认了开始实现"、"按方案写代码"、"开工"。前提是 design 已 approved 且有 checklist。遇到方案外情况要回方案谈不要硬冲。
issue 流程阶段 2——读 report + 读代码定位根因、评估风险，给用户 2-3 个修复方案让 TA 拍板。这一步不改代码。触发：用户说"分析这个 bug"、"找根因"、"定位问题"，且已有 {slug}-report.md。
issue 流程阶段 3——按已确认根因和方案定点修复、验证、写 {slug}-fix-note.md 落档。两个入口：标准路径从 analyze 来，快速通道从 report 直接来。触发：用户说"开始修 bug"、"按分析修"、"动手改代码"。只动方案声明的文件，不顺手优化。
| name | k-refactor |
| description | 代码优化的子流程入口，处理"行为不变、结构变"的工作（结构 / 性能 / 可读性），按 scan → design → apply 分步执行每步人工放行。触发：用户说"优化一下 / 重构 / 重写 / 拆一下 / 性能不行 / 代码太长"且不夹带行为改动。不处理新需求 / bug / 跨模块架构重划。 |
开始任何判断或动作前，先读取 .kflow/attention.md；缺失则视为骨架不完整，提示先补齐或运行 k-onboard。
AI 自己重构有两个稳定失败模式：一是不知道模块真实需求和约束，改出来的东西功能不等价；二是一次吞掉的范围超过上下文承载，改到后面忘了前面的约束。这流程在"想优化"和"动手改"之间塞了扫描清单 + 方法库，让 AI 只接自己能稳定做对的活。
读取材料遵守
.kflow/reference/shared-token-budget.md。重构默认先锁范围、读目标文件和直接测试，不扫全仓库历史。
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。扫描时先按 L1-L4 分类命中候选，再打开对应方法条目；只有候选横跨多层或要起草 design 时才通读方法库。
{slug}-scan.md 两部分：
reference/scan-checklist-format.md整份交给用户，用户勾选 ✓ / ✗（✗ 写理由）后进阶段 2。不要替用户勾选。
{slug}-scan.md.kflow/reference/shared-testing.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 — 共享口径索引，按需打开具体小文件