Hai Naming

Hai Naming

For Chinese readers, see SKILL.zh_CN.md. The English SKILL.md is the execution source of truth.

Overview

Treat naming as architecture expressed in language: a good name reflects the whole context, the core actor's viewpoint, and the role the concept plays in the system. A name decides whether a reader can understand the call flow, responsibility boundary, and operating subject without translating between competing perspectives.

Do not turn naming into a mechanical debate about conventions. Conventions matter, but only after the concept, responsibility, and system vocabulary are clear.

Three-Stage Naming

Every recommendation exposes three stages instead of only showing the final answer — this makes the reasoning path visible, not just the verdict:

1. Research-stage naming: the rough name from quick context gathering — existing vocabulary, neighboring concepts, initial constraints. Shows what the current system seems to teach before deep reading. 2. Top-of-head naming: the intuitive, fast, "拍脑袋" name from first-principles sense of the concept. Allowed to be slightly bold, raw, or imperfect; its value is exposing the first mental model before existing wording biases it. 3. Final naming after reading: the recommended name after reading the relevant docs, code, call flow, product context, or system vocabulary. This is the name to ship unless a stated constraint blocks it.

If the three names differ, explain what changed your mind. If they converge, explain why the name stayed stable after deeper reading.

Core Stance

These six principles are the judgment content; the Workflow and checks below reference them.

1. Name inside the whole context

Never name from an isolated snippet if broader context is available. First understand:

• The concrete scenario where a reader meets the name: reading a module, calling an API, editing

a workflow, debugging a state transition, or using a product surface.

• The product/domain concept the name represents.
• The core operating subject: who or what acts, decides, owns state, or experiences the workflow.
• The layer and audience: product UI, domain model, API contract, persistence, runtime

internals, tests, or tooling.

• Neighboring concepts and existing vocabulary.
• Lifecycle: how the thing is created, used, transformed, completed, archived, failed, retired.
• Boundaries: what this concept includes, excludes, owns, and delegates.

A name that sounds good locally can be wrong globally if it hides the main actor, duplicates an existing concept, or names an implementation detail instead of the domain role.

2. Preserve information before shortening

Do not shorten names just to make them shorter. Brevity is only useful when the surrounding context already carries the omitted information without forcing the reader to reconstruct it.

Prefer a longer explicit name when it prevents information compression, especially for:

• Exported functions, public APIs, domain entities, files, modules, events, workflow states, and

cross-module types.

• Names that distinguish adjacent concepts: product vs domain, user work vs infrastructure

execution, draft vs persisted state, request vs result, configuration vs runtime state.

• Code a reader is likely to enter from search results, stack traces, tests, docs, generated

clients, or API contracts.

Short names are acceptable only when the scope is tiny and the missing words are immediately visible in the same expression or block. If a reader has to infer a noun from the folder, a prior paragraph, or tribal knowledge, the name is over-compressed.

3. Use the current core actor's viewpoint

Pick one viewpoint the naming set is organized around, then keep it stable across the module, call chain, and related API surface. Do not name one function from module A's viewpoint and the next from module B's viewpoint if they belong to the same conceptual flow — a hidden viewpoint shift is worse than a slightly longer name.

Identify the viewpoint anchor before proposing or reviewing names:

• Product layer: name by what the user sees and intends.
• Domain layer: name by the durable business concept and its invariants.
• Runtime/infrastructure layer: name by execution responsibility, state transition, protocol role.
• Adapter/integration layer: name by the boundary being bridged.

If a name is hard to judge, ask: "From whose perspective is this name supposed to be obvious?" If two adjacent names answer differently without crossing a real boundary, the naming is inconsistent. When a real boundary is crossed, make the shift explicit through adapter, mapper, handler, port, DTO, event, or boundary-specific vocabulary.

4. Follow the whole call flow

Check names against how the concept is called, passed, transformed, and returned — not only at declaration sites. Trace: who creates or receives the value, which module owns the decision, which module merely adapts/maps/forwards/stores/renders it, what the caller expects from the name before opening the implementation, and where the perspective legitimately changes.

Names in one flow should read like one sentence from one stable viewpoint. If reading a call chain forces the reader to switch between "what A sends", "what B receives", "what C stores", and "what the UI displays" without explicit boundaries, the names are not aligned.

5. Name the concept, not the rule

fetch, get, load, create, build, manager, service, config, and context are not automatically good or bad; their quality depends on what they mean in this codebase. Prefer a name that captures the real concept over one that merely satisfies a generic convention. If the project has a strong local vocabulary, follow it unless it actively misleads readers. Suffixes like Manager, Service, Helper, Util, Data, Info, or Context are often a way to avoid deciding what the thing actually owns.

6. Let naming expose design problems

When all candidate names feel awkward, do not keep generating synonyms — diagnose the design:

• Is one module mixing product, domain, and infrastructure concepts?
• Is one call flow switching viewpoints without an explicit boundary?
• Is the thing named by what it does today instead of what it owns?
• Are two different concepts sharing one name?
• Is one concept split across too many files?
• Is the current "thing" only a pass-through, glue layer, or temporary workflow step?

A fast trigger for this diagnosis: if a name needs a paragraph of explanation, or a hidden backstory, to make sense, the concept or boundary is probably wrong — or the name is over-compressed. Treat that friction as a design signal, not a wording problem.

Say so when the better answer is a design adjustment before a rename, and route per "Hand off when" below.

Workflow

Mode 1 — Name a concept:

1. Produce the research-stage name from quick research context. 2. Produce the top-of-head name from first principles, before overfitting to existing wording. 3. Deep-read the call flow and concept, then produce the final name after reading (anchor one viewpoint per stance #3; decide what must stay visible per stance #2). 4. Propose 3-5 candidates per the rules in the template (include one vocabulary-aligned, one clean-concept, one explicit name for boundary-crossing concepts). 5. Recommend the final name and explain why the rejected ones are weaker; if none is satisfactory, recommend the design clarification needed first.

Mode 2 — Review or rename existing names:

1. Read the surrounding system, then build a small vocabulary map (actors, workflows, calling/ called modules, layer-specific names for the same concept, overloaded terms). 2. For each important rename, show the three-stage path. 3. Flag names that harm understanding (wrong actor, mixed viewpoints, flattened concepts, over-compression, leaked implementation, stale legacy term, too generic, locally-consistent- but-globally-misleading). 4. Suggest changes in priority order — high-impact exported/API/domain names before small locals.

The expanded per-step detail lives in references/output-template.md.

Output

Mode 1 fills Context Read / Concept / Three-Stage Naming / What Changed After Reading / Candidates / Recommendation. Mode 2 fills Vocabulary Map / Findings (each oldName -> suggestedName with location, three-stage path, problem, better model, viewpoint repair, information restored, impact). Read references/output-template.md for the full fill-in blocks before finalizing.

Practical checks

Mechanical checks the principles above do not already cover — use as checks, not laws:

• Symmetry: paired operations should read as peers (start/stop, open/close, encode/decode);

asymmetric pair names imply the operations are not actually inverses, misleading the reader.

• Part of speech: entities read as nouns, actions as verbs, predicates as questions — so the

reader can tell what a name returns without opening it.

• Consistency: the same concept uses the same word; different concepts do not share one word.
• Lifecycle states: state names should match real transitions, not arbitrary UI or

implementation phases.

Hand off when

• The awkward name is really a module-boundary / abstraction problem (stance #6) — route to

hai-architecture to fix the design before the rename.

• The concept is a data-model field question (should it exist, store vs compute, column vs jsonb)

— route to entity-model-auditor.

• The user actually wants a bold direction change, not a name — route to geju.
• The question is a whole React component's API surface, not one prop or identifier — route to

react-component-diagnosis; naming a single prop stays here.

What this skill is NOT

• Not a linter. Casing and style conventions are project-level constraints, not the center of the

naming decision.

• Not a thesaurus. Do not solve unclear concepts by generating prettier synonyms.
• Not a rigid naming standard. Strong local vocabulary and architectural clarity beat generic

formulas.

• Not only about identifiers. Product terms, API resources, domain entities, event names,

workflow states, document titles, and file names all shape the system model.

Naming Output Templates

Single source of truth for the fill-in shapes. The inline skeletons in SKILL.md are a strict subset of these; match these section names. Show the three-stage naming path before the final recommendation in both modes.

---

Mode 1: Name a concept

Expanded steps (the lean numbered list in SKILL.md references these by name):

1. Research-stage name — read related code, docs, schemas, routes, tests, UI labels, API names, and nearby naming patterns when available; identify the concrete reading/usage scenario; scan existing vocabulary (current terms, adjacent names, product phrases, file/module/API names, document headings, state names). Produce the surface name and mark it provisional. 2. Top-of-head name — before overfitting to existing wording, name the concept from first principles: the name you would pick to explain the concept cleanly to a new reader. It may disagree with existing vocabulary; that disagreement is useful evidence. 3. Deep-read, then final name — trace the call flow (caller, callee, adapter, storage, event, UI/API entry points); identify layer, caller, owner, lifecycle, neighboring concepts; choose one viewpoint anchor and note where a real boundary forces a perspective shift; decide which details must stay visible vs which are carried by local context. Write "This thing is…" and "It is not…". Ask a focused question only if a missing fact changes the naming direction. 4. Propose 3-5 candidates — include at least one aligned with existing vocabulary, at least one reflecting the clean conceptual model (even if it implies design cleanup), and at least one explicit non-shortened name when the concept crosses module/API/domain boundaries. Carry forward the research-stage and top-of-head names if still plausible. Avoid obscure synonyms; do not rank a candidate higher just because it is shorter. 5. Recommend the final name — explain the mental model it creates, what context it preserves for a cold reader, why it keeps the call flow in one perspective, how it differs from the research-stage and top-of-head names, and why the rejected names are weaker. If no name is satisfactory, recommend the design clarification needed first.

## Context Read
- <files/docs/concepts checked, or assumptions if unavailable>
- **Call flow checked**: <caller -> callee -> adapter/storage/UI/API shape, or unavailable>

## Concept
- **Is**: <one-sentence definition>
- **Is not**: <boundary>
- **Viewpoint**: <product/domain/runtime/etc. and core actor>
- **Call-flow reading**: <how the name should read in the surrounding calls>
- **Must preserve**: <information that should remain visible in the name>

## Three-Stage Naming
| Stage | Name | Why this name appears |
|-------|------|-----------------------|
| 调研阶段的命名 / Research-stage naming | `<name>` | <surface context, existing vocabulary, neighboring terms> |
| 拍脑袋想出的命名 / Top-of-head naming | `<name>` | <first-principles intuition before deep reading> |
| 阅读完后的最终命名 / Final naming after reading | `<name>` | <evidence-backed final recommendation> |

## What Changed After Reading
<Why the final name stayed the same or changed after reading docs/code/call flow.>

## Candidates
### `candidateName`
- **Mental model**: <what a reader will assume>
- **Works because**: <fit to context>
- **Viewpoint consistency**: <whether it stays in the chosen perspective>
- **Information preserved**: <which important details remain explicit>
- **Risk**: <where it may mislead>

## Recommendation
`recommendedName` because <reason>.

---

Mode 2: Review or rename existing names

Expanded steps:

1. Read the surrounding system, not only the declarations. 2. Build a small vocabulary map: core actors/entities; workflows and state transitions; calling and called modules in the relevant flow; layer-specific names for the same concept; overloaded or inconsistent terms. 3. For each important rename, show the three-stage naming path (research-stage from current vocabulary, top-of-head from the clean concept, final after reading the flow). 4. Flag names that harm understanding — they name the wrong actor/viewpoint; mix caller/callee/storage/UI/adapter viewpoints inside one flow; flatten different concepts into one word; are over-compressed; expose implementation details at a product/domain boundary; keep legacy vocabulary after the model changed; are too generic for their scope; or are locally consistent but globally misleading. 5. Suggest changes in priority order; prefer high-impact exported/API/domain names over small local variables.

## Vocabulary Map
- <important concepts and current names>
- **Viewpoint anchor**: <chosen perspective for the reviewed naming set>
- **Call flow**: <important caller/callee/boundary sequence>

## Findings
### `oldName` -> `suggestedName`
- **Location**: <file:line>
- **Research-stage name**: `<name>` because <surface context>
- **Top-of-head name**: `<name>` because <first-principles intuition>
- **Final name after reading**: `<name>` because <deep-read evidence>
- **Problem**: <why this hurts the system model>
- **Better model**: <what the new name makes clear>
- **Viewpoint repair**: <how the suggested name restores a single perspective or marks a real boundary>
- **Information restored**: <what the current name compressed away>
- **Impact**: <rename scope and migration concern>

## Rename Plan, If Needed
- **Scope**: <files / API / docs / product copy the rename touches>
- **Compatibility**: <whether the old name is kept as an alias, and why>
- **Validation**: <grep, typecheck, contract check, doc update to confirm the rename is complete>

## Names To Avoid
- `<name>`: <the misleading or over-compressed meaning it would imply>

For a rename audit with many names, use this compact row shape instead of one block per name:

| Current | Research-stage name | Top-of-head name | Final name after reading | Why final wins |
|---------|---------------------|------------------|--------------------------|----------------|
| `<old>` | `<name>` | `<name>` | `<name>` | <evidence from context, viewpoint, boundary, or call flow> |

Hai Naming 中文版

本文件是中文阅读版；执行规则以 SKILL.md 为准。

概览

把命名当作用语言表达的架构：好名字应该反映整体上下文、核心行动者的视角，以及概念在系统里扮演的角色。名字决定了读者 能不能不在多个相互竞争的视角之间来回翻译，就理解调用流、责任边界和操作主体。

不要把命名变成机械套约定。约定重要，但概念、责任和系统词汇必须先清楚。

三阶段命名

每次建议都暴露三个阶段，而不是只给最终答案——这是为了让推理路径可见，而不只是给结论：

1. 调研阶段的命名：基于快速调研——现有词汇、相邻概念、初始约束——得到的粗命名。它反映深入阅读之前系统表面上 "看起来在表达什么"。 2. 拍脑袋想出的命名：基于第一性原理直觉给出的名字，可以稍微大胆、直接、不完美；它的价值是在被现有措辞带偏之前 暴露最初的心智模型。 3. 阅读完后的最终命名：读完相关文档、代码、调用流、产品上下文和系统词汇之后推荐的名字。除非有明确约束挡住， 这就是要采用的名字。

如果三个名字不同，说明是什么改变了你的判断。如果三个名字一致，说明为什么深入阅读后它仍然站得住。

核心立场

这六条原则是判断内容；下面的工作流和检查项都引用它们。

1. 放在整体上下文里命名

只要有更广上下文，就不要只看孤立片段。先理解：读者会在哪个具体场景遇到这个名字、它代表什么产品/领域概念、谁是核心 操作主体、处在哪一层、面向谁、周围有哪些已有词汇、生命周期（创建、使用、转换、完成、归档、失败、退役）是什么、边界 （包含、排除、拥有、委派什么）在哪里。一个本地听起来不错的名字，如果隐藏了主行动者、重复了已有概念、或命名了实现细节 而非领域角色，全局上就可能是错的。

2. 先保留信息，再考虑变短

不要为了短而短。只有当周围上下文已经替读者带着省略的信息、不用他重建时，简短才有用。

当更长更显式的名字能防止信息压缩时优先用它，尤其是：导出函数、公共 API、领域实体、文件、模块、事件、工作流状态、跨 模块类型；用来区分相邻概念的名字（产品 vs 领域、用户工作 vs 基础设施执行、草稿 vs 已持久化、请求 vs 结果、配置 vs 运行时状态）；读者很可能从搜索结果、堆栈、测试、文档、生成客户端或 API 契约里进入的代码。只有当作用域很小、被省略的 词在同一表达式或代码块里立即可见时，短名才可接受。

3. 使用当前核心行动者的视角

选一个命名集围绕的视角，并在整个模块、调用链和相关 API 表面保持稳定。不要在同一条概念流里，一个函数用 A 模块的视角、 下一个用 B 模块的视角——隐藏的视角切换比稍长的名字更糟。

先确定视角锚点：产品层按用户看到和意图的东西命名；领域层按持久的业务概念及其不变式命名；运行时/基础设施层按执行责任、 状态转换、协议角色命名；适配/集成层按所桥接的边界命名。名字难判断时，问："这个名字应该对谁的视角是显然的？"如果两个 相邻名字回答不同却没跨越真实边界，命名就是不一致的。真正跨边界时，用 adapter、mapper、handler、port、DTO、event 等 词把视角切换显式化。

4. 跟完整调用流一起判断

命名要看概念如何被调用、传递、转换、返回——不要只在声明处判断。追踪：谁创建或接收这个值、哪个模块拥有决策、哪个模块 只是适配/映射/转发/存储/渲染它、调用方在打开实现之前对名字期待什么、视角在哪里合理地切换。一条流里的名字应该读起来 像同一视角说出的一句话。如果读一条调用链逼着读者在"A 发什么""B 收什么""C 存什么""UI 显示什么"之间切换却没有显式边界， 名字就没对齐。

5. 命名概念，而不是套规则

fetch、get、load、create、build、manager、service、config、context 没有绝对好坏，质量取决于它们在 当前代码库里表达什么。优先用抓住真实概念的名字，而不是仅仅满足通用约定的名字。如果项目有强本地词汇，就跟着用，除非它 确实误导读者。Manager、Service、Helper、Util、Data、Info、Context 这类后缀，往往是在回避"这东西到底 拥有什么"这个决定。

6. 让命名暴露设计问题

当所有候选名都别扭时，不要继续找同义词——去诊断设计：

• 是不是一个模块混了产品、领域、基础设施概念？
• 是不是一条调用流在没有显式边界的情况下切换视角？
• 这东西是不是按它今天做的事命名，而不是按它拥有的东西？
• 是不是两个不同概念共用一个词？
• 是不是一个概念被拆散在太多文件里？
• 当前这个"东西"是不是只是个透传层、胶水层或临时工作流步骤？

对这个诊断的一个快速触发：如果一个名字需要一整段解释、或一段隐藏的背景故事才能讲清楚，那概念或边界 多半是错的——或者名字被过度压缩了。把这种"卡顿"当成设计信号，而不是用词问题。

当更好的答案是先改设计再改名时，明确说出来，并按下面的"何时转交"路由。

工作流

模式 1 — 给一个概念命名：

1. 从快速调研上下文产出调研阶段的命名。 2. 在被现有措辞带偏之前，从第一性原理产出拍脑袋的命名。 3. 深入阅读调用流和概念，产出阅读完后的最终命名（按立场 #3 锚定一个视角；按立场 #2 决定哪些信息必须保留可见）。 4. 按模板里的规则提出 3-5 个候选（至少一个贴合现有词汇、一个反映干净概念模型、一个为跨边界概念保留的显式名字）。 5. 推荐最终名字并解释为什么被否的更弱；如果没有令人满意的名字，先推荐需要的设计澄清。

模式 2 — 审查或重命名已有名字：

1. 读周围系统，再建一张小词汇表（行动者、工作流、调用/被调用模块、同一概念在各层的名字、被重载的术语）。 2. 对每个重要改名，展示三阶段路径。 3. 标出伤害理解的名字（命错行动者、混了视角、把不同概念压成一个词、过度压缩、泄露实现、留旧词、太泛、本地一致但 全局误导）。 4. 按优先级排序提改动——高影响的导出/API/领域名字优先于小局部变量。

每一步的展开细节在 references/output-template.md。

输出

模式 1 填写 Context Read / Concept / Three-Stage Naming / What Changed After Reading / Candidates / Recommendation。模式 2 填写 Vocabulary Map / Findings（每条 oldName -> suggestedName 带位置、三阶段路径、 问题、更好的模型、视角修复、恢复的信息、影响）。定稿前阅读 references/output-template.md 获取完整填空块。

实用检查项

下面是上面原则没覆盖到的机械检查项——当作检查，不是法律：

• 对称性：成对操作应读起来对等（start/stop、open/close、encode/decode）；不对称的成对名字会暗示这两个操作并非

互逆，从而误导读者。

• 词性：实体是名词、动作是动词、谓词读起来像问句——这样读者不打开实现也能判断名字返回什么。
• 一致性：同一概念用同一个词；不同概念不共用一个词。
• 生命周期状态：状态名应匹配真实状态转换，而非任意的 UI 或实现阶段。

何时转交

• 别扭的名字其实是模块边界 / 抽象问题（立场 #6）——转交 hai-architecture，先改设计再改名。
• 这个概念其实是数据模型字段问题（要不要存在、存还是算、列还是 jsonb）——转交 entity-model-auditor。
• 用户真正想要的是大方向的改变，而不是一个名字——转交 geju。
• 问题是整个 React 组件的 API 表面，而不是某一个 prop 或标识符——转交 react-component-diagnosis；给单个 prop 起名仍归本 skill。

这个 skill 不是什么

• 不是 linter。大小写和风格约定是项目级约束，不是命名决策的中心。
• 不是同义词词典。不要靠生成更漂亮的同义词来解决不清晰的概念。
• 不是僵化的命名规范。强本地词汇和架构清晰度胜过通用公式。
• 不只关于标识符。产品术语、API 资源、领域实体、事件名、工作流状态、文档标题和文件名都塑造系统模型。