用途:在需要给出清晰、可评审、易扫描的反馈时使用本技能,适用于代码评审、文档评审、设计反馈、RFC 评论、编辑批注等任何重视语气与可执行性的反馈场景。来源标准为 https://conventionalcomments.org/。
核心格式:每条评论写成 <label> [decorations]: <subject>,可选再附 [discussion]。label 是单一意图标签,如 suggestion、issue、question;decorations 是可选、逗号分隔、放在括号内的上下文标签;subject 是直接评论;discussion 是可选的支持性理由或下一步。
标签选择:应选最窄且准确的标签。praise 用于指出真正值得保留的优点;nitpick 用于琐碎的偏好性修改,通常非阻塞;suggestion 用于提出改进并说明改什么、为什么;issue 用于指出具体问题,尽量附建议修复;todo 用于标记必要的小任务;question 用于不确定时请求澄清;thought 用于分享不阻塞工作的相关想法;chore 用于验收前必须完成的流程步骤,尽量附链接;note 用于提供无需行动的上下文。可选表达性标签包括 typo、polish、quibble。
装饰标签:仅在增加有用上下文时使用,常见有 (blocking)、(non-blocking)、(if-minor),也可用 (security)、(test)、(ux)、(performance)、(docs)、(accessibility) 等限定范围。装饰列表应保持简短,过长则拆分为多条评论。
工作流:先确定评审意图,再选一个最匹配的标签;仅当装饰会改变作者优先级或理解时才添加;subject 写成具体完整句子;discussion 仅在解释原因或给出解决方式时添加;对 issue、suggestion、chore、todo 明确期望动作;不确定时用 question 而非夸大问题。
语气规则:直接说明请求的修改;区分偏好与正确性;避免“这是错的”“修一下”这类模糊表述;避免表演式赞美,praise 只在具体且真实时使用;优先一条可执行评论,而非多条松散相关意见。
输出模式:单条评论只返回该评论;批量评论按列表分组。用于 Codex 行内代码评审时,把 conventional comment 文本放在代码评论的标题或正文中,并让评论绑定到最小有用行范围。
质量检查:每条评论以 <label>: 或 <label> (<decorations>): 开头;标签匹配真实意图;优先级可能被误解时明确阻塞状态;subject 脱离 discussion 也能独立成立;discussion 补充理由、上下文或下一步;需要行动时提出具体动作。
限制:资料未提供安装命令、平台支持范围、收费或价格信息,暂未提供。