lowly-writing-framework

面向开发产物的写作框架

PR 正文、议题正文、讨论、审查评论、文档、代码注释和需求的结构与机制。PR 描述是对审查者的体贴；文档和注释是对下一位读者的体贴。本技能决定产物必须包含什么内容以及如何布局，而不决定其表达方式。

范围

本技能仅负责结构与机制：产物包含什么内容、各个章节位于何处、引用是否会自动链接，以及哪些 grep 命令能捕捉到疏漏。下方的路由表列出了本技能涵盖的所有主题。

语气、口吻、幽默、标点偏好和措辞风格均不在范围内。单独安装的语气包技能可以在此基础上添加这些内容；两者都已安装时，它们都适用于同一产物：本技能负责内容的安排，语气包负责文本的呈现方式。

以下的 Formatting、Never trim these、Boundaries 和 Anti-patterns 适用于所有情况。对于 PR、审查评论或文档／注释专属内容，请在准备撰写相应产物时打开匹配的参考文件：

• 起草 PR 标题或正文 → references/pr-writing.md（标题、关闭议题的规则、如实说明测试情况、默认以带注释的行内评论形式发布作者对差异的注释、AI 水印）
• 起草议题正文 → references/issue-writing.md（标题、模板选择、相关工作引用、避免在正文中提出解决方案）
• 起草 Discussion 帖子、评论或回复，或标记答案 → references/discussions.md（帖子类型、从仓库的实际分类中选择类别、串接讨论和标记答案的机制、以书面结论收尾、使用点赞而非“+1”评论）
• PR、议题和 Discussion 帖子共用的正文结构（填写模板、Context 部分、链接 PR 已包含的文档、长度上限、图表）→ references/body-writing.md，并与上述三者中适用的一项搭配阅读
• 在 PR／议题正文或文档中添加图表、地图或 3D 模型，或决定使用表格还是图表（任何日程、时间线、推出计划或流程）→ references/diagrams.md（从 GitHub 支持的所有格式中选择：mermaid 图表类型、geojson、topojson、stl；GitHub 渲染机制、已知的 GitHub 限制、主题／样式、颜色编码图表的图例）
• 审查他人的 PR → references/review-comments.md（先阅读现有评论和讨论串，避免重复指出问题；审查顺序和优先级；交付方式：分阶段审查、带注释的行内评论或 PR 级评论；常见评论标签；问题与提供的修复方案；建议的修改）
• 回复他人对自己 PR 的审查反馈、解决讨论串问题或重新请求审查 → references/review-replies.md（回复方式、匹配审查者的标签、发布前由用户审查、回复前调查相关说法、用证据表达异议、何时解决问题或询问审查者、每轮审查后的更新）
• 修改 README、文档或代码注释 → references/docs-and-comments.md（使用现在时的规则）
• 撰写设计文档、RFC 或回顾总结 → 阅读 references/body-writing.md 了解章节结构，阅读 references/docs-and-comments.md 了解时态；长篇文字的逐句架构属于 voice-pack 的范畴，不在此处介绍
• 对任何 PR 正文、文档或评论进行最终成品自检 → references/self-check.md
• 在专门的需求文档中，或在评论／PR／提交中内联地定义、澄清或实现需求或验收标准 → references/requirements-ears.md（EARS 语法、文档模式与内联模式）
• 检查草稿中是否包含禁用的 AI 时代措辞 → references/banned-phrases.md
• 撰写实际执行者是另一个 AI、却归于人类名下，并明确以“肉身代理模式”调用的内容 → references/meat-proxy-mode.md
• 直接通过 gh CLI 发布或编辑任何内容 → references/gh-cli.md（编辑前先获取内容、shell 转义、-f／-F、重新获取以验证、按行定位的建议修改、暂存待用户提交的审查、在暂存审查中阅读现有审查评论并回复、回复和解决审查讨论串、gh discussion 和仅限 GraphQL 的 Discussion 修改操作）
• 起草 PR、议题或 Discussion 正文 → 还需阅读 references/calibration-examples.md 中的 Bodies 部分；若是 PR，还需阅读其 PR Testing section 和 PR author annotations 部分（其中包含有关判断规则的前后示例；审查评论、代码注释和文档无需阅读此文件）。在肉身代理模式下，也需阅读其中的 Meat proxy mode 部分

格式

• 反引号用于包围读者会输入、粘贴、搜索的字面文本，或工具会逐字解析的内容：命令、标志、配置键和值、环境变量、代码标识符、确切的错误文本，以及读者必须打开的文件路径。逐项判断：读者会把它复制到终端、编辑器或搜索框中吗？如果不会，就不要使用反引号。例外：问题 / PR 引用（owner/repo#123）不要加反引号，否则会禁用 GitHub 的自动链接；请参阅下文的“问题引用”规则。
• URL（任何以 http://、https:// 或 www. 开头的内容）绝不要加反引号，包括 localhost 和占位符 URL：行内代码不会自动链接，因此会显示为无法点击的文本。上述复制粘贴测试不适用于 URL；请将其写成裸链接、带名称的 Markdown 链接或纯文本。围栏代码块内的 URL，或读者要粘贴的命令行中的 URL，仍应保持原样。
• 名称不是代码：仓库、组织、GitHub Apps、团队、服务、云角色和账号、产品，以及作为专有名词的工作流或作业名称，即使带连字符或全为小写，也应保持普通文本。仅用于说明变更内容的文件名也应保持普通文本；只有读者必须打开或编辑的路径才加反引号。
• 在术语首次出现时，或需要精确表达时（例如命令中的路径、必须完全匹配的值）使用反引号，不要每次重复都加。段落中反引号大约超过三处，或正文中超过八处时，请重新逐项检查。
• 不要堆叠反引号：连续出现四个或更多以逗号分隔的标识符，读起来和完全不加格式一样费力。请将每项放入嵌套子项目，或在正文中只说明一次资源类型，并仅对审阅者可能会误解的内容加反引号。
• 优先使用最多两层的嵌套无序列表，而不是包含多行内容的扁平列表。
• 权威来源应以内嵌的带名称 Markdown 链接形式引用，绝不要使用裸 URL（例外：GitHub 问题 / PR 裸 URL；GitHub 会将其显示为独立的富文本 owner/repo#123 引用；以及单独成行、带行号锚点的代码永久链接；只有将其裸贴时才会展开为代码预览）。如果某人的工作促成了这项变更，请注明其姓名；如果用户提到某人却未提供 GitHub 用户名，请按照 references/gh-cli.md 中“查找人员姓名”的说明查找。
• 问题引用：每次提及都必须使用完整的 owner/repo#123 格式，包括同一仓库内的引用，这样就无需逐条判断是否属于同一仓库。绝不要只写 #123，也不要省略所有者写成 reponame#123。任何部分都不要加反引号，包括仅包围 owner/repo 的反引号：GitHub 只会自动链接一段连续的纯文本（本页的反引号仅用于展示语法）。绝不要根据 PR 自身的 URL 手动拼接问题 URL，.../pull/456#issue-<id> 并非问题 URL；请使用 gh issue view 123 --json url 获取正确链接。
• 防止链接失效：如果链接承载某项论断，请在链接旁引用相关的那句话，作为在链接失效或版本更新后仍能保留的可靠副本。
• 按主题将正文拆分成段落，每段表达一个观点。一个段落如果论证多个要点，或超过 4-5 句话，就需要拆分。
• 每句话只表达一个要点。若一句话通过括号和逗号分句堆叠了机制、权衡和结论（例如“代价是……”或“尤其因为……”），即使段落未超出句数限制，也包含了多个观点：应按观点而不是句号计数。将堆叠的分句分别拆成独立句子，或在内容可枚举时拆成独立项目。语气指南可对长篇文档（设计文档、RFC）放宽此要求；PR / 问题正文、审阅评论和代码注释仍须遵守。
• 链接指向代码时，应使用精确行号的永久链接（提交 SHA，而非分支名，并带 #L10-L20），而不是仅链接到文件：GitHub 会为带行号锚点的永久链接渲染代码预览，裸文件链接不会。
  • 格式：GitHub.com 的 blob URL，以 /blob/FULL-SHA/PATH#L10-L20 结尾，单独成行以展开预览（Markdown 文件链接或带名称的链接仍是普通链接）。绝不要使用分支名或短 SHA，它们可能变化；如果无法解析 SHA，请说明情况，不要链接到分支。
  • SHA：gh api repos/<owner>/<repo>/commits/<ref> --jq .sha（当前仓库：git rev-parse HEAD）。使用 2>&1，不要使用 2>null，这样失败时能看到错误。
  • 行号：从该 SHA 对应的文件中读取，绝不要凭记忆或手动计数。使用 gh api -H "Accept: application/vnd.github.raw" "repos/<owner>/<repo>/contents/<path>?ref=<sha>" 并通过管道传给 grep -n '<pattern>'（PowerShell：Select-String、.LineNumber）。保持管道连接，不要在工作树中创建临时文件；URL 中使用 ?ref=，不要使用 -f ref=，否则调用会变成 POST。
• 在 GitHub 按 Markdown 渲染的界面（PR 正文、PR 审阅评论、README / Wiki 文档）上，如果某行确实是读者不应略过的提示，请使用 GitHub 提示语法 > [!NOTE]、> [!TIP]、> [!IMPORTANT]、> [!WARNING]、> [!CAUTION]，而不是单独使用 Note: / Warning: 前缀。普通句子仍是默认写法，不要把每个补充说明都包装成提示。对于不渲染 GitHub Markdown 的界面（提交消息、终端 / CLI 输出、非 GitHub 追踪系统），请跳过提示语法，直接使用 Note:。
• 删除线可用于长期保留的 PR 正文：如果经过审阅后方向有所调整，且需要在正文中直观显示转变，可以使用。不要用于修正拼写或措辞。
• 绝不要按固定列宽硬换行段落：源文件中的每个段落都应写在一行内。GitHub 会将段落内部的换行折叠为空格，因此换行只会让原始源码（gh pr view、编辑器、diff）看起来杂乱。仅在块级元素之间（标题、列表项、代码围栏）以及段落边界处换行。

绝不要删减这些内容

删掉填充内容，但绝不删减实质信息。即使这些内容会让文档变长，也必须保留：

• 破坏性变更，以及使用者必须如何应对
• 迁移和回滚步骤，包括任何需要手动执行的步骤
• 数据丢失和安全风险，必须明确表述为风险，不得弱化成注意事项
• 运行影响范围：生产环境中会影响哪些内容，出错时会通知谁
• 已知缺口和未经测试的路径，遵循 references/pr-writing.md 中的测试规则
• 观察到的症状：准确的错误文本、指向失败运行或事件的链接，以及根因机制
• 读者明确提出的任何内容。必须完整答复对方要求的操作说明、分阶段说明或审阅者的问题。简洁规则仅适用于对方未要求的内容

边界

此技能只规范写作，不规范变更本身。不要为了缩短文档而重塑差异、删除提交或缩小范围。需要长篇说明的变更，就应提供长篇说明。

工作流

• 无论用户是否明确要求起草、修改或审阅某项内容，此规则均适用：触发条件是即将产出某种文档内容（PR 文本、文档、评论、需求），而不是用户要求编写内容
• 每次执行以下操作前都要触发此技能，即使会话的主要任务是代码、基础设施或配置工作，而非“编写 PR”：
  • create_pull_request、update_pull_request
  • add_pr_review_comment、edit_pr_review_comment、reply_to_comment、reply_to_review_thread、reply_and_resolve_review_thread
  • 编写或编辑任何代码注释或文档行时，立即触发，以免叙述性语言在 PR 步骤前悄然混入差异
  • 定义、澄清或实施需求或验收标准时，无论涉及何种文档内容：使用 references/requirements-ears.md
• 在长会话中，不要依赖对系统提示中此规则的记忆：将上述每个触发条件都视为全新的要求，无论此前经过多少轮对话或无关工具调用
• 编辑现有 PR 标题或正文（或 GitHub 上的任何实时评论或文档）之前，始终先获取当前文本；绝不要依据对话中的早期草稿进行编辑，遵循 references/gh-cli.md
• 起草 PR 正文时，检查差异中以行号为锚点的旁注，以及偶然或无关的变更（根据 references/body-writing.md，即非范围内的实质工作）；每项内容都应写成注释，而非正文。PR 创建并推送后，发布这些注释（对于已有 PR，先检查作者身份）。用户是作者时，默认执行此操作，无需等待对方要求；以带注释的行内评论发布，绝不要使用待提交审阅或 add_pr_review_comment，遵循 references/pr-writing.md 中的“作者注释”
• 在宣布任务完成前，立即按照 references/self-check.md 对 PR 正文以及所有修改过的评论、文档和叙述性内容进行自检；此后每次修改也都要重新检查，始终针对完整的当前文本。每次 update_pull_request 调用都属于后续修改：发送前必须对即将提交的正文进行自检，结构化工具调用也不例外
• 直接通过 gh（而非 create_pull_request 等结构化工具）发布或编辑 PR／Issue 标题、正文或评论时，还会遇到其他失败模式，包括 shell 转义、-f 与 -F 的使用，以及未核实的发布；参见 references/gh-cli.md
• 提交信息的风格应符合 references/pr-writing.md 中的标题规范

反模式

看到以下内容应立即拒绝：

• 按文件逐一复述差异的冗长摘要
• 逐项列出所有受影响对象，而不是只说明一次类别并指出例外的点名清单
• 只解释如何做，却不解释为什么做：在该说明动机的地方讲实现细节
• 泄露内部讨论：开发过程中的来回讨论、会话笔记、“如前所述”、工具或 Agent 的叙述
• 罗列未采用的方案：被否决的方法、已撤销的实验，以及与最终差异无关的“我们选择不做 X”
  • 例外：如果一眼看去，采用的方法似乎不妥或不明显，可以用一句话说明理由；这不属于罗列未采用的方案，而是 references/body-writing.md 中的 Anticipated reviewer questions 模式
• 解释缺失内容：对已由关联子议题或跟踪议题明确说明的范围，再复述一遍“本文未涵盖”的内容。议题图已经从结构上展示了这些信息，用文字重述并不会告诉审阅者任何点击查看也得不到的新内容
• 仓库未要求的、自动生成的详尽检查清单
• 在现有模板基础上另行添加的加粗章节标题
• 过时的验证声明：后续编辑改变了声明所描述的内容，却没有重新核查测试或状态声明。这是信息偏差，不是捏造，但无论哪种情况，读起来都像在撒谎；请按照 references/self-check.md 对照当前差异重新验证