Files
lpt-meta/.agents/notes/implemented/process/2026-11-19-plain-language-rule.md
T

41 lines
3.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Agent Note: 新增「说人话」规则,禁止用行话统称代替具体内容
Status: implemented
## Problem
在评估 `lpt-fe` 前端设计规则时,我把「焦点环的颜色宽度偏移、动效的时长与缓动、层叠顺序的档位」三组具体取值说成「设计系统缺三类 token」,还用「token 是设计取值变量」这种再抽象一步的方式解释。用户连续两次追问才听懂,最后指出这只是「颜色和大小相关的常量」,要求以后直接说人话。
问题不在术语本身对不对,在**用抽象统称代替具体内容**:读者必须先猜「三类 token」包含什么,才能判断这个结论与自己有没有关系。既有规则管不到这件事——`business-terminology.md` 管的是业务概念叫哪个名字(且要求用术语表原词),`visual-communication.md` 管的是用什么媒介表达(图还是表),两者都不约束「拿工程行话包装日常概念」和「先抛统称再让读者拆」。
## Decision
新增通用规则 `.agents/roles/plain-language.md`(说人话),四组硬约束:
1. **先给具体,再给统称**:回答「是什么 / 缺什么 / 怎么改」时,第一句写具体对象与取值,统称只在具体项之后出现用来收口。
2. **日常概念不用行话包装**:颜色、字号、间距、圆角、层叠顺序就叫「取值 / 常量」,不叫 token、design token、设计令牌;外部框架造词进中文回复要先翻成动作描述。
3. **一句话最多一层抽象**:禁止「X 体系的 Y 机制」「三类 Z」这类只描述结构、不落到对象的句子。
4. **自查**:把每个统称问一句「它具体指哪几个东西」,答不出或要绕一圈就重写;用户已经追问过的句子,下次直接写进回复。
生效方式按 `.agents/roles/README.md` 的「规则文件不是自动加载入口」:在 meta `AGENTS.md` 的通用规则清单里登记(标强制),并在 `.agents/roles/README.md` 的规则清单表加一行触发场景。`business-terminology.md` 末尾加一条指认边界的链接——术语表管「叫哪个名字」,说人话管「用什么说法讲」,避免两条规则被读成互相冲突。
## Alternatives considered
### 为什么不写进 `business-terminology.md`?
`business-terminology.md` 的单一职责是「同一概念在同一套名字上对齐」,核心是术语表这个权威源;把语域规则塞进去会让它同时承担两件事,而它已经被 9 个文件引用为术语权威,改动面大、语义还会变糊。新增一份 38 行的规则文件成本更低,触发场景也独立(写回复时读,而不是描述系统概念时读)。
### 为什么不写进 `visual-communication.md`?
那份规则的对象是**表达媒介**(图 / 表 / 代码块),判定标准是「信息类型该不该画成图」。说人话的对象是**用词层级**,与媒介无关:一段纯文字表格同样可以说得抽象。合并会让「什么时候该画图」的判断被稀释。
### 为什么不改名 `business-terminology.md` 来容纳两者?
改名要同步 `AGENTS.md`(meta、lpt-be、lpt-fe、lpt-ai、lpt-android、lpt-docs)、`lpt-docs/.agents/roles/documentation-scope.md`、`OPTIMIZATION_BACKLOG.md` 共 9 处引用。规则新增比规则改名便宜,且改名不带来任何行为差异。
## Consequences
- 后续回复与交付说明多了一道自查:每个统称要能立刻展开成具体项。代价是句子会变长一点,收益是用户不必追问「这是什么意思」。
- 规则只约束表达,不约束代码标识符与命令(`plain-language.md` 的「不在约束内」已写清),不会与 `business-terminology.md` 的英文名派生要求打架。
- 这条规则靠自觉执行,没有脚本门禁;能机械检查的部分(行话黑名单)暂不做,因为黑名单必然漏词,而误判成本高于收益。