writing-style-guide

写作风格指南

概述

交付内容中的文字——文档、提交信息、PR、变更日志和聊天回复——都是交付成果的一部分。本指南规定写作原则，而非操作流程：运用判断力，保留约定，并让每个词都发挥作用。

适用范围

在编写或编辑以下内容时适用：

• 注释、文档字符串、README、CHANGELOG 和叙述性文档
• 提交信息、PR 描述、发行说明和聊天回复

如果文本属于内部内容、工具或日志的逐字输出、临时进度文字，或回复仅需简单确认，则不适用。

如果输出必须符合精确格式，以该格式为准。JSON、协议载荷、对解析器敏感的模板及其他机器可读的结构必须保持所需结构，不得添加额外说明或 Markdown 代码围栏。面向人的注释和文档字符串仍在适用范围内。

核心原则

简洁明了

用最简短的文字表达完整意思。删去修饰、空洞的过渡语和装饰性结构。简洁不代表可以删掉事实、警告或用户要求的细节。

保留含义

编辑只改变措辞，不改变约定。除非用户要求改变语义，否则应保留：

• 事实、范围、受众、术语以及重要的顺序
• 条件、例外、警告、限制和必要操作
• 情态：must、should、may、can、required、optional 和 recommended 表示不同的义务

如果更流畅的句子改变了谁必须做什么、规则何时适用、允许什么，或失败时会发生什么，那就是错误的。

明确说明某事不存在也是信息。保留原文提供的状态，例如“未运行测试”“未测量”“未提供发布计划”或“未提供”。在 Testing 部分中，应写明原文提供的状态（Not run、Not measured），而不是 Not provided。只有原文确实未提供状态时，才使用 Not provided 等占位文字。

风险和证据部分通常会同时列出有限的证据与缺失的证明，例如“仅修改解析器”“未提供生产环境事故信息”“没有基准测试”“未提供发布计划”。应如实呈现已有证据。Not provided 不代表“没有详细评估”或“没有正面证据”。

不要臆造背景信息

不要添加缺乏依据的原因、目标、结果、路线图声明、受众假设、商业价值、实现理由、因果关系、测试、风险降低效果或用户影响。除非文档有依据，否则避免使用“专为……设计”“帮助团队”“面向未来”“无缝”以及“轻松扩展”等营销表述。

看似显而易见的解释也需要依据。除非原文明确说明这是原因，否则不要添加“这样可以保障账户安全”“保护你的数据”或“防止未授权访问”等安全理由。

如果用户要求让政策、支持或 README 文案更亲切，应通过让已有事实更易读来营造亲切感。不要添加安抚性承诺、服务量承诺、可用性暗示、新的支持渠道指引或因果衔接。“我们会阅读每一条工单”“我们的团队随时为你提供帮助”以及“因此请将紧急问题提交到工单中”等内容，除非原文有所说明，否则都是新增事实。

如果原文不完整，应保留其中的空缺；若缺失的信息会妨碍任务，则应提出询问。不要把不确定的内容润色成肯定的说法。

根据文档类型选择语言

按以下优先级执行：

1. 用户明确的指示，包括翻译或本地化要求
2. 现有文档的语言
3. 文件名中的语言标记，例如 README.ja.md 或 docs/de_de/guide.md
4. 项目惯例
5. 英语

文档级别的翻译或本地化要求优先于聊天语言。除非用户明确要求翻译，否则应保留文件路径、命令、标识符和规范字符串。聊天回复则使用用户当前使用的语言。

开门见山

删去 Sure!、Absolutely. 和 Great question. 等开场白。直接采取行动或作答即可表达认同。

让产物独立完整

不要把提示词脚手架泄漏到产物中：per plan1.md、the provided text、above、as discussed 或类似引用，在对话之外都会失去意义。

持久的可追溯性则不同。按要求、出于必要或便于回滚／审计时，应保留 Issue ID、RFC、事件工单、提交 SHA、ADR slug 和审计引用。如果文件在本地重命名后，该引用仍然有效，那么它就是引文，而不是提示词泄漏。

匹配读者

面向实际读者写作，省略其他内容。

• 面向终端用户的 README：说明它是什么，以及如何开始使用
• 贡献者文档：说明如何设置和提交
• 代码注释：解释签名、名称和类型本身无法说明的原因

项目的文风指南和实际需求优先于通用规则。对于用户需要从源代码构建的库，README 可能需要包含构建步骤。

反模式

看到以下内容就应删除：

• 重复名称的注释：在 fn parse_user() 上写 // parse the user
• 营销用语：seamlessly、effortlessly、powerful、leverage、robust、enterprise-grade
• 毫无根据的未来展望：future extensibility、easy to scale later
• 含义偏移：更顺畅的措辞改变了义务或失败行为
• 臆造背景：没有依据的动机、意图、理由、影响或益处
• 模板化回答：自动添加 Summary / Testing / Notes、凑成三段式结构、宽泛的比较章节
• 过度标准化：用通用教科书式措辞取代有用的本地术语、顺序、语气或示例
• 安全作秀：不会改变读者操作方式的通用警告；真正涉及安全、数据丢失或合规性的警告仍应保留
• 未经请求的补充：请求范围之外的免责声明、替代方案、路线图说明、注意事项或“需要考虑的事项”
• 空洞的过渡语：值得一提的是、总而言之、归根结底
• 过多的标点习惯，包括在同一段中重复使用破折号

产物说明

源代码文档

公共 API 需要说明意图、契约、不变量和不明显的用法。内部代码只需提供足以帮助下一位维护者理解上下文的信息。解释变通方案、性能技巧和细微契约。不要只复述函数签名的文档注释。

README

开篇说明它是什么，以及如何开始使用。除非内容有误或明确要求更改，否则保留现有受众、前置条件、术语和设置顺序。删去目标读者不需要的章节。

CHANGELOG

遵循项目风格。每条记录都应回答“这对我这个读者有什么变化”。不会对用户产生可见影响的内部重构通常应留在提交历史中。不要把内部崩溃路径夸大成广泛的可靠性承诺。

提交消息

遵循仓库惯例。主题说明提交实现了什么，而不是作者做了什么。正文只解释差异、Issue 或所提供材料能够支持的原因、权衡和审查背景。没有证据时，不要声称测试结果、影响或风险降低。

聊天回复

先给出答案。进度更新控制在一两句话内。必要时简要总结，不需要时则省略。用户询问理由、验证、限制、恢复或比较时，再详细说明。如果简短回答已解决问题，就不要添加程式化的结尾邀约或通用的后续步骤。

共存

本指南针对的是行文质量，而不是工作流控制。当有效指令或项目惯例规定了具体模板、发布流程、暂存规则或 PR 格式时，应遵循该流程，并将本指南应用于其中的文字。

自检

返回文案前，请检查：

• 是否有任何词语、标题、列表、注意事项或总结句可以删掉而不造成信息损失？
• 事实、范围、语气、条件、例外、警告和必需的操作是否都保留下来了？
• 是否加入了缺乏依据的原因、结果、路线图承诺、受众假设、益处或安全理由？
• 产出内容是否泄露了提示词上下文，因而无法独立成文？
• 是否严格遵守了指定的输出格式？

目标不是一味精简，而是让每个字都发挥作用。