为开发者编写安全文档并进行审查

## 写出开发者能直接用的建议，并只谈安全问题 面向开发者而非安全专家编写内容。指南必须准确、实用、简洁，并提出明确观点。与其提供理论上最佳却复杂到难以遵循的建议，不如优先提供开发者能够应用的良好建议。 所有建议都应限定在文档的安全威胁模型内。除非一般性的代码质量、性能或架构建议能直接控制安全风险，否则应在其他地方讨论。 对于所有创作工具，都必须将贡献规则视为强制要求。保留代码库中权威的人工流程和编写指南，仅将较短的智能体指南用作操作摘要。 ## 读完每个引用来源，确认它支持所写的说法 获取并阅读每个引用来源，然后确认其准确支持相关主张。绝不能编造或猜测URL，不能引用重定向到无关落地页的页面，也不能依赖训练记忆或摘要。应链接到包含支持证据的具体页面或章节。 使用内部交叉链接之前先进行验证。不得指向不存在的文档或锚点。 在引用密度门槛适用时，每个新增H2章节中至少应包含一条内嵌HTTPS引用。对于新颖、出人意料、依赖特定参数或存在争议的主张，应分别提供支持；对于已确立的常见实践，不必每句话都加引用。来源既可内嵌于正文，也可集中列入参考资料章节。 优先采用标准、政府或行业安全指南、项目和供应商的官方文档、维护良好的平台资料、规范的源代码库以及经过同行评审的研究。避开以搜索优化为目的的营销内容农场。引用门槛只是最低要求，并不能证明内容正确。 ## 为每个威胁写出对策，并说明它防不住什么 引用是必要条件，但并不充分。为每项威胁配对具体的应对措施，并明确说明该控制措施能防范什么、不能防范什么。 不得在没有明确说明限制条件的情况下，引入既定威胁模型之外的攻击。针对某一层的控制措施，不得被表述为能够防范另一层遭受入侵。 只添加确实属于安全控制措施或安全风险的指南。应分别审查正确性、对开发者的实用性和主题相关性；即使一项建议引用充分，只要内容错误，仍必须拒绝。 ## 每次改动保持小范围，已有内容用链接而不是复制 一次变更应限制在一份指南文档，或一组规模小且协调关系明确的文档内。如果代码库规定了这些上限，则在没有获批跟踪议题的情况下，不得超过三份内容文档或净增加1,500行。依赖项、自动化以及仅修正错别字的变更，应遵守各自的范围规则。 从基于默认分支的干净分支开始，每个分支只处理一个主题。绝不能从同一分支发起两项变更请求，因为不相关的变更可能在两者之间混入。在提议新增指南文档或大幅重写现有指南文档之前，必须先获得议题批准。 不要捆绑顺手进行的格式调整、批量编辑或无关修复。添加章节前，应搜索当前文档、相关文档和代码库索引。应链接到现有指南，而不是重复其内容。 保留有意设计的中心辐射式文档系列。经过协调的交叉链接是有效的，但复制另一份文档的指南则不是。如果内容属于其他主题，应将其移至适当的现有文档或新文档，而不是勉强扩大当前范围。 ## 先讲设计思路，只在主题需要时才写代码 对于一般性主题，应优先讲解架构模式、设计原则和安全决策，而不是特定语言的代码。代码很快会过时，脱离原始上下文的独立代码片段在被复制后可能并不安全。 当主题本身与特定语言、注入、参数化或具体加固措施密切相关时，可以充分使用代码。如果可执行细节本身就是安全指南，而不是附带的样板代码，较高的代码占比是合适的。 示例代码应保持简短，并在可行时为围栏代码块标注语言。除非示例已经按照生产标准完成设计和审查，否则不得将其表述为可直接用于生产。 ## 删掉空洞的开场白，明确推荐一种做法 去掉空泛的前言、重复的背景、穷举式选项列表，以及追逐潮流却没有实质内容的开场。推荐一种具体方法，并只说明开发者安全应用该方法所需的上下文。 使用美国英语，运行拼写和术语检查，并让非母语读者也能理解句子。首次使用不明显的缩写时应给出定义；如果风格指南允许，则无须解释所有人都熟悉的协议和定位符缩写。 对于听起来像通用自动生成文本的段落，应重写或不予采用。精简内容时，不得丢失约束、例外、威胁边界或某项建议更安全的原因。 ## 遵守代码库关于Markdown和图片的规定 使用Markdown；除明确允许的元素（如`details`和`summary`）外，应避免使用原始HTML。统一使用连字符项目符号、Markdown粗体和块引用。每个标题后都应留一个空行。 典型文档以一个H1和“引言”开始，随后是重点明确的H2章节，并可在末尾添加参考资料。三至六个H2章节是实用的默认值，而不是硬性上限。如果发布工具会生成目录，则不要手动添加目录。 遵循代码库的文件名规范。只使用字母、数字、连字符和下划线，并保留`_Cheat_Sheet.md`等必需后缀。新增文档应从获批模板开始。 将资源存放在指定的资源目录中。使用获批的图像格式，提供有意义的替代文本，并通过正确的相对路径引用资源。链接应使用描述性标签内嵌书写，并尽可能采用HTTPS。 ## 请求审查前先运行lint和链接检查 提出变更前，运行代码库规定的Markdown检查、术语检查和链接检查器。同时运行适用于已修改内容的范围、引用密度以及其他策略门槛。 本地或持续集成检查失败时，应将其视为需要调查的缺陷，而不是绕过门槛的理由。审查最终差异，确保生成或自动执行的变更没有掩盖无关编辑。 应理解自动化的局限。机械检查能够发现格式错误的Markdown、禁止使用的术语、失效链接、范围过大以及缺少引用模式等问题，但无法判断来源是否支持主张、建议是否正确、主题是否应属于该文档，或者内容是否与现有指南重复。 ## 说明AI的使用情况，并从多个角度审查 在变更请求说明中披露实质性的AI辅助。应在代码库指定的披露章节中记录工具名称、已知版本和提示词。这一要求适用于所有AI工具；遗漏披露可能使贡献无效。 从相互独立的维度审查安全指南：安全正确性、对开发者的实用性、来源和链接质量、重复与内容位置，以及语言质量。专业审查者可以独立工作，但其发现应汇总为一个基于证据的结论。 使用接受、要求修改或关闭等明确结果。对于构成阻断的问题，应引用具体证据，区分机械检查失败与判断失败，并且不能仅仅因为存在引用或自动检查就予以批准。