roasbeef-prose 是一份写作风格指南技能,用于在代表 Roasbeef 撰写任何文本时应用统一的写作规范。其目标读者是编写 PR 描述、提交信息、技术文档或博客等内容的写作者。
用途上,该技能定义了一种技术精确但口语化的声音,读起来像一位工程师在 IRC 上向另一位工程师解释事情,并刻意避免典型的 AI 生成文本套路。
主要能力方面,它规定了核心声音、应避免的写法、PR 描述结构、提交信息格式、技术解释方式、用词偏好以及段落节奏等。核心声音要求:提交正文和 PR 描述的默认开头是“In this commit, we...”或“In this PR, we...”,始终使用第一人称复数;不要用“This commit adds...”“Added support for...”或被动结构。语气直接随意但不松散,鼓励使用缩略形式(“we'll”“we've”“doesn't”“can't”),自然出现缩写(“w.r.t”“a.k.a”“etc, etc”“e.g.”),句子长度有变化。引用规范、BIP 或论文时首次提及内联链接,之后随意引用。面向 Bitcoin/LN 开发者时,领域术语(sighash、HTLC、nonce、tweak)无需解释。较长文本中,动机与设计意图部分用第一人称复数,协议描述转为中性第三人称。
应避免的写法包括:过度使用要点列表作为主要内容结构(散文段落为默认,要点列表仅适合 3-5 项简短枚举或 TODO 清单);“Key highlights”“Key changes”“Summary of changes”等章节标题;“comprehensive”“robust”“streamlined”“leverage”“utilize”“facilitate”“enhance”等词;任何形式的 em dash 均不得使用;填充式过渡词如“Additionally”“Furthermore”“Moreover”“It's worth noting that”“Notably”;自我夸赞语言;签名结尾或 emoji;以“this change”开句;AI 生成或共同作者署名行。
PR 描述结构上,开头用 1-2 段自然散文说明该 PR 做什么及为什么,开头固定为“In this PR, we...”。之后可用 ## 标题分节,但仍以散文为主。大型 PR 可注明“See each commit message for a detailed description w.r.t the incremental changes”。草稿 PR 中可用复选框 TODO 清单,但不应作为主要内容。
提交信息格式上,标题行为“子系统的:简短祈使式摘要”,冒号后小写,72 字符以内;子系统为 Go 包或组件名,多个包用“multi:”或“pkg1+pkg2:”。正文以“In this commit, we...”开头,用 1-3 段简短自然散文解释改了什么及为什么,侧重“为什么”。不要在正文重复标题,也不要添加文件变更的要点摘要。
技术解释上,先讲具体机制而非抽象框架,函数名、类型、变量名和简短表达式使用内联代码格式;代码示例应真实完整;基准测试与测试输出可用围栏代码块原样包含。
用词偏好给出替换表,例如用 use 替代 utilize/leverage,用 full/complete 替代 comprehensive,用 solid/reliable 替代 robust,用 allow/let/enable 替代 facilitate,用“In this commit, we add”替代“This change adds”,用具体数字或事实替代“significant improvement”。
段落节奏与流动方面,文本具有口述感,包括以连词开头的句子、口语式括号旁注、直接称呼与反问、从一项能力自然衔接到下一项、平淡干涩的幽默、用加号连接紧密耦合概念、用斜体强调关键概念、极少使用感叹号、使用自然连接词(Thus、hence、Once again 等而非 Additionally/Furthermore/Moreover)、段内预告行文方向、自然使用 i.e. 与 e.g.。整体校准目标是:像一个熟悉代码库的人快速写就,关注技术细节正确,但不雕琢华丽文辞,更像一封写得好的 IRC 消息或邮件列表帖子。
适用场景为遵循 Roasbeef 风格撰写 Bitcoin/LN 相关技术文本。其可用的平台支持、安装方式与运行要求暂未提供。