维护 .github/ISSUE_TEMPLATE/ 下的 GitHub Issue Form 时,优先保证提单人填写体验。结构化字段是为了帮助提单人说清需求,不是把内部流程、仓库路由或 AI 分析责任前置给提单人。
- Issue Form 是给提单人填写的,所有用户可见文案都必须像是在直接和提单人说话,优先使用“你/请”;不要用“用户”称呼提单人。
- 不要把系统设计者、维护者或 AI 分析流程中的概念暴露给提单人。例如“无需判断由哪个仓库负责”“目标仓库”“归属”这类路由说明,对不了解组织仓库结构的人会制造额外疑惑。
- 不要要求提单人理解社区内部角色或流程术语。例如“产品/需求接口人”“项目维护人”“验收人角色”等字段会引入解释成本;如非必要,应删除或改成普通人能回答的问题。
- 结构化字段必须服务于提单人的表达,而不是服务于内部系统收集更多元数据。字段越多、越技术化,越容易让提单人编造答案或放弃提交。
- 必填字段只保留提单人一定知道、且对理解需求必要的信息,例如遇到的问题、发生位置、影响对象、期望结果、不解决的影响、完成后如何确认可用。
- AI-ready 不等于把 AI 路由、仓库归属、owner 判断、验收责任前置给提单人。AI 应从提单人的自然描述中推断这些内容,不确定时再由后续 triage 或需求分析阶段补充。
- 技术影响范围可以保留为可选项,但要使用提单人更容易理解的语言;如果不确定,应允许不选或选择“不确定”。
- 编写或修改 Issue Form 时,逐句检查用户可见文案:这句话是否帮助提单人更好描述问题?是否引入了他原本不需要知道的新概念?如果只是解释内部流程,应删除或改写。