mc-glossary git:20261010.79a4f96A

Immutable. This exact content never changes and is served at /api/v1/blob/d62637ced90e22c7.

---
name: mc-glossary
description: 项目共同语言。当用户工程里出现「同一个东西两个叫法 / 跨会话术语聊丢了 / 反复争论同一个架构决定 / 代码名和聊天名对不上」，或用户说「立个术语表 / 把这个决定记下来 / 写 ADR / 统一命名」时激活：为用户的工程维护 GLOSSARY.md（术语、定义、禁用同义词、代码落点）与 adr/ 决策记录（背景、决定、没选的方案与原因、后果），让后续流程（spec / breakdown / review / handoff）按同一套词对齐。定义与改名由用户拍板，agent 只给草案与冲突证据。本仓知识库自身台账不适用。
---

# mc-glossary — 术语表与决策记录

一句话目标：把一个模组的领域词汇和「为什么这么定」留在盘上，而不是每个会话重新吵一遍。

## 第 1 步 · 什么时候写、写什么

- 触发：同一概念在一次对话里出现两种叫法；某个决定被反复重议；review 时发现代码名与聊天名打架。
- **别补历史**：新立词条只记当下真实发生过的分歧，不回头造几十条「看起来很标准」的术语——那是凭记忆发明，不是记录。

GLOSSARY.md 每条四件：**术语 / 定义（一句话）/ 禁用同义词**，或「与 X 的区别」判别问句（给一个场景，该不该叫这个）/ **代码落点**（类名、注册名、lang 键前缀）。

adr 每篇四段：**背景**（当时面对什么）/ **决定**（写成事实句）/ **没选的方案与原因**（这是 ADR 的价值所在）/ **后果**（哪些代码与流程因此钉死，改它要先翻这条）。只记三类决定：改变方向的、有争议拍板的、难回退的（存档格式 / 网络协议）——日常小选型入了就是流水账。

## 第 2 步 · 消费面

- mc-spec / mc-breakdown 写条目时与 GLOSSARY 对齐；名字对不上 → 要么改稿要么立词条，不含糊两边都写。
- mc-review 标准轴加一条：diff 里的新概念与 GLOSSARY 冲突 → 报告点名。
- mc-handoff 的「目标与现状」块引用 GLOSSARY / ADR 路径，让新会话不重新发明词；**引用表，不复述定义**。
- 用户没听懂要重讲时（mc-waitwhat 场景）：重讲按表内定义展开，不临场换一套比喻发明新含义。

## 第 3 步 · 纪律

- 定义权在用户：术语叫什么、边界怎么划是领域设计，agent 给草案与冲突证据，拍板等人。
- 记录现状，不自动改码：词条与代码名打架时，先如实记「当前是什么」；统一改名是另一次要用户点头的改动。
- ADR 不写「最佳实践」空话：没有真实备选项与被拒理由的不立 ADR——写进 GLOSSARY 或不写。
- 落盘先过目；位置默认用户工程 docs 下的 GLOSSARY.md 与 adr/。

## 边界

- 本仓库自己的 CORPUS_PROVENANCE / CHANGELOG 是维护侧台账，不吃本技能。
- 词条该不该按平台既有裁决先定（AGENTS 判序）：过一遍再决定是否需要 ADR，不拿 ADR 覆盖平台规矩。