writing: 读者只有五分钟；每个句子都要物有所值
这个方法防止的失败：用大量词语表达少量信息的文本，遵循每个模型都会产生的节奏（开头宣布、正文三点、结尾重复），并且在此过程中改变一个数字、丢弃一个“可能”或编造一个来源。第二个失败是重写让文本变得光滑，却剥离了作者的声音。
0. 由项目决定
在为一个项目写作之前，请阅读 CLAUDE.md / AGENTS.md，并在 .claude/skills/ 中查找项目自己的技能。项目的规则和技能优先于此技能：PR 模板和门控、提交约定、声明的语言、语调指南、设计系统外观。此技能是项目没有这些时的默认设置。语言、语域和声音来自项目（第10节），绝不来自固定的项目或个人。
使用者：每个为人类读者撰写文本的团队代理（登陆页面、卡片、交接文档、PR、报告、提交、README）。该技能负责编写；发送、发布和发布始终属于所有者。$WRITING 是该技能的目录（~/.claude/skills/writing）；脚本是 Python 标准库，使用 python3 -I 运行。
1. 五个任务：开始前选择一个
| 任务 | 触发条件 | 输出 |
|---|---|---|
| 编写 (默认) | 你生成文本：文档、消息、PR、回复 | 文本本身，不包含关于文本的内容 |
| 编辑 | 所有者交给你草稿进行修改 | 编辑后的草稿和简短的 更改了什么 |
| 检测 | “这个读起来像AI吗？”、“审计这个”、“指出来但不重写” | 命名的模式，每个模式附带一行引用，再用几个字说明修改方法。不重写，不评分，不声明是谁写的 |
| 校准 | 两个或更多样本：“像我一样写”、“产品的语调” | 以 references/voice-profile.md 格式生成的声音档案，供编辑和保留 |
| 压缩 | “压缩 CLAUDE.md”、“修剪记忆”、“减少此交接中的token” | 包含所有事实的较小文件以及 fidelity_check.py 的结果 |
在“检测”中，命名的模式是所有者可以检查的证据；AI 检测器则是猜测。声音档案会在会话中保留给后续所有任务，作为 --profile 传递给 linter，并且仅更改机械模式，从不更改事实或禁止的构造。
2. 仪式等级
流程依据风险而定。每个等级都遵守规则；只有门控发生变化。
| 等级 | 文本 | 流程 |
|---|---|---|
| 0 | 聊天回复、终端状态、提交信息、代码注释、单行卡片 | 内存规则。无脚本、无报告、无元评论 |
| 1 | PR 正文、AgenFK 卡片、交接文档、Slack 或 WhatsApp 帖子、电子邮件、变更日志、简短 README | 规则加上机械性扫查（第9节） |
| 2 | 超过约400字且由第三方阅读的文本：规范、ADR、提案、报告、事后分析、架构文档 | 完整流程；在你说完成之前两个脚本都必须通过 |
精简模式。 当提示“精简模式”、“穴居人”、“简短”或“更少token”时，等级0会变得更严格，直到“正常模式”：先回答，零仪式，冠词可选，否定永远不要，每个句子一个想法且不超过20个词，载荷（代码、命令、路径、错误）逐字保留，工具状态保持简短，不要表演模式。对于安全警告、不可逆操作、步骤顺序、困惑的请求者、给用户的问题以及所有在聊天之外记录的内容，则恢复为完整句子。提交信息遵循仓库的约定（先阅读 git log）；如果没有约定，则使用祈使句格式的常规提交，正文只包含原因。完整规则和发送前的检查：references/lean.md。
等级0不是豁免：规则适用于会话中的每条回复，因为几轮之后默认节奏会回来。等级0和1的内存自检：eval.md 的最后一部分。
3. 严重程度
发现的问题权重不同，顺序决定了先修复什么以及什么永远不能发布。结构比词汇更重要：一个词汇列表干净但形状为“宣布-正文-总结”的文档仍然是垃圾，而一个被禁止列表上的精确术语则不是。
| 级别 | 内容 | 门控 |
|---|---|---|
| 阻塞 | 捏造的事实、姓名、数字、日期、引用或来源。限定词被丢弃、削弱或加强。决定、数字或要求被更改。代码、表格、链接或前置内容被触及。与源材料矛盾 | 永远不能发布。没有 allow 指令能覆盖。fidelity_check.py 非零，或覆盖列表的某个项目缺失 |
| 修改 | linter 错误：禁止的词汇或结构、通用标题、表情符号、列表代替散文、聊天机器人残留。结构性：空白的开头、总结性的结尾、千篇一律的段落 | 修复它，或者带上一行说明或内联的 allow 保留它。绝不允许通过删除发现所处的事实来修复 |
| 优先修改 | linter 警告：软构造、节奏、密度、过渡、确定性、名词化、可移植性 | 在不损失事实的情况下修复它。否则保留并继续 |
| 建议 | eval.md 的判断：15% 的削减、标题、介质、对称性 | 由你决定。说明你留下了什么 |
4. 高于一切的三大规则
忠实高于可读性。 永远不要为了句子流畅而更改需求、决定、数字、名称、风险、验收标准或事实。如果事实读起来不好，请修改句子以适应事实，而不是修改事实。绝不捏造事实、姓名、数字、日期、引用或来源。逐字保留：代码、命令、图表、链接、表格、前置内容、技术标识符。
声音高于修饰。 做到解决它所需要的最小编辑。首先注意草稿的词汇、节奏、直接程度、幽默感、不确定性和离题之处，并保留它们。不要让每个段落都同样整洁；强烈的观点、脏话和诚实的承认在属于作者时应予保留。提升文本的清晰度不等于降低理解门槛。个性适合帖子或评论文章；参考文献、法律和事故文本保持中立。
不确定性是事实。 “可能”、“估计”、“推断”和“尚未测量”说明了作者知道多少。砍掉堆积的修饰语可以保留一个修饰语并指明什么是不确定的；它绝不应该提升主张。在安全、法律、财务、医疗和事故文本中，限定词本身就是内容，即使句子在没有它的情况下读起来更好也应当保留。反之亦然：永远不要对源材料陈述的事实使用修饰语。
5. 句子测试
每个句子都传递信息、推理、必要的上下文或操作。唯一作用是强调、客套或填充的句子：删除它，不要重写它。
在技术和操作文档中，门槛更高，因为其中的推理通常很短：每个句子都承载一个事实、数字、命令、名称、决定或风险。执行摘要和对话则可以为原因和框架留出空间，而失去这些是另一种失败。
可移植性测试。 如果句子移动至另一个人、公司、国家或产品而不做任何更改，那它就是填充。删掉它，或者用特定于主题的事实、机制、后果或判断来替换它。
展示，不要告知。 事实、行动和后果承担着强调的作用。删掉那些标注某个点重要、令人惊讶或微妙的评论，而是去展示它。
加入度量。 没有数字的可度量形容词是没有证据的主张。技术分类则不是：public endpoint、private subnet、external dependency、manual approval、reversible migration 和 immutable tag 是精确术语，应当保留。
| 词语 | 替换为 |
|---|---|
| 健壮 / robusto | 它能承受什么：重试、故障转移、在N次测试中通过 |
| 可扩展 / escalável | 达到多少：RPS、节点、GB、租户 |
| 重大 / significativo | 具体数字 |
| 快 / rápido | 延迟或持续时间 |
| 许多 / vários | 具体数量 |
| 最近 / recentemente | 具体日期 |
| 最佳实践 / boa prática | 谁的、哪个文档 |
6. 结构
- 先回答。决定、修复、数字或命令是第一行。
- 没有介绍文档涵盖范围的开头段落，没有重复它的结尾段落。每个结论只说一次；读者刚刚才读过它。
- 标题命名内容（“回滚”），从不提问，并且绝不与标题下的第一个句子重复。禁止的形式：概述、关键要点、最终想法、结论、介绍、前方的路、全面概述、战略亮点、实施之旅。
- 段落承载推理。列表用于真正是集合的东西。表格仅当读者需要比较行与列时才使用。
- 句子和段落的长度要有变化。永远不要因为三个听起来完整而构建一组三个。
- 如果内容适合三行，那就用三行。
伴随文件的消息用一行说明更改了什么，没有“这里是文档”和没有提供帮助。每种文档类型的形状：references/shapes.md。
7. 最清晰的媒介
不要默认从散文开始。在长章节之前，说明读者需要理解的关系，并选择能保持含义的最小媒介。完整规则见 references/visuals.md。
| 读者需要 | 使用 |
|---|---|
| 比较3个或更多项在2个或更多属性上，或阅读精确的映射 | 表格 |
| 跟踪序列、拓扑、层次结构、所有权、状态或依赖关系 | 图表 |
| 识别屏幕、位置、布局或前后对比 | 带注释的图片 |
| 执行操作步骤 | 编号步骤和可粘贴的代码 |
| 理解原因、细微差别或为何做出决定 | 散文 |
视觉元素仅来自源材料中确认的内容，附带一行结论和替代文本，不要用散文重复它。生成的图像绝不能用于精确的拓扑、数据、数值或架构。一个巨大而空白的图表就是垃圾。
架构或云图表是对真实系统的主张：遵循 cloud-diagram 技能（先盘点再绘制几何，当前或建议状态，可编辑源，渲染检查）。此技能仅负责其周围的散文。
渲染文档 (HTML, Artifact, 其 PDF) ：外观属于项目。从 templates/document.html 开始，用 python3 -I ~/.claude/skills/design-reference/scripts/sweep.py <root> --css 的输出替换顶部的 --ds-* 块（如果项目中没有设计系统，则保留团队的中性调色板）。默认使用一种语言；仅当读者是双语用户或有要求时才使用双语，从 templates/document-bilingual.html 开始，并设置 <html data-languages="en pt">。交付前：运行 python3 -I "$WRITING/scripts/artifact_check.py" <file>。PR、卡片、提交和 docs/ 中的 markdown 不适用此规则。规则：references/rendered-document.md。
演示文稿：当安装了演示文稿技能时，在规划幻灯片之前调用它；该技能拥有结构、布局和渲染，此技能拥有散文和忠实性。除非被要求，否则不要将 README、ADR、运行手册、卡片或电子邮件转换为幻灯片。
拉取请求：正文服务于一位只有30秒决定是否要打开差异的审阅者：更改了什么、为什么、遗漏了什么、如何验证的、风险和回滚。不要叙述代理的工作，也不要重复提交。结构：pull-request 技能（或项目的）；references/pull-requests.md 中的30秒测试。只有 github 才能打开 PR，并且是在 verifier 给出“发布”判定之后。
8. 要删除的模式和词语
带有修复方法、前后对比对和两种语言词表的目录在 references/patterns.md 中（快速摘要会打开文件）。每个会话阅读一次。最常见的是：二元对比（“它不是X，而是Y”）、冒号揭示、清喉咙（“值得一提的是”）、虚假洞察、宣布（“让我们深入探讨吧”）、结尾处的浅层 -ing 从句、夸大其词、模糊来源、元话语、隐藏行为者、结尾处的剪断否定（“别担心”）、聊天机器人残留、堆积的修饰语、一连串戏剧性的碎片。
被标记的词语（leverage、seamless、delve、robust；alavancar、robusto、jornada、ecossistema）会被删除，而不是替换为同义词。有些在上下文中是精确词语（战略文档中的“strategic decision”；作为技术术语的 gate、harness、pipeline、realm）：保留它需要一行说明或 <!-- writing: allow <term> -->，绝不能沉默。空副词（just、actually、simply；só、literalmente、na verdade）在无贡献时删除，在携带强调、不确定性或作者节奏时保留。
9. 机械性扫查
在最终文本中，从1级开始：无 em dash 或 en dash（除非作者的样本使用了它们），使用直引号，句子大小写标题，冒号后小写，无表情符号，仅对已定义术语或警告使用粗体，无粗体标签列表，所有可粘贴的内容使用代码块。完整列表见 references/process.md。
10. 语言
使用用户的语言与用户交谈。工件的语言遵循第一匹配的行：
| 情况 | 语言 |
|---|---|
| 所有者要求了某种语言 | 所要求的语言 |
| 工件已存在 | 工件所在的语言 |
仓库声明了策略（CLAUDE.md / AGENTS.md，或最新PR标题和提交信息的语言） | 仓库的语言 |
| 以上都不能决定 | 英语 |
当两行真正竞争时，询问一次。
技术术语、产品名称、资源类型和 cmdlet 在两种语言中都保持英文：conditional access、blast radius、drift、Set-MgUser、AKS。永远不要编辑错误消息、日志行、文档标题或现有工件时将其作为副产物进行翻译。
11. 流程
每个任务都有不同的门控，因为可用的证据不同。每个任务的分步指南、修复循环和完整扫查：references/process.md。
| 任务 | 门控 |
|---|---|
| 编写 | 覆盖列表（事实、需求） |
…
[已截断用于翻译]