create-issue

创建 GitHub Issue

通过交互式澄清，根据用户描述创建结构良好的 GitHub Issue。

仓库检测

使用你所在平台的 CLI，根据当前 git remote 检测仓库。示例：

# GitHub lane (CODE_HOST=github):
REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')

# GitLab lane (CODE_HOST=gitlab):
REPO=$(glab repo view -F json | jq -r '.path_with_namespace')

两者都会拆分为 OWNER 和 REPO_NAME（或 GitLab 上的 NAMESPACE 和 PROJECT）。如果检测失败，请询问用户目标仓库。

流程

步骤 1：了解请求

当用户描述一项功能或 Bug 时，通过澄清问题收集上下文。不要立即创建 Issue。

对于功能，请澄清：

• 面向用户的目标是什么？（不是实现细节）
• 验收标准是什么？（如何验证其有效）
• 每项验收标准是否都可在合并前验证？ 是否能在 PR 合并前，通过自主开发/审查 Agent 可以访问的途径获取证据——例如 CI 任务、PR 预览 URL、staging 命令或本地复现？优先采用可在合并前验证的验收标准，并让作者注明验证途径和预期证据。如果某项标准无法在合并前验证（需要部署/生产环境、真实用户、长时间运行测试、外部审批、生产遥测数据，或机器人不具备的凭据），先检查现有的 PR 预览/staging 路径是否已通过相同输入覆盖相同代码路径；如果确实无法在合并前验证，则将其拆分为单独的非阻塞、非 autonomous 后续事项（参见 references/ac-verification.md）。循环无法在合并前满足的阻塞性验收标准，是导致开发↔审查循环无法终止的已知原因。
• 是否涉及 UI/UX？
• 与哪些现有功能相关？
• 优先级和范围限制

对于 Bug，请澄清：

• 复现步骤
• 预期行为与实际行为
• 环境（prod、staging、PR 预览）
• 严重程度（阻塞、性能下降、外观问题）
• 错误消息或日志
• 修复的每项验收标准是否都可在合并前验证？ Bug 修复通常不止一项验收标准——请对每一项进行分类，而不只是标题中的“回归测试在修复前失败，修复后通过”（这是合并前验证的默认方式——请注明验证途径：CI unit/E2E 任务）。注意不要将任何标准表述为合并后/生产环境重放（“通过在已部署的流水线中重放失败批次来验证”）：如果现有的 PR 预览/staging 路径已通过相同输入覆盖相同代码路径，就应让该标准指向此途径。如果某项标准确实只能在部署后确认，则将其拆分为单独的非阻塞、非 autonomous 后续事项（参见 references/ac-verification.md）。这种逐项分类同样适用于 Bug 修复和功能——无论 Issue 类型如何，循环无法在合并前满足的阻塞性验收标准都是导致开发↔审查循环无法终止的已知原因。（注意：Bug 的 ## Environment 字段可以合理地填写为 prod——这是复现环境，而非验收标准。）

每轮提出 2-3 个重点问题。信息足以撰写清晰的 Issue 后即可停止。

上述逐项 合并前可验证 分类同时适用于两种 Issue 类型——功能和 Bug。不要收集包含仅限生产环境的阻塞性验收标准的 Bug 报告，就像不会为功能收集此类报告一样。

步骤 2：起草 Issue

根据 Issue 类型使用相应模板。完整模板内容请参阅 references/issue-templates.md。

两个模板都包含以下必需部分：

• Summary / Motivation（功能）或 Steps to Reproduce（Bug）
• 带复选框的 Requirements（功能）或 Expected/Actual Behavior（Bug）
• Testing Requirements（必需的 TDD 部分：测试用例文档、单元测试、E2E 测试）
• 带复选框的 Acceptance Criteria
• 用于安排 Issue 顺序的 Dependencies 部分

步骤 3：检测并附加工作区变更

起草问题后，检查工作区中的本地变更，看看它们是否能为自主开发 Agent 提供有用的上下文。如需了解完整的检测、附加和清理流程，请参阅 references/workspace-changes.md。

摘要：

1. 运行 git status --short——如果没有变更则跳过
2. 总结变更并征求用户确认
3. 根据差异大小选择策略：内联（< 500 行）、推送分支（>= 500 行）或回退为文件列表
4. 在问题正文中添加 ## Pre-existing Changes 部分
5. 附加后可选择清理本地变更

步骤 4：向用户确认

向用户展示问题草稿，包含：

1. 拟定标题（简洁、明确）
2. 完整的问题正文（如适用，包含 Pre-existing Changes 部分）
3. 拟定标签
4. 是否添加 autonomous 标签

使用 AskUserQuestion 确认：

• “这个问题看起来正确吗？要创建吗？”
• 询问是否添加 autonomous 标签：是否希望 AI 自动处理此问题

合并前可验证性建议性自检（你就是检查器——无需运行时脚本）：仅自检草稿中的 AC 复选框行（## Acceptance Criteria 下的 - [ ] 行，而非其他字段——这样可避免误报 bug 模板的 ## Environment 字段，因为其中的 Stage: 值可能合法地是 prod），查找表明 AC 无法在合并前验证的措辞： post-merge、after merge、in production，以及更广泛的表述——live users、soak、rollout、approver、prod telemetry、manual smoke。如果某项阻塞性 AC 匹配，且没有对应的后续拆分项，提醒作者（仅建议，不阻止），并提出按 references/ac-verification.md §3 进行拆分（创建一个非阻塞、非 autonomous 的后续问题；在 ## Out of Scope 下引用该问题，不要放在 ## Dependencies 下）。匹配不应导致草稿被硬性判定失败。

Agent 无法写入的区域建议性自检（范围同样仅限 AC 复选框行，对相同行进行第二轮检查）：也要查找那些指定了开发 Agent 的受限令牌无法写入的验证区域的措辞——至少包括 in (the )?PR (body|description|title) 和 PR metadata。此类 AC 可能完全可在合并前验证，却仍会导致 dev-actionable=false 停滞，因为受限令牌可以发布 PR/问题评论并提交文件，却无法编辑 PR 元数据（这是设计如此，因双令牌分离而产生，参见 references/ac-verification.md §5）。如果匹配，提醒作者（仅建议，不阻止），并建议改写为指定 Agent 可写入的区域，例如将“……在 PR 正文中”改为“……作为 PR 评论”。匹配不应导致草稿被硬性判定失败。

步骤 5：创建问题

使用 GitHub MCP 工具或 gh CLI 创建问题，包含：

• title：已确认的标题
• body：已确认的正文
• labels：适当的标签（参见下方的标签指南）

向用户报告创建后的问题 URL。

如果推送分支被延后（大差异策略）：

问题创建且已知问题编号后：

1. 使用实际问题编号执行步骤 3 中的分支推送命令
2. 更新问题正文，添加分支引用部分

标签指南

标签	适用情况
bug	Bug 报告
enhancement	功能请求
autonomous	用户确认 AI 应自动处理开发/测试/审查/合并
no-auto-close	与 autonomous 配合使用——AI 处理开发/测试/审查，但在合并前停止，需要人工批准
documentation	仅涉及文档的变更
good first issue	简单、范围明确的任务

自主标签决策

起草问题后，明确询问用户是否要添加 autonomous 标签。

说明适合使用 autonomous 的情况：

• 适合：范围明确、验收标准清晰、遵循现有模式、不涉及含糊的设计决策
• 不适合：需要做出重大的架构决策、开发过程中需要用户提供意见、涉及敏感的基础设施变更、探索或研究类任务

将问题表述为：

“这个问题应该交由自主开发流水线处理吗？AI 将自动开发、测试、审查并合并变更。这最适用于范围明确且验收标准清晰的任务。”

如果用户选择 autonomous，还要询问是否添加 no-auto-close：

“这个问题还应该添加 no-auto-close 标签吗？添加此标签后，AI 会负责开发、测试和审查，但会在合并前停止——并通知你做出最终的合并决定。对于敏感的基础设施变更、需要产品签字确认的功能或实验性工作，建议使用此标签。”

标签交互摘要：

• 仅有 autonomous = AI 负责开发、测试和审查，并且通过后自动合并
• autonomous + no-auto-close = AI 负责开发、测试和审查，但在合并前停止，通知负责人进行手动审批

写作指南

• 标题：以动词开头，具体明确。例如“为 plans 列表页添加分页”，而不是“改进 plans 页面”
• 正文：面向能访问完整代码库、但不了解本次对话背景的 AI 开发者撰写
• 验收标准：必须客观可验证，而非主观判断
• 验收标准验证方式：对每项验收标准，分类为合并前可验证（证据可在合并前获取——注明验证途径：CI 作业、PR 预览 URL、预发布环境命令或本地复现，以及预期证据）或合并前不可验证（需要部署到生产环境、真实用户、长时间运行观察、外部审批、生产遥测数据或机器人不具备的凭据）。优先采用前者，并始终注明验证途径 + 预期证据，而不是只断言结果。确实无法在合并前验证的标准，应放在单独的非阻塞、非 autonomous 后续问题中（在 ## Out of Scope 下引用，绝不要放在 ## Dependencies 下）——将其保留为阻塞性验收标准，是导致开发与审查循环无法终止的已知因素。完整的评估标准、复用现有预览的指南、拆分流程及示例，见 references/ac-verification.md。
• 范围：优先创建较小且聚焦的问题，而非大型多部分问题
• 参考资料：必要时链接相关问题、PRD 章节或代码路径
• 依赖项：## Dependencies 章节只能包含必须先关闭或合并，才能开始处理此问题的问题。不要包含：仅作背景参考的父级史诗、本问题解除阻塞的问题，或任何并非真正阻塞项的 #NNN 引用。自主调度器会按字面解析此章节——任何未关闭或未合并的列表项引用，都会导致此问题被静默跳过，直到该引用对应的问题关闭或合并。解析范围：仅限列表项行（以 -、* 或 1. 开头的行）；## Dependencies 与下一个 ## 标题之间的正文和引用块会被忽略。列表项中可识别 #N（同一仓库）和 owner/repo#N（跨仓库）。如果没有阻塞项，请准确写为 None。按依赖顺序创建问题，以便撰写后续问题时已知较早的问题编号。
• 测试要求：务必包含“测试要求”章节。开发 Agent 会遵循项目的 TDD 工作流，但已发现：如果问题没有明确要求，Agent 可能会跳过 E2E 测试或测试用例文档。请具体说明：
  • 每种测试类型必须覆盖的关键场景（2–4 个项目符号）
  • 对于缺陷，回归测试必须在修复前失败、修复后通过

多问题创建

将大型功能拆分为多个问题时：

1. 按依赖顺序创建问题 —— 先创建没有依赖的问题，再创建依赖于这些问题的问题。这样可以确保编写依赖引用时已知问题编号。
2. 在每个问题正文的 ## Dependencies 部分中，使用 #N（同一仓库）或 owner/repo#N（跨仓库）列表项链接，仅列出直接阻塞的问题。不要引用父级史诗、上下文问题或此问题所解除阻塞的问题——分发器会将该部分中的每个列表项引用都视为硬性阻塞项。正文或引用块中的引用会被忽略。
3. 使用一致的命名方案 —— 在标题前加上项目/功能名称，便于筛选（例如，“MyProject：添加 DynamoDB 基础设施”）。
4. 交叉引用计划 —— 如果存在实施计划，请将每个问题链接到相关的计划任务/分块。
5. 分发器会跳过受阻问题 —— 对于 ## Dependencies 部分中仍有未解决依赖项的问题，自主分发器会忽略它们，直到所有依赖项都已解决（关闭/合并）。

---

参考资料

详细内容请参阅：

• references/issue-templates.md —— 包含所有必需部分的完整功能和缺陷问题模板
• references/ac-verification.md —— 合并前与非合并前 AC 分类准则、复用现有预览的指导、拆分为非阻塞后续事项的流程、no-auto-close 说明，以及两个演示示例（防止循环）
• references/workspace-changes.md —— 完整的工作区变更检测、附件策略和清理流程