用途:为技术沟通提供核心写作原则,适用于撰写或润色提交信息、PR 描述、分支名称和技术文档。
两个目标:一是告知,帮助读者理解并记住工作内容;二是宣传,说明价值,让评审者觉得投入评审的时间值得。
痛点模式:仅围绕真实痛点组织信息,结构为「观察到的问题」加「下游影响」。痛点应描述真实体验,例如报错、重复流程、昂贵过程或令人困惑的行为,以及由此产生的后果。示例:不好的是「缺少通用接口」,好的是「本地开发编排在多环境间重复,导致副本彼此失步」。
句式结构:优先使用「[动词] 收益 by 机制」或「[动词] 机制 for 收益」,例如「speed up local dev by automating config and log formatting」「prevent data loss by fixing the asset sync race」。
按产物区分格式:分支名用 TICKET/short-description,简短;提交主题用 TICKET: type(scope): verb benefit by mechanism,不超过 100 字符;提交正文只写痛点,中等长度;PR 标题与提交主题相同,简短;PR 描述为痛点加一行方法说明,中等长度。
反模式:避免「Add feature」「Fix bug」「Refactor code」「Update dependencies」,避免在 PR 正文中写解决方案清单,避免用通用抽象代替观察到的问题。不要写以解决方案为主的 PR 正文,评审者会自行查看 diff;也不要仅为重复改动中已可见的内容而添加测试计划章节。
限制:资料未提供该框架的安装方式、收费模式或平台支持等具体信息。