agentleFS
open-gujiopen-guji/luatex-cn/.claude/skills/refactor/SKILL.md

refactor

Skill127 starsChanged 3 months agoApache-2.0View on GitHub

清理重构代码 (Code cleanup and refactoring)

195 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use ascii-diagram, debug-fix and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • SethGammonSkill

    ascii-diagram

    Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow. Uses a programmatic character-grid approach so alignment is guaranteed by math, not token prediction. Includes post-render verification.

    Also in 4 projects that use this

  • zebbernSkill

    debug-fix

    Find and fix a bug or issue — from any source (GitHub issue, error message, user report, or observed behavior)

    Also in 4 projects that use this

  • parcadeiSkill

    agent-context-isolation

    Agent Context Isolation

    Also in 3 projects that use this

  • parcadeiSkill

    agentica-infrastructure

    Reference guide for Agentica multi-agent infrastructure APIs

    Also in 3 projects that use this

  • +8 more from parcadei

The file

Files
SKILL.md

代码清理与重构

以资深程序架构师的视角审视项目代码,使其更整洁、更模块化、更易维护。

重构原则

按优先级排列:

1. 删除死代码

  • 找出未被调用的函数和未使用的变量
  • 搜索方式:用 Grep 搜索函数名/变量名,确认只有定义没有调用
  • Lua 文件:检查 local function 和 module 导出的函数
  • STY 文件:检查 \cs_new 定义的命令是否被使用

2. 提取重复代码

  • 在同一文件或相关文件中找到高度相似的代码段
  • 提取为通用函数,放到合适的工具模块中
  • 命名清晰,参数明确

3. 逻辑迁移:STY → Lua

  • 复杂逻辑应放在 Lua 中,STY 只负责命令定义和参数解析
  • STY 文件应尽量薄:定义命令 → 调用 Lua 函数
  • 模式:
    % STY 中:只做参数解析和 Lua 调用
    \NewDocumentCommand{\MyCmd}{O{} m}{
      \lua_now:e { my_module.my_func("\exp_not:n{#1}", "\exp_not:n{#2}") }
    }

4. 使用 Style Stack 管理样式

  • 格式和样式的设置应通过 style stack 来管理
  • 避免全局变量传递样式参数
  • 查看 tex/core/ 中 style stack 的现有用法作为参考

5. 模块职责单一

  • 每个模块(文件)负责一个独立功能
  • 与该功能相关的所有代码都应集中在该模块中
  • 如果发现某个功能的代码散落在多个不相关的文件中,应该收拢

6. 文件大小控制

  • 单个文件超过 400~600 行时,必须考虑拆分
  • 按子功能拆分为多个文件
  • 通过 require (Lua) 或 \RequirePackage (STY) 组织

7. 命令复用

  • 如果一个命令可以由其他命令组合实现,优先复用
  • 避免重复实现已有功能

执行流程

Phase 1: 分析 (不改代码)

  1. 扫描目标模块
    • 读取目标文件,理解其功能和结构
    • 统计行数,标记过大的文件
  2. 识别问题
    • 用 Grep 搜索未使用的函数/变量
    • 找出重复代码段
    • 标记可以迁移到 Lua 的 STY 逻辑
    • 检查模块职责是否单一
  3. 制定计划
    • 列出所有要做的重构项
    • 按风险从低到高排序
    • 每个重构项作为独立的一步
    • 使用 EnterPlanMode 让用户审批计划

Phase 2: 逐步执行

对每一步重构:

  1. 修改代码
    • 只做当前这一步的改动
    • 保持功能不变
  2. 回归测试
    python3 test/regression_test.py check
    • 所有测试必须 PASSED
    • 如果失败,立即修复或回滚
  3. 提交
    git add <changed-files>
    git commit -m "refactor: <描述这一步做了什么>
    
    Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
  4. 继续下一步

Phase 3: 最终验证

# 运行完整回归测试
python3 test/regression_test.py check --all

如何选择重构目标

如果用户没有指定目标模块,按以下顺序扫描:

# 找出最大的文件
find tex/ -name '*.lua' -o -name '*.sty' | xargs wc -l | sort -rn | head -20

优先处理:

  1. 行数最多的文件
  2. 最近频繁修改的文件 (git log --format='%H' --since='2 weeks ago' -- tex/ | head)
  3. 已知有技术债的模块

注意事项

  • 不要一次改太多 — 每步只做一个类型的重构
  • 测试优先 — 每步改完必须跑回归测试
  • 保持功能不变 — 重构不改变外部行为
  • 先读 LEARNING.md — 避免踩已知的坑
  • STY 中的 expl3 — 遇到展开问题先读 ai_must_read/expl3_note.md
  • 不要改测试文件 — 除非测试本身有问题

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.