code-clarifier 是一个面向代码可读性的技能,以“只改变代码如何清晰表达、不改变代码做什么”为核心原则,在不改变功能的前提下让代码自文档化、意图更易显露。
用途 用于对刚编写或刚修改的代码进行澄清与文档化。默认聚焦最近修改的代码,除非收到其他指示。
主要能力
- 通过命名揭示意图:重命名变量与参数以表达用途;把魔法值改为具名常量;将晦涩条件提取为谓词函数;通过类型标注、守卫子句或断言让隐含假设显式化。
- 为可读性重构:把长函数拆成读起来像叙述的命名步骤;将复杂条件提取为具名变量或函数;用提前返回消除深层嵌套、凸显正常路径;按逻辑、可预期的方式排列参数、属性与分支;对相关操作做视觉分组,仅在分组不自明时添加分节注释。
- 策略性补充文档:只在命名与结构无法创造价值处添加文档,例如公共函数的 JSDoc/docstring 头(说明做什么、为何存在、在整体中的位置)、类型本身无法表达的参数范围或格式约束、解释文件在代码库中角色的模块级注释,以及用 NOTE、TODO、HACK 前缀标注已知限制与坑点。注释解释“为什么”,不解释“做什么”。
- 遵循项目规范:匹配代码库与 CLAUDE.md 中既有的命名风格、文档格式、导入组织与类型标注模式。
- 避免过度澄清:不添加复述代码的注释;不把简单逻辑碎成过多小函数;不使用超出表意所需的过长命名;不为易变的实现细节写文档而应记录意图;不用“看似有帮助”的抽象掩盖直白逻辑。
使用方式 该技能被描述为自主运行,在代码编写或修改完成后立即进行澄清。其工作流程为:识别最近修改的代码;以首次阅读的视角通读并记录每个困惑点;按影响排序应用改动(先命名,再结构,最后文档);最后验证功能未变且每条注释都有其价值。资料未提供具体安装命令或调用参数。
适用场景 适合在功能开发或修改完成后整理代码可读性、统一命名与文档风格,以及让新读者更快理解代码意图。
限制 资料未提供收费、价格、平台支持范围与效果数据;该技能强调只改表达不改行为,因此不适用于需要变更功能或重构架构的任务。