write-openspec-docs

编写 OpenSpec 文档

你现在要编写 OpenSpec 的用户文档。请阅读 writing.md；它是本文档写作的风格准则。立即生效的简要版如下：

• 页面是供读者查找信息的界面，不是散文。结构决定读者能否找到答案；文字只决定答案读起来如何。每个部分开头都要直接给出答案，不要铺陈叙事。
• 先确定页面类型，再拟定大纲。指南围绕读者的任务展开；参考文档则映射产品结构，并使用准确的字段名、命令名和文件名作为扫描锚点。参考文档必须覆盖完整，不能把多个事实压缩到一个句子、单元格或段落里。
• 写出能回答问题的最短版本；扩充简短的页面成本很低，删减臃肿的页面则相当于重写。用词朴素，越少越好：一个想法能用一行说清，就只写一行。大多数读者用不到的深入内容放到链接后，核心内容（命令、实际输出、故障与解决方法）必须完整保留。
• 句子简单，结构清晰。写直白的句子（主体、动词、宾语，说明实际发生的事）；不要压缩额外事实，也不要刻意变换角度。不要用夸张的形容词、铺垫语或破折号。
• 每个位置只做一件事：每个句子只陈述一个事实；列表引言只用于引出列表；每个部分只回答一个读者问题或对应一个查找目标。相关事实要有自己的位置，不要附带在其他内容中。
• 让条目以读者可验证的内容为依据：先写路径或文件夹，再补充概念说明；如实展示实际输出。
• 不要套用固定模板。清单先列出所有项目，再在清单后分别为每项设置独立单元展开说明，绝不要在行内展开。按顺序执行的内容使用编号步骤（编号代表顺序；清单使用项目符号）。单一想法和推理用简短文字说明。
• 所有关键事实都要放在便于扫描的锚点上：代码块、带编号的粗体引导语、**术语**：事实 项目符号、表格或文件树。绝不要只把它们放在段落中间。
• 完成前，进行两项兜底检查。可检索性：只靠扫描能否找到每个问题或准确的产品名称？一眼观感：检查渲染后的页面结构，看它是否显得一目了然、易于完成阅读，而不是像一项工作。对于表格较多的改动，要在桌面端和窄屏宽度下检查。失败说明某个内容位置缺乏必要性；现在就修正，不要留给审核时再处理。

基本规则

• 起草前加载 no-ai-slop 技能；它负责通用的 AI 垃圾内容模式，而 writing.md 规定 OpenSpec 文档的具体呈现方式和写作风格。
• 编辑前完整阅读目标页面。
• 只写真实事实：标志、路径和输出都必须与源码一致。如果某项声明无法轻易核实，仍要写出，但在展示相关内容时标明它尚未核实；绝不要用听起来合理的句子弥补信息缺口。
• 每个事实只归属一个页面；其他页面都链接到该页面。文档树中的 README 负责页面索引和结构约束；重组内容或新增页面前先检查它。
• 对于参考文档，起草文字前先从源码梳理完整规范。遵循 writing.md 中的参考文档流程。
• 如果不确定内容应如何呈现或措辞，应参考范例：docs-lab/start/setup.md 展示章节结构和清单写法；docs-lab/start/installation.md 中的 Uninstalling 部分展示多步骤任务写法。

完成后

向用户说明改动内容，并指出任何尚未核实的声明。

如果用户要求进行深入的、以证据为先的起草流程（运行每条命令、每次专注编写一个部分、设置正式检查点），请遵循 full-process.md。