Agent Skills
返回列表
贴合上下文的命名

贴合上下文的命名

开发编程 更新于 2026.08.30

将以下提示词粘贴到你的 AI 对话框中:

请根据 https://skillhub.cn/install/skillhub.md,安装 @user_c283aad7/gy7。

技能介绍

命名烂掉时,问题往往不在「想不出词」

变量、类型、模块、API 字段如果叫得泛、叫得隐喻过重,或者把当前实现细节写进名字里,后续重构时名字会立刻撒谎。读者也会误用:把「工具函数」当成「领域概念」,把临时数据结构当成长期契约。这类问题在存量代码库里尤其常见,因为命名习惯是局部上下文决定的,照搬通用词典里的「好听词」往往格格不入。

技能如何工作

本技能把「起名」当成一次小型设计评审,而不是随机造词:

  1. 先看周边:对照同目录、同模块、同层的既有命名(前缀、后缀、粒度、动词/名词习惯)。
  2. 再定边界:弄清这个概念负责什么、作用范围多大、主要读者是谁(维护者、调用方、终端用户文案等)。
  3. 偏无聊、偏具体:在可读的前提下,优先能直接回答「它代表什么」的名字,少用宽泛或强隐喻。
  4. 别绑死实现:避免把很可能变的细节(具体存储、某次优化的数据结构、临时算法名)编码进标识符。
  5. 主观就摊开说:当多种命名都合理时,给出 3~7 个候选,并写清各自取舍(长度、歧义、与现有 API 的一致性等)。

好的名字应当让误用更难发生:说明「是什么」,而不是「当前代码碰巧怎么算出来的」。

适用边界

  • 适合:新模块/新类型/新接口字段、重构后需要改名、团队内命名风格不统一时的对齐讨论。
  • 不适合:替代产品对外品牌命名、法律商标检索,或需要大量创意营销文案的场景;也不会替你拍板组织级命名规范,只能在给定上下文里给出建议。

使用场景

  • 拆分单体服务时,为新包路径下的领域类型起名,需与相邻模块的动词前缀和名词粒度一致
  • 为 REST 资源新增字段,要在不暴露存储实现的前提下与现有 JSON 键名风格对齐
  • 重构把 `processData` 拆成多步后,需要区分编排函数与纯计算函数的职责命名
  • Code Review 里同事质疑标识符过泛,需列出若干候选名并说明歧义与一致性取舍

适合人员

  • 维护十年老仓库的后端工程师,每次加类型都要对照同目录既有 `*Service` / `*Repository` 习惯
  • 负责对外 SDK 的库作者,希望公开 API 名称稳定、不让调用方误把内部 helper 当契约
  • 带队做模块边界划分的 Tech Lead,需要在 PR 讨论里给出可比较的命名方案而非拍脑袋
  • 全栈开发者在前后端共享 DTO 命名时,要对齐字段语义且避免把 ORM 列名直接暴露给前端