docs: 新增说人话与图示优先两条规则,登记跨仓库笔记
This commit is contained in:
@@ -0,0 +1,40 @@
|
||||
# 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` 的英文名派生要求打架。
|
||||
- 这条规则靠自觉执行,没有脚本门禁;能机械检查的部分(行话黑名单)暂不做,因为黑名单必然漏词,而误判成本高于收益。
|
||||
Reference in New Issue
Block a user