naming-refactor

命名重构

如果斜杠命令或 dollar 调用已将这些说明加入对话，请直接遵循这些说明。在这种情况下，不要再次通过技能工具调用此技能。

无论重构成本如何，都要确保当前仓库中的每个名称都表达一致的领域模型。

约定

• 覆盖当前 Git 仓库的全部内容。不要将运行范围缩小到选定文件，也不要在达到候选数量上限后停止。
• 保留功能、运行时行为、副作用、对性能敏感的特性以及外部使用的约定。允许产生大型差异、移动路径以及迁移由仓库控制的接口。
• 只有当所有使用方都在范围内且可以原子性迁移时，才将导出接口视为由仓库控制。除非用户明确授权进行不兼容迁移，否则保留其他 API 名称、CLI 标志、环境变量、配置键、线上字段、路由、数据库名称和导入路径。
• 只有在缺陷和预期行为明确，且回归检查能够证明修复有效时，才修复重构过程中发现的错误。将错误修复放在单独的变更波次中，并单独报告。
• 保留已有工作。允许进行本地编辑、文件移动、目录重组和非破坏性验证。除非用户或仓库说明要求，否则不要提交、推送、发布或向外部写入。
• 对相互影响的仓库写入操作，必须串行执行实现和验证。先完成代码库分析和重构计划，然后在每个波次开始前，按“获取实现范围”中的定义认领累计写入集。
• 只有在穷尽检查后，才可确认无需更改。不要仅为制造改动而重命名清晰、惯用的名称，但也不要为了缩小差异而保留含糊的名称。

覆盖范围台账

相对于此 SKILL.md 解析 scripts/naming-ledger.py，并在仓库外创建台账：

uv run "<skill-dir>/scripts/naming-ledger.py" init --root <repo> --ledger <scratch.json>

此辅助工具会映射所有已跟踪和未被忽略的未跟踪路径，并记录已有工作区状态。只有检查了路径名称、相关内容和作用后，才能处理该路径：

uv run "<skill-dir>/scripts/naming-ledger.py" mark \
  --ledger <scratch.json> --status <pending|retained|renamed|excluded|blocked> \
  --path <path> [--path <path>...] [--reason <text>]

当当前名称合理时，使用 retained；当路径或其内容已加入经过验证的重命名时，使用 renamed；当生成文件、供应商文件、二进制文件或批量文件已通过其源文件或不变量验证时，使用 excluded；当无法确认行为或约定是否安全时，使用 blocked。excluded 和 blocked 必须说明原因。

对于委派运行，让每个子 Agent 在仓库外写入一个 dispositions TSV 文件，每行一条记录： status<TAB>repo-relative-path<TAB>reason。并发的 mark 和 refresh 调用会通过旁路文件 <scratch.json>.lock 串行化。从协调会话中一次性批量应用每个文件：

uv run "<skill-dir>/scripts/naming-ledger.py" mark \
  --ledger <scratch.json> --from-file <dispositions.tsv>

子 Agent 应将计划中但尚未验证的重命名报告为 pending。波次验证完成后，使用 --pending-as renamed（或其他最终状态）应用其文件，而不是重写 TSV。原因保持不变，excluded 或 blocked 仍必须说明原因。

dispositions 中的路径相对于仓库根目录，且必须与台账条目完全匹配。台账仅映射已跟踪和未被忽略的文件。被 Git 忽略的产物、缓存文件和裸目录都不是台账路径。未知路径会导致整个批次安全失败。只有在审查所报告的路径并确认每项跳过都符合预期后，才能使用 --skip-unknown 重新运行，然后检查结果中的 skipped 列表。

uv run "<skill-dir>/scripts/naming-ledger.py" pending --ledger <scratch.json> [--limit <n>]
uv run "<skill-dir>/scripts/naming-ledger.py" refresh --ledger <scratch.json>
uv run "<skill-dir>/scripts/naming-ledger.py" summary --ledger <scratch.json>

路径移动后、最终验证前刷新台账。新路径会变为待处理状态。已移除的 retained 路径会恢复为待处理状态。已移除的路径仍保留在台账中，必须标记为 renamed、excluded 或 blocked。只有当辅助工具报告没有待处理或受阻路径时，本次运行才算完成。

梳理重构依据

1. 阅读适用的仓库说明。记录仓库根目录、起始提交和状态、构建与检查命令、生成的源文件，以及对预先存在的更改的归属边界。
2. 初始化台账，并根据仓库情况建立格式、lint、类型、测试、构建、代码生成、API 快照或冒烟检查的基线。编辑前归因已有失败。
3. 识别外部契约、由仓库控制的使用方、反射与序列化边界、动态导入、大小写不敏感文件系统的限制，以及语言感知的重命名工具。
4. 根据行为、类型、数据流、文档、测试和相关历史推导规范的领域词汇。历史可用于澄清意图，但不能凌驾于当前设计之上。

完成此阶段需要记录基线、明确契约边界，并建立覆盖整个仓库的台账。

制定重命名映射

检查台账中的每条路径，并在更改每个连贯的领域切片之前，建立有证据支持的映射。覆盖目录、文件、包、模块、命名空间、导出项、类型、类、函数、方法、参数、变量、布尔值、常量、测试、夹具、文档、配置、脚本和 CI。

同时遵循以下规则：

• 一个概念对应一个规范术语。不同概念使用不同术语。
• 根据领域角色、行为、归属、生命周期、单位和极性命名，而非依据偶然的实现细节。
• 有证据支持具体名称时，替换具有误导性、含义过宽、脱离上下文或过于通用的名称，例如 data、info、item、manager、process、handle 和 utils。
• 使目录、文件名、主要导出项与模块职责保持一致。若当前结构模糊了归属，或迫使名称弥补上下文缺失，则调整路径。
• 保留语言、框架、协议和生态系统所需的惯用写法。现有术语已一致时，不要在整个仓库范围内统一大小写或改写同义词。

对每组重命名，记录旧概念和新概念、理由、契约分类、受影响的使用方、冲突风险、动态字符串引用、迁移顺序和验证检查。通过检查符号及其引用来消除歧义，再选择名称。绝不要对含义过宽的术语进行盲目的全局替换。

完成此阶段需要为每条未排除的路径保留有理由的命名模型、分配到已验证的重命名组，或根据具体证据标记为受阻。

获取实施范围

完成代码库分析和重命名映射后，提交有证据支持的重构计划，包括重命名组、依赖波次、契约边界、风险和验证检查。每个波次开始前，使用仓库的协调机制认领累积写入集：包括已写入的所有路径，以及该波次的定义、通过搜索找到的使用方、移动路径的两端和递归移动的目录。遗漏前序波次路径的认领无效。只有在无法枚举某个波次的使用方时（例如重命名一个无处不在的标识符或移动顶层目录），才认领整个工作树（--recursive '.'）。

对于 ai-coord，运行 ai-coord start 'naming refactor' <paths>... [--recursive <dir>]...，且只有在其返回 READY 后才能继续。BLOCKED、UNKNOWN 和不含路径的 INTENT 结果均不授权编辑，也不能由用户确认予以覆盖。持有认领直到最终验证完成。

获取认领后，重新读取当前提交和工作树状态，刷新台账，并将仓库与记录的基线进行比较。重新检查分析期间内容或存在状态发生变化的每个路径，然后在实施前更新重命名映射、契约边界和验证检查。台账刷新能够检测路径变化，但无法检测现有路径的内容变化。由于其他写入者可能修改未认领的路径，每个波次开始前以及最终验证期间，都要重新搜索旧名称，并将新发现的使用方纳入认领。

如果仓库没有可靠的协调机制，请用户确认在实施和验证期间，没有其他编码 Agent 会写入该仓库。在用户明确确认这一备用时段之前，停止操作。不要根据工作树稳定、没有发现相关进程或首次调用时的情况推断用户已确认。

分波次执行并验证

在实施范围生效后，按连贯的依赖波次应用重命名组。所有委派的写入都必须在已认领的写入集内。如果失去范围所有权，或其他写入者开始修改已认领的路径，请在继续之前停止。

• 对符号重命名，优先使用语言服务器、编译器或支持 AST 的重命名工具。只有在证明每处匹配含义相同后，才使用精确文本替换。
• 使用不会暂存无关工作内容的仓库安全机制移动受版本控制的路径。在大小写不敏感的文件系统上仅大小写不同的重命名，应使用中间路径。
• 在同一波次中更新定义、使用方、导入、重新导出、测试、固定数据、文档、示例、配置、CI、选择器、反射、序列化和生成的源代码。
• 通过生成器或架构更改生成的输出，然后重新生成并验证。不要编辑供应商提供的源代码。
• 每个波次结束后运行范围最小的验证检查。继续之前，修复可归因于该波次的问题。如果无法确认一致性，只还原该波次的更改；不要使用全仓库重置、清理、检出或暂存命令。
• 只有在波次通过验证后，才标记台账中的路径。移动路径后刷新台账，使新路径纳入覆盖范围。

持续执行，直到所有计划的重命名均已应用或受阻。重构成本、差异大小和耗时都不是停止条件。

最终验证与报告

刷新台账，检查每个新路径，并重复语义命名检查，直到不再发现实质性命名问题。 搜索过时的旧名称和路径，包括大小写变体和非代码字面文本。运行仓库级检查，并 与基线进行比较。任何新增且无法解释的失败都不可接受。通过可用的 API 快照、架构、CLI 帮助、导入接口或有针对性的冒烟测试，验证稳定的外部契约。

成功时，以 ### ✅ Naming refactor complete — <rename groups> groups · <accounted>/<mapped> paths accounted 开头。 报告精确的文件和目录移动、每一项公开或导出的重命名、简洁的局部标识符分组计数、 基线与最终检查结果、有意保留的外部名称、附带修复的 Bug，以及剩余风险。命令、路径、名称、诊断信息和契约标识符必须保持原样，不得加修饰。

如果台账不完整、无法证明行为一致，或外部契约需要未经批准的破坏性变更，则以 ### ⛔ Naming refactor incomplete 开头，并报告阻塞证据和所需决策。只要仍有任何路径处于待处理或受阻状态，就不得将此次运行描述为已完成。