naming

命名

一份列表，和 Hub 同步。naming 门禁会在推送时和 CI 中检查机器能检查的内容；其余由你判断。references/lint.md 划定了界限。

命名之前，先运行 node .agents/skills/naming/scripts/config.mjs，并将其输出作为当前规则来阅读：它会打印与项目覆盖项合并后的 references/naming.json。

规则

1. 每个事物只用一个词，而且这个词必须来自 GLOSSARY.md。先查这里，再查现有类型、数据库表和 API 路由。仓库中的用词优先于请求中的用词。

   好	不好	原因
   testimonial	customerQuote	请求说的是“客户引言”，仓库用的是 testimonial
   Testimonial 类型、testimonials 表、/api/testimonials	Testimonial 类型、reviews 表	每个事物只用一个词，处处一致
   order	与 order 并用的 purchase	一个事物用两个词会让搜索结果分散

2. 还没有对应的词？运行 term-check，向用户展示结果并取得确认，然后通过负责维护该文件的 domain-modeling 将这个词加入 GLOSSARY.md。

   好	不好	原因
   经术语检查并写入 GLOSSARY.md 的 carryOver	在 PR 中自行发明的 carryOver	新词需要用户确认
   记录了复数形式 caseStudies 的 caseStudy	没有词条的 caseStudy	下一个 Agent 可能会选用不同的词
   加入角色列表的 grid	使用 Grid，但列表未更新	闭合列表之外的角色是新词

3. 按角色命名，而非按类型命名。不要加 I 或 T 前缀，不要使用匈牙利命名法，也不要使用噪声词（见 naming.json 中的 noiseWords）。

   好	不好	原因
   User	IUser	不加 I 前缀
   count	nCount	不用匈牙利命名法
   accounts	accountList、accountData	不用噪声词，复数形式已经表示多个

4. 只用完整单词，不用单字母名称，也不用魔法数字。禁止使用的短词列在 naming.json 的 shortWords 中。

   好	不好	原因
   options	opts	使用完整单词
   error	e、err	不用单字母，也不用缩写
   const MAX_RETRIES = 3	单独的 3	数字需要有名称

5. 不要重复调用处已经表达的内容。

   好	不好	原因
   user.name	user.userName	对象已经说明是 user
   testimonials.add(item)	testimonials.addTestimonial(item)	集合已经说明是 testimonial
   testimonials 表中的 name 字段	testimonial_name 字段	表名已经说明是 testimonial

6. 动作名称以 naming.json 的 prefixes 中的动词开头，每种含义只用一个动词。纯派生值可以使用名词。

   好	不好	原因
   fetchTestimonials	与之并存的 loadTestimonials	每种含义只用一个动词；fetch 表示通过网络获取
   listUsers	getAllUsers	list 表示多个
   branchSha	getBranchSha	纯派生值可以使用名词

   前缀代表其含义：get 只读取，set 不返回任何内容，is 返回布尔值；find 可能什么都找不到，而 get 不会。名称中带有 and（如 saveAndNotify）就意味着这是两个函数。

7. 存储的布尔状态使用裸形容词；检查操作使用 is、has、can 或 should；绝不使用 notX。

   好	不好	原因
   archived	isArchived	存储状态使用裸形容词
   isEmpty、canRetry	empty()、retryAllowed	检查操作要带前缀
   enabled	notDisabled	只用肯定形式的名称

8. 实体使用单数，集合使用复数。在 GLOSSARY.md 中将不规则复数形式记录在对应词条旁。

   正确	错误	原因
   类型 Testimonial，文件 testimonial.ts	类型 Testimonials	单个实体用单数
   表、路径、文件夹 testimonials	表 testimonial	集合用复数
   case_studies，在 GLOSSARY.md 中记录不规则复数	case_studys	不规则复数只需记录一次

9. 不使用 enum。使用字符串字面量联合类型或 as const 对象。命名中的判别键是 naming.json 中的 kind。自有值使用 kebab-case；从外部 API 镜像的值保持原样。

   正确	错误	原因
   type Status = 'open' | 'in-progress'	enum Status { Open }	不使用 enum
   { kind: 'pull-request' }	{ type: 'pull-request' }	判别键是 kind
   GitHub API 中的 'MERGED'	'merged'	镜像值保持原样

10. 按照从大到小的顺序，从 naming.json 中的 parts 构建每个名称：project · area · entity · role · action · attribute · consumer。选取所需部分，并保持顺序。每个 artifacts 条目都会列出部分、大小写形式和示例。role 是每个仓库中固定的列表（artifacts.component.roles、artifacts.env.roles）。环境变量遵循 artifacts.env.shape。Payload CMS：集合 slug = API 路径 = 表；slug 使用 kebab-case 和复数形式（case-studies），表名将连字符替换为下划线（case_studies）。

    正确	错误	原因
    COLIN_SYNC_KEY_FOR_TWENTY	TWENTY_API_KEY	先写颁发方，再写密钥用途，最后写持有者
    TestimonialGrid	GridTestimonial	先写实体，再写角色
    testimonial.added	addTestimonial	事件描述过去发生的事实，而不是命令

11. 大小写形式遵循语言指南和仓库的 linter。文件和文件夹使用小写 kebab-case。如果仓库已有约定，则以现有约定为准：在 artifacts.file.case 和 artifacts.folder.case 中设置，可指定一种大小写形式或列表（React 组件和钩子使用 ["kebab", "PascalCase", "camelCase"]）。

    正确	错误	原因
    render-pr-body.mjs	renderPrBody.mjs	文件使用 kebab-case
    src/components/case-studies/	src/components/case_studies/	文件夹使用 kebab-case
    在所有地方都使用 load 的仓库中使用 loadUser	在旁边使用 fetchUser	以现有约定为准

12. 含义改变了？在同一次更改中到处重命名，参见 writing-rules 中的规则 204。

    正确	错误	原因
    在一个 PR 中将代码、文档和数据库中的 draft 重命名为 proposal	代码已重命名，文档仍写着 draft	同一事物不能有两个名称
    值不再表示上限后使用 retryCount	仍使用 maxRetries	名称不符合实际含义
    重命名并更新 GLOSSARY.md	仅重命名	术语表是权威来源

每个项目的覆盖项

覆盖文件：.skilly/naming.json，结构与 references/naming.json 相同，只包含需要更改的键。仅当 .skilly/naming.json 缺失时，才会读取旧的 docs/agents/naming.json：将其移至 .skilly/naming.json。

合并顺序：

1. references/naming.json
2. 按 .skilly/config.json 中 bundles 列出的顺序，依次合并 references/stacks/<bundle>.json。文件缺失时跳过。仅通过 includes 引入的 bundles 不计入。
3. .skilly/naming.json

合并规则：

• 对象按键合并。null 会删除对应键。
• 数组追加并去重。"-Data" 会删除默认的 Data。
• 标量值会覆盖。

{
  "prefixes": { "sync": { "meaning": "mirror to a remote system", "not": ["push", "mirror"] } },
  "noiseWords": ["-Data"],
  "allow": {
    "ctxTools": { "names": ["^ctx_"], "rules": ["short-word"], "why": "lean-ctx tool names." },
    "payload/migrations": null
  }
}

allow 存放命名条目。结构及其豁免的规则见：references/lint.md。

参考资料

• references/naming.json：前缀、组成部分、产物、短词、噪声词、同义词、区分项、允许项
• references/stacks/：每个套件的默认值，结构相同
• references/lint.md：检查门禁的内容、需要判断的事项、每个仓库的例外情况
• references/biome.json：供使用方选择启用的 Biome 配置块
• scripts/config.mjs：打印合并后的配置
• scripts/check.mjs：对分支中有变更的文件运行检查门禁