用途
该技能用于把“业务术语是什么意思”与“为什么选择某个方案”分开治理。前者归入领域上下文,后者归入架构决策记录(ADR)。它强调:没有稳定内容时不要创建空壳文档。
主要能力
领域上下文文档(仅限领域语言)
当术语需要反复解释、一个术语有多种含义,或语言不清导致模块边界错误时,优先复用仓库已有的术语表/领域模型文档,或 .governance/docs-map.json 中的上下文角色。若已有上下文地图划分了不同业务上下文,应沿其链接找到相关术语表;主题归属不清时应询问。不同上下文可以合理地赋予同一词不同含义。不要为每个目录创建术语表,也不要跨不相关上下文强制统一含义。仅当不存在等效文档且某术语已确定时,才建议使用 templates/context.example.md 中的默认 CONTEXT.md。写入前必须获得用户明确批准创建该新文档,并保持在授权的文档范围内。一般性的“可更新文档”许可不等于批准新建文档;在授权范围内编辑已映射的现有术语表则无需新建审批。
记录内容仅限:
- 领域术语及精确定义;
- 核心概念之间的关系;
- 已确认的歧义及选定解释;
- 仍待领域负责人确认的歧义。
不得包含实现细节、当前状态、任务排期、完整需求、决策理由或历史。这些应分别留在代码/MAP、STATUS/Issue Tracker、Spec、ADR 和 LOG 中。术语必须可追溯到代码、契约或业务证据。未确认项标记为“待确认”,不要猜测。
对话中的语言精炼
这是主动建模工作流,并非要求每次被其他技能读取就重写术语表。
- 挑战矛盾:将用户措辞与术语表比较。若“cancellation”已指取消整个订单,而请求允许取消单行,应解释区别并询问用户意图,不得静默重定义。
- 拆解过载概念:对“account”,确认指客户组织、个人登录还是计费关系,并为每个不同概念提出精确术语。仅当确实指同一概念时才记录被否定的同义词。
- 用具体场景探查关系:例如一个客户能否有多个登录、部分取消订单时发票如何处理。场景用于暴露边界,是提问而非发明业务规则。
- 用证据核对主张:检查相关代码、测试、契约和现有记录。若实现只支持整单取消,应指出与部分取消提议的冲突。代码反映当前行为,不等于业务负责人的期望行为,不得自行裁定对错。
- 术语确定时及时记录:在授权的文档编辑中,当场更新现有术语表,而非等到收尾。定义保持一至两句,必要时附来源和本上下文应避免的同义词。不要仅为匹配提议术语而改写代码、契约或已接受的决策。仅讨论或只读工作时,仅呈现建议措辞,不写文件。
使用项目现有术语表格式。新建文档时,上下文模板提供精简起点;无实际内容的章节应省略。只收录业务特有概念,不含超时、工具函数等通用编程词汇。
ADR 交接:复用现有能力
该技能不定义第二个 ADR 目录、编号方案、生命周期或模板。当决策难以逆转、缺少上下文会让未来读者困惑、且涉及真实权衡时:
- 阅读并执行 architecture-decision-records 技能,保留仓库现有 ADR 位置、格式及初始化与写入的明确审批门槛。
- 若无现有约定,由该技能选择最小可行位置;不要在此另建体系。
- 从 CONTEXT.md、项目地图或相关 Spec/Issue 链接 ADR,而非复制决策正文。
- 决策被接受、取代或弃用时,按活文档规则向项目历史追加事件。
常规实现细节、易逆转改动和短期实验无需 ADR。
使用方式
存在已映射的上下文或术语表时直接复用;仅当没有等效事实来源且用户明确批准新建时,才创建 CONTEXT.md。挑战冲突语言、探查具体边界情况,并在记录已确认定义前用代码和契约核对。未解决的解读保持显式标注,不混入实现或任务状态。持久权衡转交 architecture-decision-records 并链接结果 ADR。排期、阻碍和执行状态保留在现有问题跟踪器中。
适用场景
- 领域术语被反复解释,或歧义语言导致实现漂移。
- 项目需要稳定的领域语言入口但缺少等效文档。
- 上下文工作中发现应转交 ADR 系统的持久决策。
- 仅在一次普通缺陷修复中消费既有词汇,则无需建模会话或新文档。
限制与边界
- 任务、状态、阻碍和排期应保留在项目现有跟踪器(如 GitHub Issues、Linear)中作为唯一事实来源;仅当无外部跟踪器且项目明确采用时,才使用本地 .scratch/。不得把排期放入 CONTEXT.md、ADR、PROJECT_STATUS 或历史索引数据库。
- 反模式包括:把当前任务、排期、完整需求或实现细节复制进 CONTEXT.md;为求完整创建空上下文文件或第二套 ADR 体系;将未确认的领域解读当作事实;把 ADR 正文复制进地图和日志;把不同业务概念当作同义词重命名;把多个上下文强行并入一个通用术语表;把术语表更新当作修改实现的许可;把代码当作预期业务规则的证明。
相关技能
architecture-decision-records:难以逆转决策的唯一 ADR 方法论。living-docs-governance:项目地图、状态与历史的生命周期维护。docs-governance:跨能力路由与收尾顺序。
其他说明
该技能的术语精炼工作流改编自 Matt Pocock 的 MIT 许可领域建模技能;具体的来源与改编边界暂未提供。ECC 现有 ADR 工作流仍是决策记录的唯一所有者。