code-refinement

代码精炼工作流

从六个维度分析并提升不断演进的代码质量。

快速开始

/refine-code
/refine-code --level 2 --focus duplication
/refine-code --level 3 --report refinement-plan.md

适用场景

• 快速 AI 辅助开发冲刺后
• 重大版本发布前（质量门禁）
• 代码“能运行，但有异味”时
• 为提升清晰度而重构现有模块
• 减少不断演进的代码中的技术债务

不适用场景

• 移除 无用/未使用的代码（使用 conserve:bloat-detector）

分析维度

#	维度	模块	检查内容
1	重复与冗余	duplication-analysis	几乎相同的代码块、相似函数、复制粘贴
2	算法效率	algorithm-efficiency	可用 O(n) 解决却使用 O(n^2) 的情况、不必要的迭代
3	代码整洁度问题	clean-code-checks	方法过长、嵌套过深、命名不佳、魔法值
4	架构契合度	architectural-fit	范式不匹配、违反耦合原则、抽象泄漏
5	反劣质模式	clean-code-checks	过早抽象、装腔作势的企业级设计、空洞模式
6	错误处理	clean-code-checks	裸露的 except、吞掉错误、仅处理正常路径
7	增量偏见	imbue:justify	用变通方案代替根因修复、篡改测试、不必要的增补

插件专属模式

适用于插件和技能代码库的检测模式，可发现 标准代码质量启发式方法会遗漏的结构性问题。

委托存根正文

某个技能声明“委托给 X”，却仍保留完整模板正文， 说明它身兼数职。委托技能应是一个精简包装器（少于 30 行）， 负责将请求路由到目标。若委托技能正文超过 50 行，则标记出来。

模块膨胀

若技能包含 10 个或更多模块文件，且其中 40% 或以上的内容 存在重叠，则标记出来。警示信号：两个模块从不同角度覆盖 相同的 API 范围（例如，都描述相同的配置选项 或相同的 CLI 标志）。

过大的单体模块

将超过 500 行的单个模块文件标记为拆分或精简的候选项。大型模块 会破坏渐进式加载，因为即使只需要部分信息，也必须读取整个文件。

失效的 Python 引用

技能引用了 Python 命令（python -m module.name 或 python -c "from module import ..."），但被引用的 模块在插件的 src/ 目录中不存在。这些是指向已重命名或已移除代码的过期引用。

渐进式加载

根据精炼重点加载模块：

• modules/duplication-analysis.md（约 400 个 token）：重复检测与整合
• modules/algorithm-efficiency.md（约 400 个 token）：复杂度分析与优化
• modules/clean-code-checks.md（约 450 个 token）：整洁代码、反劣质模式、错误处理
• modules/architectural-fit.md（约 400 个 token）：范式对齐与耦合

全面精炼时加载全部模块。针对特定问题时，仅加载相关模块。

必需的 TodoWrite 项

1. refine:context-established：确定范围、语言和框架
2. refine:scan-complete：完成所有维度的检查并记录发现
3. refine:prioritized：按影响和工作量对发现进行排序
4. refine:plan-generated：生成包含前后对比的具体重构计划
5. refine:evidence-captured：按照 imbue:proof-of-work 编制证据附录
6. refine:findings-verified：通过 citation_verifier.py 确认引用
7. refine:execution-complete：关闭所有列入波次的候选项，或说明不处理的理由（仅当调用内容包含“execute findings”或更强要求时才必需；参见步骤 6）

工作流

步骤 1：确定上下文（refine:context-established）

检测项目特征：

# Language detection
find . -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
  -not -path "*/node_modules/*" -not -path "*/.git/*" \
  \( -name "*.py" -o -name "*.ts" -o -name "*.rs" -o -name "*.go" \) \
  | head -20

# Framework detection
ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null

# Size assessment
find . -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
  -not -path "*/node_modules/*" -not -path "*/.git/*" \
  \( -name "*.py" -o -name "*.ts" -o -name "*.rs" \) \
  | xargs wc -l 2>/dev/null | tail -1

步骤 2：维度扫描（refine:scan-complete）

加载相关模块，并根据层级执行分析。 对于维度 7（增量偏见），运行 Skill(imbue:justify) 以计算偏见分数、检查是否遵守铁律， 并标记不必要的增补或变通方案。

步骤 3：确定优先级（refine:prioritized）

按以下标准排列发现项：

• 影响：质量提升幅度（高／中／低）
• 工作量：修改的行数、涉及的文件数（小／中／大）
• 风险：引入 Bug 的可能性（低／中／高）

优先处理影响高、工作量小、风险低的项目。

步骤 4：生成计划（refine:plan-generated）

针对每个发现项，提供：

• 文件路径和行范围
• 锚点：所引用行中的原文
• 当前代码片段
• 建议的改进
• 理由（对应的原则／维度）
• 预估工作量

步骤 5：采集证据（refine:evidence-captured）

使用 imbue:proof-of-work 记录（如果可用）：

• 每个发现项的 [E1]、[E2] 引用
• 可衡量指标的改进前／后数据
• 标明违反的原则

备用方案：如果未安装 imbue，则在报告中直接记录证据，使用相同的 [E1] 引用格式，不集成 TodoWrite。

步骤 6：执行发现项（refine:execution-complete）

步骤 1-5 产出的是计划。步骤 6 产出的是结项记录。两者都是该技能的一部分。除非用户明确表示“仅计划”，否则执行不会停在规划阶段。

执行模式判定

将用户的调用措辞与此表匹配，以确定执行范围：

用户所说的内容	模式	停止条件
/code-refinement（未指定其他条件）	仅计划	步骤 5 后
--dry-run 或“仅规划”	仅计划	步骤 5 后
“执行发现项”／“应用修复”	规划并执行第 1 波	所有工作量小且风险低的发现项都已结项后
“执行所有发现项”／“所有阶段”／“所有波次”	规划并执行每一波	每个发现项（或每个列出的波次候选项）都已通过提交结项，或在综合记录中有明确的逐项理由后
“忽略范围限制”	覆盖分支规模限制	分支指标不限制执行；越过红色区域后继续
“不要停下来，直到完成”／“直到全部……完成”	期间不做摘要	只有当综合记录中的每个波次候选项都已结项或有明确理由时，才宣布完成

触发条件可以组合：--tier 3 --execute all findings --ignore-scope-guard 表示无论分支规模如何，都要将第 2 波和第 3 波的每个候选项执行至结项。

完成门槛（启用执行模式时）

只有满足以下所有条件，任务才算完成：

1. 第 2 波候选项（综合记录“第 2 波候选项”部分中列出的中等工作量项目）：每个项目都必须有结项提交，或在综合记录中有明确的逐项说明，解释为什么不可行。
2. 第 3 波候选项（综合记录“第 3 波候选项”部分中列出的大型工作量项目）：要求相同。用户要求“执行所有项目”时，不要以泛泛的“需要专门的 PR”为由提前推迟大型工作量项目。执行机械性项目（按类拆分、mixin 包、模块合并），仅将需要架构层面决策的项目（模式更改、新增依赖声明、新建 venv 布局）列为“推迟”。
3. 更新综合记录：docs/refinement/<date>/00-synthesis.md 记录每个结项的提交 SHA，以及每个延期项目的一句话理由。

Agent 自身的反模式检测器

如果模型在执行过程中发现自己正在做以下任何事情，这就是停止钩子泄漏。返回并继续执行发现项：

反模式	判定方式
“第 2 波已完成。开始第 3 波。”（中途摘要）	过早发出任务完成信号：继续工作
机械性项目尚未全部完成，就开始“记录延期项目及理由”	以文书记录为由跳过执行
仍有 >0 个列出的候选项未结项且没有明确理由，却撰写完成摘要	违反完成门槛
用户的调用中包含“不要停下来”，却再次询问用户“是否继续？”	无视明确要求，不得在任务中途做摘要

门禁的判定依据

门禁读取的是记录，而不是 Agent 对自身工作的陈述： .review/findings.json 和引用验证器的退出代码（见 下一节）用于确定哪些候选项已关闭，综合结果会列出其余项。执行次数受 max_waves 限制（默认值为 3，每轮遍历未解决候选项一次）。预算用尽或 运行框架发出停止信号时，运行即停止：将所有剩余候选项记录在综合结果中， 作为差距，并说明如何才能关闭这些差距，然后结束本轮。停止信号发出后， 不要继续运行。运行框架的停止信号来自运行之外；若运行无视该信号，就等于 让自己充当完整性的裁判，而研究发现这种安排会导致偏移（arXiv 2607.17641）。

验证发现有依据（refine:findings-verified）

将发现写入 .review/findings.json，运行引用验证器 （Skill(imbue:review-core) 第 5 步），并删除验证器拒绝的发现，或将其标记为 UNVERIFIED。

退出标准

• 针对目标范围的全部六个分析维度都有判定（发现问题或“未检测到问题”）。
• 每项发现都包含文件路径、行范围和逐字的 Anchor（该行的确切源文本）。
• 每项报告的发现都带有经过 citation_verifier.py 确认的 Location + 逐字的 Anchor（退出代码为 0），否则应删除未验证的 发现或将其标记为 UNVERIFIED。

分级分析

级别	时间	范围
1：快速（默认）	2-5 分钟	复杂度热点、明显重复、命名、魔法值
2：针对性	10-20 分钟	算法分析、全面重复扫描、架构一致性
3：深入	30-60 分钟	以上全部内容，以及跨模块耦合、范式适配性、全面规划

跨插件依赖

依赖项	必需？	回退方案
imbue:proof-of-work	可选	在报告中内联证据
conserve:code-quality-principles	可选	内置 KISS/YAGNI/SOLID 检查
archetypes:architecture-paradigms	可选	仅进行基于原则的检查（不检测范式）

支持模块

• 代码质量分析 - 重复检测命令和整合策略

未安装可选插件时，此技能会正常降级：

• 没有 imbue：内联记录证据，不使用 TodoWrite 工作证明
• 没有 conserve：使用内置的整洁代码检查（子集）
• 没有 archetypes：跳过特定范式的一致性检查，仅使用耦合/内聚原则