create-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create GitHub Issue

创建GitHub Issue

Create well-structured GitHub issues from user descriptions through interactive clarification.

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

Repository Detection

仓库检测

Detect the repository from the current git remote:

bash

REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')

从当前git远程仓库中检测目标仓库：

bash

REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')

Splits into OWNER and REPO_NAME


If detection fails, ask the user for the target repository.


如果检测失败，请向用户询问目标仓库信息。

Process

流程

Step 1: Understand the Request

步骤1：理解需求

When the user describes a feature or bug, gather context through clarifying questions. Do NOT create the issue immediately.

For features, clarify:

What is the user-facing goal? (not implementation details)
What are the acceptance criteria? (how to verify it works)
Are there UI/UX implications?
What existing functionality does this relate to?
Priority and scope constraints

For bugs, clarify:

Steps to reproduce
Expected vs actual behavior
Environment (prod, staging, PR preview)
Severity (blocking, degraded, cosmetic)
Any error messages or logs

Ask 2-3 focused questions per round. Stop when there is enough information to write a clear issue.

当用户描述功能或Bug时，通过澄清问题收集上下文信息。请勿立即创建issue。

对于功能请求，需澄清：

面向用户的目标是什么？（而非实现细节）
验收标准是什么？（如何验证功能正常工作）
是否存在UI/UX影响？
与现有哪些功能相关？
优先级和范围约束

对于Bug报告，需澄清：

复现步骤
预期行为与实际行为对比
环境（生产、 staging、PR预览）
严重程度（阻塞性、性能下降、界面瑕疵）
任何错误信息或日志

每轮询问2-3个针对性问题。当拥有足够信息可撰写清晰的issue时停止询问。

Step 2: Draft the Issue

步骤2：草拟Issue

Use the appropriate template based on issue type. For full template content, consult references/issue-templates.md
.

Both templates include these required sections:

Summary / Motivation (feature) or Steps to Reproduce (bug)
Requirements with checkboxes (feature) or Expected/Actual Behavior (bug)
Testing Requirements (mandatory TDD section: test cases doc, unit tests, E2E tests)
Acceptance Criteria with checkboxes
Dependencies section for issue ordering

根据issue类型选择合适的模板。如需完整模板内容，请参考 references/issue-templates.md
。

两种模板均包含以下必填部分：

摘要 / 动机（功能请求）或 复现步骤（Bug）
带复选框的需求（功能请求）或 预期/实际行为（Bug）
测试要求（强制TDD部分：测试用例文档、单元测试、E2E测试）
带复选框的验收标准
用于issue排序的依赖项部分

Step 2.5: Detect & Attach Workspace Changes

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

After drafting the issue, check the workspace for local changes that may provide useful context for the autonomous dev agent. For the complete detection, attachment, and cleanup procedure, consult references/workspace-changes.md
.

Summary:

Run
```
git status --short
```
— skip if no changes
Summarize changes and ask user for confirmation
Choose strategy based on diff size: inline (< 500 lines), branch push (>= 500 lines), or file list fallback
Add a
```
## Pre-existing Changes
```
section to the issue body
Optionally clean up local changes after attachment

草拟issue后，检查工作区中的本地变更，这些变更可能为自主开发Agent提供有用的上下文信息。如需完整的检测、附加和清理流程，请参考 references/workspace-changes.md
。

流程概述：

运行
```
git status --short
```
— 若无变更则跳过
总结变更内容并请求用户确认
根据diff大小选择策略：内联（<500行）、推送分支（≥500行）或文件列表回退
在issue正文中添加
```
## 预存在的变更
```
部分
附加完成后可选择清理本地变更

Step 3: Confirm with User

步骤3：与用户确认

Present the draft issue to the user with:

Proposed title (concise, descriptive)
Full issue body (including Pre-existing Changes section if applicable)
Proposed labels
Whether to add
```
autonomous
```
label

Use AskUserQuestion to confirm:

"Does this issue look correct? Should I create it?"
Ask about autonomous label: whether AI should handle this automatically

向用户展示草拟的issue，包含：

建议标题（简洁、描述性）
完整issue正文（如适用则包含预存在的变更部分）
建议标签
是否添加
```
autonomous
```
标签

使用AskUserQuestion进行确认：

“此issue内容是否正确？是否需要创建？”
询问autonomous标签：是否由AI自动处理该issue

Step 4: Create the Issue

步骤4：创建Issue

Use GitHub MCP tools or

gh

CLI to create the issue with:

```
title
```
: The confirmed title
```
body
```
: The confirmed body
```
labels
```
: Appropriate labels (see Label Guide below)

Report the created issue URL to the user.

If branch push was deferred (large diff strategy):

After the issue is created and the issue number is known:

Execute the branch push commands from Step 2.5.5 using the actual issue number
Update the issue body to include the branch reference section

使用GitHub MCP工具或

gh

CLI创建issue，包含：

```
title
```
: 已确认的标题
```
body
```
: 已确认的正文
```
labels
```
: 合适的标签（见下方标签指南）

将创建好的issue URL反馈给用户。

若延迟推送分支（大diff策略）：

创建issue并获取issue编号后：

使用实际issue编号执行步骤2.5.5中的分支推送命令
更新issue正文以包含分支引用部分

Label Guide

标签指南

Label	When to Apply
`bug`	Bug reports
`enhancement`	Feature requests
`autonomous`	User confirms AI should handle dev/test/review/merge automatically
`no-auto-close`	Used with `autonomous` -- AI handles dev/test/review but stops before merge, requiring manual approval
`documentation`	Documentation-only changes
`good first issue`	Simple, well-scoped tasks

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

Autonomous Label Decision

Autonomous标签决策

After drafting the issue, explicitly ask the user whether to add the

autonomous

label.

Provide guidance on when

autonomous

is appropriate:

Good fit: Well-defined scope, clear acceptance criteria, follows existing patterns, no ambiguous design decisions
Poor fit: Requires significant architecture decisions, needs user input during development, involves sensitive infrastructure changes, exploratory/research tasks

Frame the question as:

"Should this issue be handled by the autonomous development pipeline? The AI will automatically develop, test, review, and merge the changes. This works best for well-defined tasks with clear acceptance criteria."

If the user selects
autonomous
, also ask about
no-auto-close
:

"Should this issue also have the
no-auto-close
label? With this label, the AI will handle development, testing, and review, but will stop before merging -- you'll be notified to make the final merge decision. This is recommended for sensitive infrastructure changes, features needing product sign-off, or experimental work."

Label interaction summary:

```
autonomous
```
alone = AI handles dev/test/review and auto-merges on pass
```
autonomous
```
+
```
no-auto-close
```
= AI handles dev/test/review but stops before merge, notifying the owner for manual approval

草拟issue后，明确询问用户是否添加

autonomous

标签。

提供

autonomous

标签适用场景的指导：

适用场景：范围明确、验收标准清晰、遵循现有模式、无模糊设计决策
不适用场景：需要重大架构决策、开发过程中需用户输入、涉及敏感基础设施变更、探索性/研究性任务

询问话术示例：

“是否由自主开发流水线处理此issue？AI将自动完成开发、测试、评审和合并。此方式最适用于范围明确、验收标准清晰的任务。”

若用户选择
autonomous
，需额外询问
no-auto-close
标签：

“是否同时添加
no-auto-close
标签？添加后，AI将处理开发、测试和评审，但在合并前停止，并通知负责人进行手动批准。此标签推荐用于敏感基础设施变更、需要产品确认的功能或实验性工作。”

标签交互总结：

仅
```
autonomous
```
标签 = AI处理开发/测试/评审并在通过后自动合并
```
autonomous
```
+
```
no-auto-close
```
标签 = AI处理开发/测试/评审，但在合并前停止，通知负责人手动批准

Writing Guidelines

编写指南

Title: Start with verb, be specific. "Add pagination to plans list page" not "Plans page improvement"
Body: Write for an AI developer who has access to the full codebase but no verbal context from this conversation
Acceptance criteria: Must be objectively verifiable, not subjective
Scope: Prefer smaller, focused issues over large multi-part ones
References: Link to related issues, PRD sections, or code paths when relevant
Dependencies: When creating multiple related issues, populate the
```
## Dependencies
```
section with links to blocking issues. Create issues in dependency order so earlier issue numbers are available for later ones. The dispatcher will skip issues whose dependencies are still open.
Testing Requirements: ALWAYS include the "Testing Requirements" section. The dev agent follows the project's TDD workflow but has been observed to skip E2E tests or test-case docs when the issue doesn't explicitly call them out. Be specific about:
- Key scenarios each test type must cover (2-4 bullet points)
- For bugs: the regression test must fail before the fix and pass after

标题：以动词开头，具体明确。例如“为计划列表页添加分页功能”而非“计划页改进”
正文：为可访问完整代码库但无本次对话上下文的AI开发者编写
验收标准：必须可客观验证，而非主观描述
范围：优先创建小而聚焦的issue，而非大型多部分issue
参考：关联相关issue、PRD章节或代码路径（如有）
依赖项：创建多个相关issue时，在
```
## 依赖项
```
部分添加阻塞issue的
```
#N
```
链接。按依赖顺序创建issue，以便后续issue可引用更早的issue编号。调度器会跳过依赖项仍未关闭的issue。
测试要求：务必包含“测试要求”部分。开发Agent遵循项目的TDD工作流，但当issue未明确要求时，可能会跳过E2E测试或测试用例文档。需明确：
- 每种测试类型必须覆盖的关键场景（2-4个要点）
- 对于Bug：回归测试在修复前需失败，修复后需通过

Multi-Issue Creation

多Issue创建

When breaking a large feature into multiple issues:

Create issues in dependency order — issues with no dependencies first, then issues that depend on them. This ensures issue numbers are known when writing dependency references.
Populate the
## Dependencies
section in each issue body with
```
#N
```
links to blocking issues.
Use a consistent naming scheme — prefix titles with the project/feature name for easy filtering (e.g., "MyProject: Add DynamoDB infrastructure").
Cross-reference the plan — if an implementation plan exists, link each issue to the relevant plan tasks/chunks.
The dispatcher skips blocked issues — issues with open dependencies in the
```
## Dependencies
```
section are ignored by the autonomous dispatcher until all dependencies are resolved (closed/merged).

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

按依赖顺序创建issue — 先创建无依赖的issue，再创建依赖于它们的issue。确保编写依赖项引用时可获取到issue编号。
填充
## 依赖项
部分 — 在每个issue正文中添加阻塞issue的
```
#N
```
链接。
使用一致的命名规则 — 标题前缀添加项目/功能名称以便筛选（例如：“MyProject: 添加DynamoDB基础设施”）。
交叉引用计划 — 若存在实现计划，将每个issue链接到计划中的相关任务/模块。
调度器跳过阻塞issue —
```
## 依赖项
```
部分中存在未关闭依赖项的issue，将被自主调度器忽略，直到所有依赖项解决（关闭/合并）。

References

参考文档

For detailed content, consult:

references/issue-templates.md
-- Full feature and bug issue templates with all required sections
references/workspace-changes.md
-- Complete workspace change detection, attachment strategies, and cleanup procedure

如需详细内容，请参考：

references/issue-templates.md
-- 包含所有必填部分的完整功能和Bug issue模板
references/workspace-changes.md
-- 完整的工作区变更检测、附加策略和清理流程