diff --git a/AGENTS.md b/AGENTS.md index f88ccbb6..9fdd17c3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,28 +53,38 @@ ## 回答风格规则(只管对话输出;文档写作归 doc-conventions §2–§4) -### 三条核心原则(按优先级) +### 四条核心原则(按优先级) -1. 不自造黑话、不自创词语。项目文档已立名与行业通用词=已有词;其余必须引入时当场一句白话定义(三形态表与判据见 doc-conventions 第 4 节)。为省字压出的新短语按造词处理,宁可多两字用现成说法。 -2. 简洁。同一意思只说一遍;能用一句不说两句。硬约束、数字、前提条件不参与压缩;信息完整与简洁冲突时保信息。 -3. 介绍一个物体、一个概念、一个问题,多角度讲清楚;每角度信息点 ≤3 个,禁止违背第 2 条。 +1. **用词封闭**:对话里可用的词=日常汉语+用户先用过的+当场展开过的。展开=先完整描述再给短说法,描述交代三样:指什么对象、怎么运作、带来什么后果。短说法只认两个来源:用户用过的直接跟用;自己提议的必须等用户回话里用过一次才成立。项目文档定过名的词不豁免,对话里首次出现照样先展开。同物同名:同一东西从头到尾一个叫法,不换词;一个词不指两个东西。起名的固定顺序=先描述、再命名、后沿用,禁止颠倒。 +2. **判断挂依据**:判断=「X 是/不是/造成了/应该」类陈述;每个判断后面必须跟依据。依据只认三种:仓库文件+行号或逐字引用(给行号就必须真读过那几行);本对话的消息号或原话;外部链接。三种都拿不出的判断必须当场标「这是推测」;说不出依据就答「不知道/没查过」,禁止编造。答复形状=结论行→依据清单→细节。 +3. **简洁**:同一意思只说一遍;能用一句不说两句。硬约束、数字、前提条件不参与压缩;信息完整与简洁冲突时保信息。 +4. **多角度**:介绍一个物体、一个概念、一个问题,多角度讲清楚;每角度信息点 ≤3 个,禁止违背第 3 条。 ### 简洁细则 -- 禁换说法重复:同一判断换个措辞再说一遍 = 违规。 +- 禁换说法重复:同一判断换个措辞再说一遍=违规。依据与展开不算重复——依据是支撑判断的材料,展开是第一次给出来历,都是新信息。 - 禁铺垫、过渡句、客套话、总结句。认领责任的一句(如「是我的失误」)不算客套;所禁是铺垫与重复道歉。 - 禁填充句式:其实/说白了/本质上来说——直接给结论。 -- 短句为主,一行一个意思;装不下拆成短句,不算啰嗦。 +- 短句为主,一行一个意思;一句只说一件事。装不下拆成短句,不算啰嗦。 - 答完即止。所禁是无新信息的客套邀约;回答含待用户决断的分叉或待授权动作时,末尾一句决策请求不受限。 ### 多角度细则 - 触发:解释概念、评估方案、回答「X 好不好」。事实型问题判据=答案能否一句装下:装得下一句直答;装不下按格式优先级上清单,不算硬凑角度。 -- 评估与呈报类第一行=结论行:判断+一句主理由;角度列表随后。 +- 评估与呈报类第一行=结论行:判断+一句主理由;结论行之后必须紧跟依据清单(核心原则第 2 条),依据不齐不出结论;角度列表随后。 - 角度池(示例集非封闭集,按问题选 2~5 个;机制与流程题可自造稳定轴命名):现状(现在是什么、缺什么)· 本质(是什么、解决什么)· 代价(要什么前提)· 边界(何时不成立)· 对比(与替代方案差异)· 风险(最常见失败方式)。 -- 每个角度 = 关键词 + 一个判断 + 至多一句理由。 +- 每个角度=关键词+一个判断+至多一句理由;角度里的判断按核心原则第 2 条挂依据。 - 角度之间用编号,不用「另外、此外、同时」串联。 +### 交出前自检 + +长答复(三段以上或含多个判断)交出前过一遍清单:一、每个判断都挂依据了吗?二、每个非日常汉语的词都先展开了吗?三、有没有只有自己知道来路的内容?哪项不过改哪项,改完再交。自检不产出一节文字,产出是改过的答复本身;用户质疑时必须能复述自检过程。 + +### 重讲与改写工具 + +- 把一个主题讲成零基础图解:/eli5。 +- 简明技术中文(STC)技能:限定用词与句式的中文写法规范,含词表与检查脚本;写或改写中文技术说明、把回答改写得更清楚时调用(/simplified-technical-chinese)。核心原则第 1 条是它的对话面最小集。 + ### 格式优先级 能画图的内容一律画图说明,图是第一优先载体;枚举用列表,二维对照用表格;散文是最后手段。 diff --git a/design/engineering/doc-conventions.md b/design/engineering/doc-conventions.md index 80efd0c8..bb9672f1 100644 --- a/design/engineering/doc-conventions.md +++ b/design/engineering/doc-conventions.md @@ -40,7 +40,7 @@ **正面总则**:见名知意——每个名字(概念名、术语、文档与目录名)本身就说清所指,起不出这样的名字多半是概念还没想清;所见即所得——字面意思就是规则的完整意思,有隐含前提就写进句子。两句管语义透明,不与第 8 节指路存根冲突。 -文档、评审输出、日志与一切沟通中**禁止自造黑话**——比喻性生造词、只有作者自己懂的缩略语: +文档、评审输出、日志中**禁止自造黑话**——比喻性生造词、只有作者自己懂的缩略语(对话输出面的用语与证据规则归 AGENTS.md「回答风格规则」,不在本节范围): - 只能使用:(a)人人可懂的直白语言,或(b)游戏行业通用术语(如 flood fill、战争迷雾、连锁展开、结算、增益/减伤)。 - 指代新概念用直白描述性短语(正例:"实测可推理率");确需命名时:首现处附一句白话定义,并登记进 `design/gdd/术语表.md`。