文档写作原则

帮助作者组织和表达内容，让读者能够理解、判断并完成任务。人和 Agent 共用一份权威内容，角色或操作方式的差异在相应内容处说明。

核心原则

围绕问题组织：整套文档解决整体问题，每篇、每节与每段承担其中的具体问题。先想清各部分怎样支撑目标，再决定目录和结构；内容难以归位时，重新审视问题的划分。
按实际作用取舍：内容相关还不够，必须帮助读者理解、判断或行动。保留必要的背景、依据和示例，删去没有实际作用的内容。
先说要点，再展开：开头直接给出最重要的结论、原则或行动路径，让读者先抓住主线。后文展开依据、推导与做法；目录和主题分类不能代替要点。
想清楚，讲完整：先明确内容关系与展开顺序，再写段落句子。读者只能凭文档及其引用材料理解关键推导、采取行动并判断结果。

下面按文档体系、单篇文档、段落与句子三个层面展开，再说明修改与检查方法。局部问题来自上层组织时，先修正上层。

文档体系的组织

明确分工与关系

整体问题可按对象、阶段或具体疑问划分。同一层级的划分依据应清楚，换一种划分方式时说明关系。让读者看懂哪些部分独立使用、哪些有前提、哪些提供共同依据。

例如，产品设计文档可以分别讨论目标与范围、行为规则、原型和价值验证。原型依据目标与规则，也可能暴露规则缺口；价值验证可以发生在投入前或使用后。它们的关系应在入口说明，不能让读者把目录顺序当成执行顺序。

按职责划分，保持使用完整

一份文档承担一个具体职责，所需的背景、依据、步骤与示例放在一起。常见职责包括：

文档职责	应承载的内容
解释与导航	用途、适用范围、内容关系与阅读入口
支持理解或判断	概念、原则、判断依据、推导与示例
指导一项操作	准备条件、动作、分支、完成标准与必要排障
提供可复用的表达形式	模板结构、填写说明与示例

入口负责解释自身和导航，具体方法与交付细则放在对应文档。简单主题写成一篇完整说明即可；拆分以任务为单位，让读者一次拿到一个任务所需的全部规则。

维护权威内容与阅读路径

同一规则或方法只维护一处权威内容，其他文档引用它。摘要帮助读者选择和把握主线，详细规则在原处展开。通用原则集中维护，领域文档说明具体应用与特有要求。

导航用读者能识别的问题、现象或任务引导选读，不要求读者预先知道根因。说明必要的阅读依赖；新增或调整内容时同步更新索引和引用。

单篇文档的写作

让开头先交付核心认识

先明确读者需要理解什么或完成什么，将最重要的答案集中放在开头。说明文先给核心认识，方案先给建议与关键取舍，操作文档先给最小可用路径。短文用一句话或一段话即可，不必统一设置“总览”标题。

总览应包含可用的判断，不能只预告后面有哪些主题。例如，“本文讨论职责、内容与结构”只说明范围；“各部分围绕要解决的问题组织，不能帮助理解或行动的相关内容也应删去”才传达了原则。

总览与展开承担不同作用：总览让读者抓住结论及关键条件，展开解释为什么、如何判断和执行，并提供证据或示例。换词重述总览，或把核心结论藏进展开部分，都算总览未完成。会改变结论或行动的关键限制应随要点出现。

写完后暂时遮住后文，只读开头：能否说出最重要的判断或下一步，而不只是复述章节名？若不能，先重写总览；不要靠加粗所有段落或要求全文必读来弥补主线缺失。

按读者需要展开

先明确各节要回答的问题和相互关系，再安排顺序。让读者看清结论怎样得到依据支持、操作怎样走向完成，不让读者陪作者重走探索过程。

默认读者不熟悉当前主题。解释陌生术语，补足必要背景与推导，不依赖未交代的对话上下文；较长的前置知识可通过链接提供。上层框架能够涵盖某个认识，不等于读者会自行想到，能改变实际判断的认识应明确讲出。

操作说明写清准备、动作和完成标准，保留影响选择、执行或排障的必要信息。复盘和调查记录按用途保留过程，纯概念说明不必套用操作流程。

已有可用的命令、请求、配置或输入输出时，保留最小示例，说明输入来源、需替换的位置和验证状态。简洁以足够支持理解和行动为限；删掉一句不影响读者理解、判断或行动时，可删除或合并。

用形式表达关系

内容关系	适合的形式	使用要点
同层级、同维度的比较	表格	对齐差异，不为整齐把不同层级压成并列项
包含、分解、逐层推导	标题或嵌套列表	表达层级与从属
因果与论证	段落	保留推理过程与语气衔接
流程、状态、依赖、页面布局	图，如 Mermaid 或 HTML 渲染	从权威内容生成，不另立需要同步维护的事实

段落与句子的表达

一个段落围绕一个中心展开，一条只讲一个主张。写完用一句话说出这段让读者得到的判断或做法：说不出，是主张还没想清，先想清再调整表达；说出的是多件并列的事，用列表或拆段分开。

句子表达参照 ASD-STE100（Simplified Technical English）的下列结构原则；其英文词汇与时态规则不直接用于中文：

一句只做一个动作或一个主张，多个动作或条件拆开写。
用主动语态并写明施动者，施动者确实未知时除外。
省略与指代只在不存在第二种解读时使用。
同一概念全篇使用同一个词，不做同义词轮换。

明确区分必须、建议与可选，说明适用条件，不把可能包含的内容写成必填项。供机器解析或执行的文本，如工具描述、错误信息、Agent 间指令和操作步骤，按歧义零容忍检查。

正面表达完整的主张，把必要的范围、条件与确定程度交代清楚，再用依据、做法和示例帮助读者理解与执行。为防备假想误读而追加的限定、例外或提醒，应直接删去或将其中的必要信息融入主张。例如，将“清理全部缓存，但不包括正在使用的缓存”写成“清理未被使用的缓存”。

修改与检查

修改前识别原文的用途、关键事实、适用条件与推导关系。润色保留原意与要求强度，不能确认等义时先保留，纠错须有依据。收到反馈先整合已有内容，确有缺口再补，不把纠错过程逐条追加到正文。

按读者的阅读过程检查：

先读开头：能否抓住核心结论、原则或行动路径，以及影响它的关键条件？只有主题介绍或目录时，总览尚未完成。
再看组织：整套文档的分工与关系是否清楚？只读文档标题与各级标题，能否辨认主题、范围和内容关系？标题应具体说明对应内容。各篇、各节是否帮助解决对应问题？内容只是相关却没有作用时，应删减或重新组织。
沿任务走读：后文是否提供必要依据、做法与示例？仅凭文档和可获得的材料，能否形成判断、开始操作并确认结果？需要猜测或反复拼接规则时，回到对应层面调整。
核对表达与引用：检查术语、指代、要求强度、链接与格式，确认修改没有破坏原有价值或留下冲突。

机械检查不能代替内容判断，文档走读不能代替实际执行验证。交代检查结果时说明覆盖范围和未验证部分。

常见反模式

反模式条目记录真实发生过的纠正，用四列表维护，新增即在表中加行；各领域建反模式文档时按此格式收录，不另立写法。

四列填法

场景与条件：首句写任务动作，作为检索入口；随后写决定取舍的条件参数，不看任何外部材料即可读懂。
被否的做法、采纳的做法：写实际发生的做法；采纳的必须是落地验证过的。
决策依据：说明这次为什么这样选，写清实际影响取舍的条件与权衡；只记录本次决策有依据的判断，不补写未发生的反例场景。

收录与使用

每格一到两句，写不进来说明未想透。
只收录真实发生过的纠正；同一偏差更新不新增，当初判断有误时改判。
新增或改判条目，内容经用户确认后写入；Agent 提出候选，不自行收录。
条目是算账样本，不是答案库：引用前核对当前条件与条目条件的差异；条件不同导致结论不同，不是违背条目。
场景相似、按同样的账算出不同做法且说不清差异时，停下来问用户。

场景与条件	被否的做法	采纳的做法	决策依据
整理 practical-memory 文案及审阅界面设计方法时，用户指出主张后的补充含有防御性解释。	在主张后追加“不是……”“不构成……”或“仍需验证”等限定、例外与提醒，防备假想误读。	按段落与句子的表达重写规则：删去无实际作用的补充，将必要范围与条件融入正面主张，后续展开帮助理解和执行主张。	补丁式限定分散主线，逐句正确也会增加阅读负担；取舍看其对当前理解和行动的作用，必要条件随主张表达。
写方法节，内容逐句正确却被评价“没有营养”，定点改写后仍无改善。	保留与共识常识无法区分的规则表述，靠补句子加信息量。	点出规则防止的偏差，让针对性可见；删掉不改变读者行为的句子，或并入相邻内容。	真正有信息量的是针对具体偏差的默认倾向；防止的偏差没写出时，规则与常识无法区分，删掉也不改变读者行为。
新建公开仓库发布项目，沿用内部开发 README，检查只核对路径残留等机械项即认为可用，用户指出“太机械”。	直接发布开发台账（功能罗列、版本史、内部排查记录、防御性边界），以机械项通过代替读者视角检查。	发布前按目标读者重写：开头讲清是什么、为什么值得用、与替代方案的差异；删去版本史与排查记录，边界集中一节、措辞直接。	开发台账服务于 agent 协作，不是面向使用者的文档；机械项核对通过不等于可发布，检查须过读者视角。