用途:这是一项保持项目领域语言精确的主动实践,负责维护 CONTEXT.md 术语表(领域术语的共享词汇),并判断某个决策是否值得写成 ADR。当术语使用不一致、术语漂移,或同一概念在多次会话中被反复解释时触发——每次重复解释都会浪费 token,而一句话的条目即可替代。
布局:项目根目录下单个 CONTEXT.md 存放术语表,docs/adr/NNNN-*.md 存放架构决策。若代码库包含多个不同上下文,改用 CONTEXT-MAP.md。文件应惰性创建,只在某个术语确实需要固定时才建,不要预先搭建空术语表。
会话中的做法:质疑术语,当一个词有两种用法时指出歧义并提出更精确的含义;把模糊表述替换为代码实际实现的具体术语;压力测试概念关系,确认对话中的关系与代码中的关系一致;将说法与代码交叉核对,与实现矛盾的条目是错的,需修正条目或代码;发现更精确含义时即时更新 CONTEXT.md,不要留到会话结束批量编辑;固定重复解释,当同一概念在消息或会话间需要超过两句话说明时,添加一句话的 CONTEXT.md 条目。
CONTEXT.md 规则:它只是术语表,包含术语及其精确含义,不含实现细节、操作指南或散文式论述;每个术语一条,每个含义尽量一句话;若术语确实存在争议,标记为 Flagged: 并记录相互竞争的含义,而不是默默选择其一。
何时提供 ADR:仅当三个条件同时成立时才提供架构决策记录——决策难以逆转、没有上下文会令人意外、可行选项之间存在真实权衡。任一条件不成立,就把该决策记录为 CONTEXT.md 术语条目,不要为常规选择创建 ADR。