AI 技能人工智能【免费下载链接】skillsAnthony Fus curated collection of agent skills.项目地址https://gitcode.com/gh_mirrors/skills11/skills点击查看免费下载PR 正文是代码评审的第一道入口一份好的正文应当让审查者“只看正文就能理解变更”而不是去翻 diff 猜意图。本指南以 antfu-create-pr 技能中的 pr-body 决策指南为骨架结合 SKILL.md 的完整工作流与 visual-evidence 的截图取证规范系统讲解 Summary、Change map、Architecture and behavior、Boundaries and risks、Visual changes、Rollout and follow-up 每个分区何时该写、怎么写、写出什么效果。读完本文你将掌握一套可复制、与变更规模成比例、处处有证据可溯的 PR 正文写作方法。一、核心原则按需取用章节而不是机械套模板pr-body.md的 frontmatter 用一句话定义了这份文档的本质它是每个 PR 正文分区的决策指南与模板Decision guide and templates for each PR body section。其中有一个贯穿全文的约束Summary 和 Verification 始终存在其余每个分区只在能让评审更快或更准时才添加。这意味着一份合格的 PR 正文不是把所有标题都堆上去而是回答一个前置问题审查者需要知道什么原文给出了一个极简示例一个小的局部改动正文就是Summary 一行closes #N 一个Verification块仅此而已。同时要遵循一条铁律不要为了填满标题而编造内容Do not invent content to fill a heading。在 antfu-create-pr/SKILL.md 中这条原则被进一步展开为正文与变更成比例一行代码的修复几句话即可跨模块的特性用表格和图表。并且始终遵守证据纪律Evidence discipline说清楚什么是已验证verified、什么是假设assumed、什么是未验证not verified没有证据支撑就不要写 safe、fixed、backward compatible 这类结论绿色 CI 只能证明 CI 所跑的检查聚焦测试只能证明它们覆盖的行为。这套方法的来源据 README 说明是从 moeru-ai/airi 的 create-pr 技能适配而来——保留了其 merge-base 与 stacked-PR 处理、变更地图、行为图、边界与验证映射、视觉取证工作流并结合了 Anthony Fu 的 PR 写作惯例。下文逐节拆解每个分区。二、Summary以问题或能力开篇再说结果与原因Summary 是每份 PR 必备的第一节写法遵循固定顺序先抛问题或能力the problem or the capability再给结果what changed最后解释为什么选这个方案why this approach。原文示例## Summary Uploads over ~10MB failed silently because the client dropped the response body on a 413. This surfaces the error to the caller and retries once with chunked transfer. closes #482注意示例的三个层次第一句陈述故障现象与根因客户端在收到 413 时静默丢弃响应体第二句给出修复结果把错误暴露给调用方并用分块传输重试一次最后用closes #482关联 issue让 GitHub 自动链接并支持合并时自动关闭。针对stacked PR叠放式 PR需要显式声明依赖关系与归属范围例如Stacked on #480; only the last two commits belong to this PR.这行声明在 SKILL.md 中有一条配套规则不要把父分支继承下来的变更描述成本 PR 的变更Do not describe inherited changes from a parent branch as this PRs changes两者互相印证。三、Change map模块级前因后果表拒绝文件清单当 diff 触及多个模块或在模块之间转移职责时使用 Change map。它有两个关键约束行是模块或边界modules or boundaries不是文件绝不使用原始文件列表Never a raw file list。模板如下## Change map | Module | Before | After | Description | | --- | --- | --- | --- | | upload/client | Swallowed non-2xx responses | Maps 413 to PayloadTooLarge, retries once chunked | Callers can distinguish size errors from network errors | | cli/upload | Printed generic failed | Prints the mapped error and hint | Actionable output for users |每行回答三件事这个模块原来是什么行为、现在是什么行为、为什么值得让审查者知道。上面的例子中upload/client的行为变化是吞掉非 2xx 响应 → 把 413 映射为PayloadTooLarge并分块重试一次其价值是调用方能区分大小错误与网络错误cli/upload的变化则是把笼统的 failed 输出换成映射后的错误 提示让终端用户得到可行动的反馈。当变更本身即目录结构调整时可以用一棵简短的职责树responsibility tree代替表格server/ ├── routes/ # accept and validate input ├── domain/ # own the invariants └── adapters/ # talk to external systems树的注释标注每个目录承担的职责routes 负责接收与校验输入、domain 负责持有不变式、adapters 负责对接外部系统让审查者一眼看懂职责边界在哪。四、Architecture and behavior用图说话且图必须可溯源当一张图比一段散文更快地解释变更时才使用本分区。图表的使用原则是节点名必须绑定真实模块或符号箭头必须标注调用、事件或数据按变更性质选图型跨模块特性或边界迁移 → 模块流程图flowchart LR排序变化、异步工作、重试、取消、清理 → 时序图sequence diagram每个alt分支必须对应一个真实代码分支状态迁移或终止态变化 → 状态图state diagram。原文给出了一个完整的 Mermaid 时序图示例演示413 后分块重试的完整调用链图中 CLI → UploadClient → Server 的参与者命名都对应真实代码层alt 413与else success两个分支分别对应客户端错误映射逻辑与正常路径返回的AssetUrl是调用方的最终结果。对于改变流程或状态的修复类 PR规范要求给出同一抽象层级的Before/After图对并明确点出到底是哪条边或哪个步骤变了这样审查者无需自己 diff 两张图。反过来如果审查者预期这里会有图但实际不适用就应当直接声明例如Not applicable: only renames a constant, no runtime flow changes.五、Boundaries and risks不变式、失败模式、防护与证据一一对应当变更存在真实的失败模式、不变式invariants、迁移或外部影响时用四列表格把风险变成可核查项并且只保留真正有意义的行## Boundaries and risks | Invariant or boundary | Failure mode | Protection | Evidence or gap | | --- | --- | --- | --- | | Retry happens at most once | Infinite loop on persistent 413 | attempt counter, hard cap of 1 | upload.test.ts does not retry twice | | Chunked upload is idempotent | Duplicate asset on retry | Server dedupes by content hash | Not verified in this PR |四列的含义分别是不变式或边界你要守护的承诺如最多重试一次失败模式违反该承诺会怎样如持久 413 导致无限循环防护措施用什么机制兜底如attempt计数器硬上限为 1证据或缺口测试名、文件路径或如实标注Not verified in this PR。注意第二行幂等性依赖服务端按内容哈希去重但本 PR 没有验证这一点因此证据列如实写作 Not verified in this PR而不是把风险问题包装成结论。原文有一句直接的规定写Not verified而不是把风险问题变成声明WriteNot verifiedinstead of turning a risk question into a claim。原文还给出了一个风险扫描清单写正文时应逐项过一遍命中哪项就补哪行输入校验与鉴权input validation and auth失败映射、重试、重复、并发、排序、清理failure mapping, retries, duplicates, concurrency, ordering, cleanupschema 变更、回填、回滚schema changes, backfills, rollback日志或错误载荷中的机密泄露secrets in logs or error payloadsUI 的加载、错误、空态、过期态、重复操作态UI loading, error, empty, stale, and repeated-action states。六、Visual changes仅限用户可见的 UI 变更图片行在下、标签行在上本分区只用于用户可见的 UI 变更模板采用图片行在前、标签行在后的两行表格## Visual changes | Before | After | | --- | --- | |  |  | | Settings / Connection, 1440x900, dark | Settings / Connection, 1440x900, dark |标签行需要说明位置、视口尺寸、主题等复现条件上例为 Settings / Connection, 1440x900, dark确保前后截图的对比条件一致。新增的状态用Absent表示删除的状态用Removed表示。完整的取证与附件流程在 visual-evidence 中展开要点包括用git worktree add --detach检出 merge-base避免污染工作分支前后两张截图必须使用相同的视口、主题、语言、夹具数据与就绪条件截图写入被忽略的目录如.pr-shots/base/id.png与.pr-shots/head/id.png逐张检查图片拒绝空白、加载中、报错或不稳定的截图除非该状态本身就是变更主题通过 GitHub CLI 2.99 的gh pr create --attach上传到 GitHub user-attachments 存储而不是提交进仓库对应 SKILL.md 中Do not commit screenshots or other PR-only artifacts to the repo的规则。七、Rollout and follow-up发布计划与已知缺口并声明是否阻塞合并这是一个可选分区适用于涉及以下内容的变更数据迁移migrations特性开关feature flags分阶段发布staged rollout监控monitoring已知缺口known gaps需要后续跟进的 PRrequired follow-up PRs。它的硬性要求是对每个缺口明确声明它是否阻塞合并State whether each gap blocks merge。这样审查者无需猜测这里没做完能不能合发布计划的决策权透明地交给评审流程。该分区不需要模板表格两到三行清晰的声明即可。八、与 SKILL.md 工作流的衔接标题、必备分区与写作规则pr-body.md是 antfu-create-pr 技能的第三步产物——SKILL 的完整流程为检查仓库 → 计算 merge-base 与base...head范围 → 通读 diff 并追踪调用链 → 分类 PR 并挑选分区即本指南内容→ 运行针对变更面的检查 → 截取 UI 证据 → 写入临时文件并用gh pr create --body-file创建 → 打开 PR 复核 → 处理评审意见。把正文写作放入这个流程还需要掌握以下配套要求每份 PR 必备## Summary问题或能力优先再讲变更与方案stacked PR 需注明关联 issuecloses #123/fixes #123/refs #123## Verification精确记录运行的命令与结果以及哪些没有验证。标题规则Conventional Commits与仓库既有提交风格一致feat(scope): add retry to upload client fix(scope): avoid double submit on enter refactor: extract diff parsing from cli chore(deps): update vite to v8 docs: clarify worktree setup小写、祈使句、无结尾句点、70 字符以内scope 使用仓库既有的包名/模块名仓库级变更可省略squash-merge 的仓库会把标题直接变成提交信息因此要按你希望留在历史上的提交来写。正文写作规则清单使用普通连字符-禁止 em dashU2014与 en dashU2013禁止 filler 措辞This PR aims to...、comprehensive、robust以事实开头禁止在正文粘贴 token、密钥、用户记录或完整 payload截图等 PR 专用产物不得提交进仓库用gh --attach附件上传如果 PR 由 Agent 辅助编写在正文末尾用一行声明。如果仓库自带 PR 模板则保留模板的标题并填写内容只在模板留白处补充上述分区SKILL.md 原文If the repo has a PR template, keep its headings and fill them; add sections above only where the template leaves room。九、写作前的自查清单把上述要点压缩成发布前的最终检查Summary 是否以问题/能力开篇并包含closes #NVerification 是否记录了精确命令与结果未验证项是否如实标注每个可选分区是否为审查者而写而非凑标题小改动是否只保留了 Summary issue VerificationChange map 是否按模块而非文件组织且每行有 Before / After / Description 三要素图表节点是否绑定真实模块或符号alt分支是否对应真实代码分支修复类 PR 是否有Before/After图对风险表格是否四列齐全不变式 / 失败模式 / 防护 / 证据或缺口无法验证的是否写了Not verifiedUI 变更的截图是否前后条件一致、以附件上传而非入库全文是否只用普通连字符、无 filler、无机密内容这套方法的核心始终是那句话按审查者需要选择分区而不是按模板机械填充——正文的每一行都应该帮助评审更快、更准地做出判断。赞分享AI 技能人工智能【免费下载链接】skillsAnthony Fus curated collection of agent skills.项目地址https://gitcode.com/gh_mirrors/skills11/skills点击查看免费下载相关推荐antfu-create-pr 技能实战用 Conventional Commits 标题与证据驱动正文打造可审查的 GitHub Pull Requestantfu create pr 技能实战用 Conventional Commits 标题与证据驱动正文打造可审查的 GitHub Pull RequestAI 技能人工智能antfu-create-pr 技能实战用证据驱动工作流创建可审查的 GitHub Pull Requestantfu create pr 技能实战用证据驱动工作流创建可审查的 GitHub Pull Request 导读 本指南以 skills/antfu creAI 技能人工智能Hexclave 视觉化 PR 描述写作指南基于 pr-body-template 的 Before/After 截图矩阵与 GitHub PR 正文编排Hexclave 视觉化 PR 描述写作指南基于 pr body template 的 Before/After 截图矩阵与 GitHub PR 正文编排 导后端认证鉴权前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考