dafang
7.6 KiB
name, description, argument-hint
| name | description | argument-hint |
|---|---|---|
| cs-refactor | 行为等价的重构、拆分、性能优化。会改变外部可观察行为的诉求走 cs-feat 或 cs-issue。 | [重构目标] |
cs-refactor
改结构，不改行为，并且能证明行为没变。
开工
- 有
.codestable/attention.md就先读。 - 按目标模块关键词检索
.codestable/lessons/、项目文档，以及存在的 v1 只读知识目录：.codestable/roadmap/、.codestable/features/、.codestable/issues/、.codestable/refactors/、.codestable/goals/、.codestable/compound/、.codestable/audits/、.codestable/brainstorms/、.codestable/feedback/；命中要报告来源路径。上述 v1 目录不得继续生成、原地改写或批量迁移，新结论按归属进入 v2 Epic、项目文档、ADR 或 lesson。 - 先确认诉求真是行为不变：一旦包含"顺便支持 X / 改成 Y"，把那部分拆出去转
cs-feat或cs-issue，不夹带。 - 结构好坏用深度衡量：小接口承载大行为是深，接口和实现一样复杂是浅；重构应让调用方用更少认知换更多能力，不为"看起来干净"搬家，不把模块越拆越碎。
持续学习
检索到 lesson 后先做 read-repair。只做一次有界、最低成本的定向核实，优先读取已有代码、测试或
canonical 文档；不得仅为核实 lesson 运行大范围测试或反复复现。仍不足时跳过该 lesson，不阻塞正常任务。
只有 scope 符合、未退役、当前事实成立，并真实改变计划或验证，或明确排除一个具体且合理的错误路径
的条目才算有效命中；按
经验命中：{path}（{status}）；核验：{fact}；影响：{plan_or_check} 报告。retired 不应用；
observed / validated 先核实再用；旧 lesson 缺 status 按 observed 读取，不批量迁移。只是相关
但没有改变行为时不制造复用证据；当前事实明确反证时立即停止应用，证据不足时不猜。
任务内只在内存保留最多 3 条候选，按新证据替换低价值项，不暂停或询问。强信号只包括：owner 纠正实际改变方案/代码/术语/验证；可复现证据推翻根因；同一路径失败两次后更换假设； blocking/important finding 暴露未编码不变量；新 red -> green 捕获可复发失败；lesson 真实改变本次行为 或被反证；重复 workaround；方法显著降低重试、成本或风险。
候选还必须同时有可追溯证据、能写成未来动作、适用于本次精确 diff 之外、且没有现成 canonical owner。网络波动、拼写、泛化口号、活动记录，以及已被机械 owner 完整覆盖的事实直接丢弃。
创建、改写规则/scope、晋升、删除与跨项目反馈仍须用户显式授权。为不中断 read-repair，仅对已有且
有效命中的 lesson 开放两种窄维护：observed -> validated 仅在独立后续任务确实采用并验证成功时
发生，只补一次代表性证据；必须记录 lesson 实际改变的计划或验证，或明确排除的具体且合理错误路径，
以及本次通过的验收证据。observed|validated -> retired 仅在当前仓库事实直接反证或发现已有
canonical owner 时发生，只写原因与替代/反证指针。窄维护不新建事实、不改规则、不扩 scope、不新增
gate，随当次代码、证据和
游标进入同一语义原子 milestone；稳定 validated 命中不写文件。需要改写结论或证据不足时只给
候选，新结论不得通过复活 retired 条目获得 validated 身份；窄维护必须在最终报告列出文件变化。
当前任务范围内能直接落成 red -> green 测试/checker 的约束优先机械化，不另写重复 lesson；会扩大
范围时只给候选。用户已明确说“记住 / 更新 / 退役”时，同轮按 cs-keep 处理，不重复确认。普通任务
只在强信号成立时展示最高价值一条，首行固定 晶化候选：{rule}，并给出证据、范围和建议归宿；无
强信号完全不显示模板，没有记忆写入授权时不落盘。
硬门槛
- 先有能自证等价的验证，再动代码：覆盖目标行为的测试、类型检查或可对照的输出基线。没有就先补验证或与用户确认等价判据，不许裸改。
- 行为等价是底线：过程中发现必须改变外部可观察行为时停下报告，让用户决定转向，不擅自继续。
- 分步改，每步之后跑验证；全部完成后跑完整验证并附输出。验证变红时先恢复绿再继续。
风险升级
跨模块大范围重构、改公开 interface 内部实现、或影响性能敏感路径时，动手前先给用户一页改动清单（动哪些点、顺序、每步验证方式）确认。完成后默认由当前主流程创建一个 fresh reviewer，让其单轮执行 cs-review，reviewer 内不得再创建子 agent；仅微小整理可说明后跳过。主流程处理 findings，需要复审时重新创建 reviewer，累计最多 3 轮；超限仍有 blocking 或分歧时交用户裁决，不得继续对轮或宣称完成。
- 当前主流程创建 reviewer 前，先发现当前会话可调用的 subagent 创建与管理能力。项目上下文有显式创建方式/model 约束时先遵守。达到审查质量基线后，优先选择与实现者异构的 agent，并显式指定最强稳定
model；创建方式依次使用受管理的结构化委派能力、宿主 subagent、本机有界 agent CLI 回退，不得只扫 PATH。 - 没有合格异构候选时回退同构最强模型。把最终创建方式、agent/model 与回退原因写入 task packet，禁止依赖默认模型。
- 审查前冻结一个明确目标（diff review 优先 staged diff，也可用明确 range/patch；design review 冻结对应文档版本；audit 冻结 commit + 范围标识），把目标标识写入 task packet；reviewer 返回前不改目标或对应工作树。有 blocking 或未被用户明确接受的 important 时不提交当前候选，也不得创建正式里程碑 commit；处理后重跑验证、重新冻结审查目标并创建 fresh reviewer。
- 仅在跨会话恢复、agent 交接或隔离 reviewer 需要不可变基线时，且已有 commit 授权，才可在私有工作分支创建明确标记的 WIP/checkpoint commit；它不代表 review 通过或任务完成，交付前按仓库策略 fixup/squash。
- 本 skill 的确认与验证门槛均满足、blocking 清零且其余 important 已处理或被用户明确接受后，已有 commit 授权时才创建语义原子的正式里程碑 commit；未获授权则只报告可提交状态，不自行提交。
- reviewer 创建后绑定该运行并记录 run identity：目标有效、能力仍满足，且 reviewer 状态为 running，或
Awaiting携带可查询的同一 run identity 且查询仍为活动态时为健康；状态健康时等待终态报告，不因后来发现更优创建方式而取消、重复创建或并行补发。仅在运行明确失败或终止无报告、idle /Awaiting且无可恢复 run identity、能力不满足或目标失效时，本轮失败且不计轮次；不得盲目重发，先检查 task packet 与 agent 状态，再决定一次有界重试、更换创建方式或交用户。
收尾
- 报告：改了什么结构、等价性证据（验证输出）、遗留事项。
- 需要跨会话继续时写
.codestable/work/refactor-{slug}.md（目标 / 现场 / 边界 / 证据 / 验收 / 状态与未决六节；work 文档一律带类型前缀）。完成后先在报告列毕业去向（结论进哪、lesson 沉哪，或明说无可毕业）再删除；目标位置不存在时在清单中建议落点请用户拍板，拍板前不删。用户要求留档则保留。