用途
domain-modeling 用于维护项目的共享语言,核心是两份小型产物:一份 GLOSSARY.md 术语表,以及一组简短的决策记录(ADR)。术语表为每个领域术语规定唯一名称、用业务语言写成的定义、应避免的同义词,以及负责裁决争议的术语负责人。决策记录用于保存那些难以逆转、事后令人意外且源于真实权衡的选择。该技能还提供工具,从对话和代码中提取候选术语、检查术语表、在文档和标识符中查找被禁用的同义词,并保持决策记录编号连续、链接正确。
主要能力
- 术语提取:从会议记录、设计笔记、工单和代码路径中统计内容词和双词短语,分类为已定义、被避免别名或新候选,并列出术语表中从未使用的术语。
- 术语表检查:检查 ### Term 条目,包括缺失定义或负责人、重复、别名冲突、循环引用、定义过长或过于实现化、无效状态、悬空 Related;
--scan可在文档和代码中查找被避免的别名,并支持标识符拆分(如 clientId、memberships.renew 会被识别为 client、membership 的使用)。 - 决策记录检查:检查编号、标题与文件匹配、状态值、双向取代链接、必需章节、措辞是否果断、是否记录了备选方案;
--next-title可打印下一个文件名。 - 同义词冲突解决:为竞争词写一句话定义,构造场景测试;若一个词适用于某场景而另一个不适用,则视为两个概念;若为同一概念,按外部使用优先、内部最少重载次之、代码中出现最多再次之的顺序选择名称,将落选词放入 Avoid。
- 设计过程中的模型维护:当有人使用术语违背术语表含义时立即指出并询问意图;当代码与已声明规则矛盾时呈现矛盾而非选边;在引入或重命名概念的同一变更中更新术语表。
使用方式
快速开始示例:
# Lint the sample glossary and find banned aliases in a feature note
python3 engineering/domain-modeling/scripts/glossary_lint.py \
--glossary engineering/domain-modeling/assets/sample_GLOSSARY.md \
--scan engineering/domain-modeling/assets/sample_feature_notes.md
# Lint the sample decision records and get the next file name
python3 engineering/domain-modeling/scripts/adr_lint.py \
--input engineering/domain-modeling/assets/sample_adr_set.json \
--next-title "Publish events for billing"
术语提取示例:
python3 engineering/domain-modeling/scripts/term_extract.py \
--paths engineering/domain-modeling/assets/sample_conversation.txt \
--glossary engineering/domain-modeling/assets/sample_GLOSSARY.md --format text
术语表检查示例:
python3 engineering/domain-modeling/scripts/glossary_lint.py \
--glossary engineering/domain-modeling/assets/sample_GLOSSARY.md \
--scan engineering/domain-modeling/assets/sample_feature_notes.md --format json
决策记录检查示例:
python3 engineering/domain-modeling/scripts/adr_lint.py \
--input engineering/domain-modeling/assets/sample_adr_set.json --format text
所有脚本均支持 --format text|json。adr_lint.py 可通过 --dir docs/adr 读取目录,或通过 --input 读取 JSON 包。
适用场景
- 同一事物在代码、文档、工单和支持宏中有三个名称。
- 设计讨论因某个词的含义而反复停滞(例如 "account" 指付款方还是登录账号)。
- 为项目或系统的某个限界部分开始编写 GLOSSARY.md。
- 刚做出一个新人可能会撤销的决策。
- 入职场景:新成员需要先掌握词汇,代码才讲得通。
- 命名新模块、表或 API 资源之前,使用已约定的术语。
限制
- 术语提取基于词频和停用词表,只呈现候选,不理解含义;人名和日常动词可能混入,分类需人工决定。
- 别名扫描在拆分标识符后匹配整词;无关复合词中的被禁词(如 "billboard" 安全,"billFor" 不安全)会被处理,但故意提及被禁词的引用文本仍会被报告。
- 检查工具只检查结构和一致性,不检查定义是否正确。
- 不涉及系统级架构决策及其评估(由 senior-architect 技能负责);不涉及模块接口设计与重构;不提供跨代码库的标识符自动重命名;不提供完整的领域驱动设计引导(如事件风暴工作坊)。
- 多上下文场景:当一个词在两个部分中合法地表示两种含义时,应拆分为按上下文的术语表,并保留根 GLOSSARY.md 列出上下文和翻译,在代码接缝处显式翻译。
- 决策记录采用三部分测试:难以逆转、事后令人意外、存在真实备选方案;三者全部满足才记录。已接受的记录不可编辑决策,只能通过新记录取代并添加 Supersedes: 链接。