naming-refactor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Naming Refactor

命名重构

If these instructions are already present in the conversation from a slash or dollar invocation, follow them directly; do not invoke this skill again through a skill tool.

Make every name in the current repository communicate one coherent domain model, regardless of refactor cost.

如果对话中已经存在来自斜杠或美元符调用的这些指令，请直接遵循；不要通过技能工具再次调用此skill。

让当前仓库中的每个名称都传达出一个连贯的领域模型，无论重构成本如何。

Contract

契约

Cover the complete current Git repository. Do not narrow the run to selected files or stop after a candidate cap.
Preserve features, runtime behavior, side effects, performance-sensitive characteristics, and externally consumed contracts. Large diffs, path moves, and repository-controlled interface migrations are allowed.
Treat an exported surface as repository-controlled only when every consumer is in scope and can migrate atomically. Preserve other API names, CLI flags, environment variables, configuration keys, wire fields, routes, database names, and import paths unless the user explicitly authorizes a breaking migration.
Fix a bug discovered during the refactor only when the defect and intended behavior are clear and a regression check can prove the fix. Keep bug fixes in a distinct change wave and report them separately.
Preserve pre-existing work. Local edits, file moves, directory restructuring, and non-destructive validation are authorized. Do not commit, push, publish, or write externally unless the user or repository instructions require it.
Serialize implementation and verification against intersecting repository writes. Complete codebase analysis and the refactor plan first, then acquire a coordination scope covering the complete worktree before the first edit. If no reliable coordination mechanism is available, require the user to confirm an exclusive write window instead.
A verified no-op is valid only after exhaustive coverage. Do not rename a clear, conventional name merely to create churn, but do not retain a weak name to minimize diff size.

覆盖当前完整的Git仓库。不要将范围缩小到选定文件，也不要在达到候选上限后停止。
保留功能、运行时行为、副作用、性能敏感特性以及外部消费的契约。允许大差异、路径移动以及仓库控制的接口迁移。
仅当所有消费者都在范围内且可以原子化迁移时，才将导出表面视为仓库控制的内容。保留其他API名称、CLI参数、环境变量、配置键、网络字段、路由、数据库名称和导入路径，除非用户明确授权破坏性迁移。
仅在缺陷和预期行为明确且回归检查可以证明修复有效性的情况下，修复重构过程中发现的Bug。将Bug修复放在单独的变更阶段并单独报告。
保留已有的工作内容。允许本地编辑、文件移动、目录重组以及非破坏性验证。除非用户或仓库指令要求，否则不要提交、推送、发布或向外部写入内容。
针对交叉的仓库写入操作，序列化实现与验证流程。首先完成代码库分析和重构计划，然后在首次编辑前获取覆盖完整工作区的协调范围。如果没有可靠的协调机制，则要求用户确认独占写入窗口。
只有在全面覆盖后，经过验证的无操作才是有效的。不要仅仅为了制造变更而重命名清晰、符合惯例的名称，但也不要为了最小化差异而保留不合理的名称。

Coverage Ledger

覆盖记录

Resolve

scripts/naming-ledger.py

relative to this

SKILL.md

and create its ledger outside the repository:

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

The helper maps every tracked and non-ignored untracked path and records pre-existing worktree state. Account for a path only after inspecting its name, relevant contents, and role:

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

Use

retained

when the current name is justified,

renamed

when the path or its contents joined a verified rename,

excluded

for generated, vendored, binary, or bulk artifacts validated through their source or invariant, and

blocked

when behavior or contract safety cannot be established.

excluded

and

blocked

require reasons.

For delegated runs, have each subagent write a dispositions TSV outside the repository with one record per line:

status<TAB>repo-relative-path<TAB>reason

. Apply each file in one batch:

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

Dispositions paths are relative to the repository root and must match ledger entries exactly. The ledger maps only tracked and non-ignored untracked files; gitignored artifacts, cache files, and bare directories are never ledger paths. Unknown paths fail the batch closed. Rerun with

--skip-unknown

only after reviewing the reported paths and confirming that every skip is intentional, then verify the result's

skipped

list.

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>

Refresh after path moves and before final validation. New paths become pending; removed paths remain in the ledger and must be accounted as renamed, excluded, or blocked. The run is complete only when the helper reports no pending or blocked paths.

相对于此

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在仓库外部写入一个处置TSV文件，每行一条记录：

status<TAB>仓库相对路径<TAB>理由

。批量应用每个文件：

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

处置路径相对于仓库根目录，必须与记录条目完全匹配。记录仅映射已跟踪和未被忽略的未跟踪文件；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>

在路径移动后和最终验证前刷新记录。新路径会变为待处理状态；已移除的路径仍保留在记录中，必须被标记为已重命名、已排除或已阻止。只有当助手报告没有待处理或已阻止的路径时，运行才完成。

Ground the Refactor

为重构奠定基础

Read applicable repository instructions. Record the repository root, starting commit and status, build and check commands, generated sources, and ownership boundary for pre-existing changes.
Initialize the ledger and establish baseline format, lint, type, test, build, codegen, API-snapshot, or smoke checks appropriate to the repository. Attribute existing failures before editing.
Identify external contracts, repository-controlled consumers, reflection and serialization surfaces, dynamic imports, case-insensitive filesystem constraints, and language-aware rename tooling.
Derive canonical domain vocabulary from behavior, types, data flow, documentation, tests, and relevant history. History resolves unclear intent; it does not override the current design.

Completion of this phase requires a recorded baseline, explicit contract boundaries, and a ledger covering the entire repository.

阅读适用的仓库指令。记录仓库根目录、起始提交和状态、构建与检查命令、生成的源文件以及已有变更的所有权边界。
初始化记录，并建立适合仓库的基准格式、lint、类型检查、测试、构建、代码生成、API快照或冒烟检查。在编辑前记录现有失败情况。
识别外部契约、仓库控制的消费者、反射和序列化表面、动态导入、大小写不敏感的文件系统约束以及支持语言感知的重命名工具。
从行为、类型、数据流、文档、测试和相关历史中推导规范的领域词汇。历史用于解决模糊的意图，但不会覆盖当前设计。

此阶段完成需要记录基准、明确的契约边界以及覆盖整个仓库的记录。

Build the Rename Map

构建重命名映射

Inspect every ledger path and build an evidence-backed map before changing each coherent domain slice. Cover directories, files, packages, modules, namespaces, exports, types, classes, functions, methods, parameters, variables, booleans, constants, tests, fixtures, documentation, configuration, scripts, and CI.

Apply these rules together:

Give one concept one canonical term; give distinct concepts distinct terms.
Name by domain role, behavior, ownership, lifecycle, units, and polarity rather than incidental implementation.
Replace misleading, overloaded, contextless, or generic names such as
```
data
```
,
```
info
```
,
```
item
```
,
```
manager
```
,
```
process
```
,
```
handle
```
, and
```
utils
```
when a specific name is supported by evidence.
Align directory, filename, primary export, and module responsibility. Move paths when the current structure obscures ownership or forces names to compensate for poor context.
Preserve required language, framework, protocol, and ecosystem idioms. Do not perform a repository-wide casing or synonym rewrite when existing terminology is already coherent.

For every rename group, record the old and new concept, rationale, contract classification, affected consumers, collision risks, dynamic string references, migration order, and proving checks. Resolve ambiguity through symbol and reference inspection before choosing a name. Never use blind global replacement for an overloaded term.

Completion of this phase requires every non-excluded path to be retained with a reasoned naming model, assigned to a validated rename group, or marked blocked with concrete evidence.

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

同时应用以下规则：

为一个概念赋予一个规范术语；为不同的概念赋予不同的术语。
根据领域角色、行为、所有权、生命周期、单位和极性命名，而非偶然的实现细节。
当有证据支持特定名称时，替换误导性、重载、无上下文或通用的名称，如
```
data
```
、
```
info
```
、
```
item
```
、
```
manager
```
、
```
process
```
、
```
handle
```
和
```
utils
```
。
使目录、文件名、主导出项和模块职责保持一致。当当前结构模糊了所有权或迫使名称弥补不良上下文时，移动路径。
保留必要的语言、框架、协议和生态系统惯例。当现有术语已经连贯时，不要进行仓库范围的大小写或同义词重写。

对于每个重命名组，记录新旧概念、理由、契约分类、受影响的消费者、冲突风险、动态字符串引用、迁移顺序和验证检查。在选择名称之前，通过符号和引用检查解决歧义。永远不要对重载术语使用盲目的全局替换。

此阶段完成需要每个非排除路径要么通过合理的命名模型被保留，要么被分配到已验证的重命名组，要么被标记为已阻止并附有具体证据。

Acquire the Implementation Scope

获取实现范围

After completing the codebase analysis and rename map, present the evidence-backed refactor plan, including its rename groups, dependency waves, contract boundaries, risks, and proving checks. Before editing, use the repository's coordination mechanism to acquire a claim covering the complete worktree. For

ai-coord

, run

ai-coord start 'naming refactor' '.'

and proceed only after it returns

READY

;

BLOCKED

UNKNOWN

, and pathless

INTENT

results do not authorize edits and cannot be overridden by user confirmation. Hold the claim through final verification.

After acquiring the claim, re-read the current commit and worktree status, refresh the ledger, and compare the repository with the recorded baseline. Reinspect every path whose content or presence changed during analysis, then update the rename map, contract boundaries, and proving checks before implementing. The ledger refresh detects path changes, not content changes to existing paths.

If the repository has no reliable coordination mechanism, ask the user to confirm that no other coding agent will write to the repository through implementation and verification. Stop until the user explicitly confirms that fallback window; do not infer it from a stable worktree, absent processes, or the initial invocation.

完成代码库分析和重命名映射后，提交有证据支持的重构计划，包括重命名组、依赖阶段、契约边界、风险和验证检查。在编辑前，使用仓库的协调机制获取覆盖完整工作区的权限。对于

ai-coord

，运行

ai-coord start 'naming refactor' '.'

，仅在返回

READY

后继续；

BLOCKED

、

UNKNOWN

和无路径的

INTENT

结果不授权编辑，且不能通过用户确认覆盖。在最终验证期间保持该权限。

获取权限后，重新读取当前提交和工作区状态，刷新记录，并将仓库与记录的基准进行比较。重新检查分析期间内容或存在状态发生变化的每条路径，然后在实现前更新重命名映射、契约边界和验证检查。记录刷新会检测路径变化，但不会检测现有路径的内容变化。

如果仓库没有可靠的协调机制，请用户确认在实现和验证期间没有其他编码agent会向仓库写入内容。在用户明确确认此备用窗口之前停止；不要从稳定的工作区、不存在的进程或初始调用中推断。

Execute in Verified Waves

分阶段验证执行

With the implementation scope active, apply rename groups in coherent dependency waves. Keep every delegated write within the same coordination ownership. If scope ownership is lost or an uncovered writer appears, stop before continuing.

Prefer language-server, compiler, or AST-aware rename support for symbols. Use exact text replacement only after proving each occurrence has the same meaning.
Move a tracked path with a repository-safe mechanism that does not stage unrelated work. Use an intermediate path for case-only renames on case-insensitive filesystems.
Update definitions, consumers, imports, re-exports, tests, fixtures, docs, examples, configuration, CI, selectors, reflection, serialization, and generated sources in the same wave.
Change generated output through its generator or schema, then regenerate and verify it. Do not edit vendored sources.
Run the narrowest proving checks after each wave. Fix attributable failures before continuing; if parity cannot be established, revert only that wave's edits without repository-wide reset, clean, checkout, or stash commands.
Mark ledger paths only after the wave is verified. Refresh the ledger after moves so new paths enter coverage.

Continue until every planned rename is applied or blocked; refactor cost, diff size, and elapsed time are not stopping criteria.

在实现范围生效后，按连贯的依赖阶段应用重命名组。确保每个委托写入都在同一协调所有权范围内。如果失去范围所有权或出现未覆盖的写入者，请在继续前停止。

优先使用语言服务器、编译器或支持AST感知的重命名工具处理符号。仅在证明每次出现都具有相同含义后，才使用精确文本替换。
使用仓库安全的机制移动已跟踪路径，不要暂存无关工作。在大小写不敏感的文件系统上，对仅更改大小写的重命名使用中间路径。
在同一阶段更新定义、消费者、导入、重新导出、测试、夹具、文档、示例、配置、CI、选择器、反射、序列化和生成的源文件。
通过生成器或模式更改生成的输出，然后重新生成并验证。不要编辑供应商提供的源文件。
在每个阶段后运行最窄范围的验证检查。在继续前修复可归因的失败；如果无法建立一致性，仅回滚该阶段的编辑，不要执行仓库范围的重置、清理、检出或暂存命令。
仅在阶段验证通过后标记记录路径。移动后刷新记录，使新路径进入覆盖范围。

继续执行，直到所有计划的重命名都已应用或被阻止；重构成本、差异大小和耗时不是停止标准。

Final Verification and Report

最终验证与报告

Refresh the ledger, inspect every new path, and repeat the semantic naming pass until it finds no material naming issue. Search for stale old names and paths, including case variants and non-code literals. Run aggregate repository checks and compare them with baseline; no new unexplained failure is acceptable. Verify stable external contracts through available API snapshots, schemas, CLI help, import surfaces, or focused smoke tests.

Lead success with

### ✅ Naming refactor complete — <rename groups> groups · <accounted>/<mapped> paths accounted

. Report exact file and directory moves, every public or exported rename, compact local-identifier group counts, baseline-versus-final checks, intentional retained external names, incidental bug fixes, and residual risks. Keep commands, paths, names, diagnostics, and contract identifiers exact and undecorated.

If the ledger is incomplete, behavior parity is unproven, or an external contract would require unapproved breakage, lead with

### ⛔ Naming refactor incomplete

and report the blocking evidence and required decision. Do not describe the run as complete while any path remains pending or blocked.

刷新记录，检查每条新路径，并重复语义命名检查，直到未发现实质性命名问题。搜索过时的旧名称和路径，包括大小写变体和非代码文字。运行聚合仓库检查并与基准进行比较；不允许出现任何新的无法解释的失败。通过可用的API快照、模式、CLI帮助、导入表面或聚焦的冒烟测试验证稳定的外部契约。

成功完成时以

### ✅ 命名重构完成 — <重命名组数量>个组 · <已统计路径数>/<已映射路径数>条路径已统计

开头。报告确切的文件和目录移动、每个公共或导出项的重命名、简洁的本地标识符组计数、基准与最终检查对比、有意保留的外部名称、附带的Bug修复以及剩余风险。确保命令、路径、名称、诊断信息和契约标识符准确且无修饰。

如果记录不完整、行为一致性未被证明或外部契约需要未经批准的破坏性变更，则以

### ⛔ 命名重构未完成

开头，并报告阻止证据和所需决策。当任何路径仍处于待处理或已阻止状态时，不要将运行描述为已完成。