用途
readability-method 是一个仅关注代码可读性的规范化技能（canonical readability-only plan）。它使用 clean-code-agent 重写源代码以提升可读性，同时保证不改变代码行为。它适用于需要清理代码风格、改善命名与结构的场景，但不负责更深层的结构性重构——这类改动应交回调用方的开发计划。
主要能力
- 变量/函数重命名：将含义模糊的名称改为具有领域含义的名称。
- 删除样板注释：移除复述代码的注释、空 docstring。
- 添加 why-comments：为非显而易见的业务逻辑补充说明性注释。
- 结构简化：扁平化嵌套、移除冗余抽象、合并逻辑。
明确不做的事：不重排代码、不提取函数、不更改 API、不移除错误处理/校验/导入、不修改测试文件、不过度简化。
使用方式
技能从 $ARGUMENTS 确定目标：若为文件路径则清理该文件；若为目录则清理其中所有源文件；过滤掉测试文件（除非它们引用了被重命名的符号）。随后列出待清理文件及其语言。
执行流程：
- 识别目标。
- 建立验证基线：通过检查项目文件检测可用的类型检查器、测试运行器和 linter，并运行它们捕获 stdout 与 stderr，记录基线。检测方式包括 tsconfig.json（tsc --noEmit）、mypy.ini/pyrightconfig.json 或 pyproject.toml 中的 mypy/pyright（mypy . 或 pyright）、Cargo.toml（cargo check）、go.mod（go vet ./...）；测试运行器包括 package.json（npm test）、pyproject.toml 或 setup.py（pytest）、Cargo.toml（cargo test）、go.mod（go test ./...）、带 test 目标的 Makefile（make test）；linter 包括 ruff.toml 或 pyproject.toml 中的 ruff 配置（ruff check）、.eslintrc* 或 eslint.config.*（eslint）、Cargo.toml（cargo clippy）。
- 预览变更：--dry-run 时仅预览；目标为超过 3 个文件的目录时先显示预览；--yes 时在显示预览后直接应用。预览会逐文件列出重命名、删除的样板注释、添加的 why-comments、结构简化，并给出总变更数与文件数，提供“应用全部/仅应用到特定文件/取消”选项。
- 应用变更：在独立隔离上下文中调度 clean-code-agent，传入文件列表与已批准的变更。
- 验证与报告：按类型检查器、测试、linter 的顺序重新运行所有检测到的工具；对在基线中通过但之后失败的文件进行回退；对每个被重命名的符号，在 .json、.yaml、.yml、.toml、.env、.cfg、.ini、.xml、.html、.md 中搜索旧名称并作为警告报告。最后输出修改文件数、各类变更计数、验证结果与陈旧引用。
安全与恢复机制
技能要求加载 project-protocol:project-protocol 技能以执行 preflight、基线、候选门禁与恢复。需捕获所拥有文件的精确编辑前内容，包括已有编辑与未跟踪文件。失败时使用按路径范围的恢复；硬重置需要独占拥有的干净隔离工作区并捕获 pre_phase_sha。远程检查需与候选快照及命令/配置/任务身份匹配。不得覆盖其他写入者的后续编辑。
限制
- 硬门禁：若既无测试也无类型检查器，则停止并提示用户选择取消（推荐先建立测试或类型检查）或使用 --force 继续。仅 --yes 不能绕过此门禁，只有 --force 可以。
- 若变更后任何验证失败，通过通用协议恢复精确保存的编辑前内容，保留已有编辑，并在遇到外部写入者冲突时停止。
- --strict 标志会额外标记无法自动修复的剩余可读性问题。
- 更深层的结构性变更需交回调用方的开发计划，本方法仅应用可读性改动。
适用场景
适用于已有测试或类型检查器、希望在不改变行为的前提下提升代码可读性的项目。对于缺乏验证工具的项目，需谨慎使用 --force。