函数注释与命名体检 Skill

--- name: code-comment description: 扫描 Python 源码找出缺文档串的公共函数、参数过多的函数、过长的函数体、魔法数字与含糊命名，生成一份待补清单，让代码交接不再靠口口相传。 --- # 函数注释与命名体检 Skill ## 触发条件 当要交接项目、做代码评审、或觉得某个模块读起来费劲却说不清哪里费劲时触发。 ## 执行步骤 1. 运行 python scripts/comment_todo.py src/ -o code_report.md（也支持单文件）。 2. 先看缺文档串的公共函数，那是最该补注释的地方，私有小工具函数可以放过。 3. 处理超长函数：优先拆分而不是加注释，注释救不了结构问题。 4. 魔法数字抽成常量并命名，含糊变量名改成能表达用途的词。 5. 补完重跑确认清单收敛，脚本只做静态扫描，不判断逻辑正确性。 ## 依赖 Python 3 标准库（ast/re/argparse/pathlib），不执行被测代码、不导入模块。 ## 输出 一份 code_report.md：缺注释函数清单、超长与多参数函数清单、魔法数字位置、命名建议表。