Issue Creator

Issue Creator

创建高质量 GitHub Issue：人类能 1 分钟做决策，AI agent 能从中获取精准的问题上下文直接开工。

核心理念

Issue 是问题描述空间，不是解决方案空间

Issue 应该提供：

• 精准的问题/需求上下文 — 是什么、在哪里、什么时候触发、影响范围
• 清晰的验收标准 — 怎样算完成
• 必要的决策点 — 需要人类判断的选择

Issue 不应该包含：

• ❌ 具体实现方案或代码修改建议
• ❌ 技术路线选择或架构决策
• ❌ "建议使用 xxx 来实现" 之类的措辞

原因：Issue 的创建者不一定是最终执行者。如果创建时写入了质量不确定的实现方案，会误导后续执行的人或 AI agent。把实现判断留给执行者，基于代码现状自行决定。

"AI 友好"= 精准的定位上下文，而非实现指导

AI agent 需要的是：

• 精确的文件路径和行号
• 当前代码的实际行为描述（不是猜测）
• 可机械复现的触发步骤
• 充分的上下文信息（来自用户工作环境和对话中的真实数据）

双层信息架构

┌─────────────────────────────────────┐
│  🧑 人类层（快速决策）               │  ← TL;DR + 决策点 + 验收标准
│  一眼看懂：是什么、为什么、要不要做   │
├─────────────────────────────────────┤
│  🔍 定位层（精确上下文）             │  ← 文件路径 + 行号 + 当前行为 + 触发方式
│  精准描述：在哪里、现在什么样、怎么触发│
└─────────────────────────────────────┘

触发场景

• /issue-creator 或 /create-issue
• 用户说"创建 issue"、"建个需求"、"写个 enhancement issue"、"帮我拆成子 issue"
• 用户描述了一个功能需求、优化方向、重构计划或任何需要追踪的工作项

执行流程

Step 1: 理解需求并收集上下文

# 仓库基本信息
OWNER=$(gh repo view --json owner --jq '.owner.login')
REPO=$(gh repo view --json name --jq '.name')

# 近期改动和状态
git log --oneline -10
git status --short

# 已有 issue 和 label（避免重复）
gh issue list --state open --json number,title,labels --limit 20
gh label list --json name --jq '.[].name'

同时回顾当前对话上下文——用户提到的现象、截图、报错、设计决策、优先级、已确认的结论等。不要重复提问已回答过的问题。

从仓库信息和对话上下文中提炼：

• 是什么 — 问题现象或需求本质
• 为什么 — 动机、对用户/团队的价值
• 在哪里 — 影响哪些模块/页面/功能
• 什么时候 — 触发条件或复现步骤

Step 1.5: 查重

两段式：先用 Step 1 拿到的 open issue 列表做近况了解，再针对核心关键词做检索（覆盖 open + closed，能抓到曾以 wontfix 关闭又被重提的需求）：

# 关键词检索，默认覆盖 open 和 closed
gh search issues --repo "$OWNER/$REPO" "<核心关键词>" --limit 10 --json number,title,state,url

# 获取疑似重复 issue 的正文
gh issue view <number> --repo "$OWNER/$REPO" --json title,body,labels,assignees

对比当前需求与已有 issue 的核心意图（不是字面措辞），判断：

Step 2: 探索相关代码，获取精准定位

定位信息的详细程度应与 Issue 复杂度匹配，避免过量信息变成噪音：

探索代码时记录：

• 涉及的模块/功能域（必须）
• 当前代码的实际行为（必须，基于代码阅读而非推测）
• 具体文件路径和行号（仅在复杂 issue 中提供）

Step 3: 判断是否需要拆分

拆分原则：

• 每个 sub-issue 应该是一个独立可完成的工作单元
• 标注 sub-issues 之间的依赖关系（可并行 vs 必须串行）

Step 4: 向用户提问对齐

创建 Issue 前必须通过提问与用户对齐。 不要默默生成然后直接提交。

使用 AskUserQuestion（或当前环境中等效的交互式提问工具）向用户提出选择题，让用户通过选择选项来确认或纠偏。每个问题提供具体选项和简要说明，降低用户的回答成本。每个问题的选项中必须标注一个"推荐"和一个"次推荐"，让用户在没有强烈偏好时能快速采纳你的建议。

需要对齐的维度（根据实际情况组合提问，不必每次都问全）：

• 需求理解 — 你对核心问题/需求的理解是否正确？如有多种解读，每种解读作为一个选项
• 范围边界 — 这个需求包含哪些、不包含哪些？模糊的边界作为选项让用户勾选
• 拆分方案 — 单个 issue 还是拆分？如果拆分，给出拆法选项
• 标签建议 — 准备打什么标签，让用户确认或调整
• 其他模糊点 — 任何你不确定的地方，都转化为选择题而非开放问题

原则：宁可多问一轮，不要创建出需要关闭重建的 issue。

豁免：用户明确说"直接建，不用确认"，或当前处于无人值守/自主执行模式（如 /goal 模式、定时任务、CI 等无法交互的场景）时，跳过提问，直接采用各维度的推荐选项创建，并在 Step 7 的输出摘要中列出所采用的假设。

Step 5: 生成 Issue 内容

使用下方模板。关键：

• TL;DR 必须让人类 10 秒内理解核心
• 定位信息必须来自实际代码探索，不能猜测
• 验收标准必须可机械检查

Step 6: 创建 Issue 并关联

gh issue create \
  --repo "$OWNER/$REPO" \
  --title "Issue 标题" \
  --label "enhancement" \
  --body "$(cat <<'ISSUE_EOF'
[Issue body]
ISSUE_EOF
)"

Sub-issues 关联：

SUB_URL=$(gh issue create --repo "$OWNER/$REPO" --title "..." --label "..." --body "...")
SUB_NUMBER=$(echo "$SUB_URL" | grep -oE '[0-9]+$')
PARENT_ID=$(gh issue view <parent_number> --repo "$OWNER/$REPO" --json id --jq ".id")
CHILD_ID=$(gh issue view "$SUB_NUMBER" --repo "$OWNER/$REPO" --json id --jq ".id")

# 用 GraphQL 变量传参，避免字符串拼接转义问题
gh api graphql -f parentId="$PARENT_ID" -f childId="$CHILD_ID" -f query='
  mutation($parentId: ID!, $childId: ID!) {
    addSubIssue(input: {issueId: $parentId, subIssueId: $childId}) {
      issue { title number }
      subIssue { title number }
    }
  }'

GitLab 环境（glab）的等效命令见 references/glab.md——GitLab 没有 GitHub 式 sub-issue，需用 issue links 表达父子/依赖关系。

Step 7: 输出摘要

创建完成后，向用户报告：

• 创建了哪些 issue（编号 + 链接）
• sub-issue 关联状态
• 建议的工作顺序（如有依赖关系）

Issue 模板

单一 Issue

## TL;DR

[1-2 句话。人类读完这段就能决定要不要做。]

## 决策点

> 需要人类判断的选择。没有则删除本节。

- [ ] [选择 A vs 选择 B：简述权衡]

## 问题/需求描述

[3-5 句话描述问题现象或需求背景。聚焦"是什么"和"为什么"。]

## 当前行为

[精确描述当前代码的实际行为。基于代码阅读而非猜测。]

## 期望行为

[精确描述完成后应该是什么样。]

---

<!-- 以下为定位信息，详细程度按 Issue 复杂度调整 -->

## 影响范围

<!-- 简单 issue：只写模块/功能域 -->
涉及模块：[模块名 / 功能域描述]

<!-- 复杂 issue：展开为精确表格 -->
| 文件 | 行号 | 当前状态 |
|------|------|---------|
| `src/features/xxx/pages/XxxPage.tsx` | 42-58 | [当前代码在这些行做了什么] |
| `src/lib/xxx.ts` | 15 | [当前状态描述] |

## 触发/复现方式

1. [具体步骤 1]
2. [具体步骤 2]
3. [观察到的现象]

## 验收标准

- [ ] [可检查的标准 1]
- [ ] [可检查的标准 2]
- [ ] [仓库约定的构建/测试命令]通过（从 CLAUDE.md、package.json、Makefile、CI 配置探测，如 `pnpm run build`、`cargo test`）

## 关联

- 相关 Issue: #N
- 依赖: #M（需先完成）

Parent Issue（带 Sub-issues）

## TL;DR

[1-2 句话概括整体目标]

## 概述

[3-5 句话描述问题/需求的完整背景]

## Sub-issues 总览

| # | 标题 | 依赖 |
|---|------|------|
| 1 | [子任务 1] | 无 |
| 2 | [子任务 2] | 无 |
| 3 | [子任务 3] | #1 完成后 |

## 依赖关系

Sub-Issue 1 ──┐ Sub-Issue 2 ──┼──→ 可并行 │ ▼ Sub-Issue 3 ──→ 依赖 Sub-Issue 1

## 验收标准（整体）

- [ ] 所有 sub-issues 完成
- [ ] [整体集成验证标准]

标签选择

标签是 Issue 的分类入口，直接影响优先级排序、看板过滤和任务分配。必须根据 Issue 内容主动选择标签，并在 Step 4 对齐时向用户确认。

选择标签时考虑两个维度：

1. 类型标签（必选，描述这个 Issue 是什么性质）：

2. 难度/协作标签（符合条件时必须打）：

3. 辅助标签（可选，描述额外属性）：

根据仓库中已有的标签体系，酌情追加优先级（priority:high）、模块（area:auth）等辅助标签。不要凭空发明标签体系，优先复用仓库现有标签。

如果仓库中没有需要的标签，先用 gh label create 创建。

标题格式

[模块] 动词短语描述

示例：

• [Hub] 独立化色彩体系，消除 primary 色污染
• [Dashboard] 马赛克墙触摸设备长按无响应
• [Auth] 邀请码注册后未自动跳转到仪表板

质量自检

• TL;DR ≤ 2 句，人类读完能做决策
• 没有包含实现方案或代码修改建议
• 定位信息的详细程度与 Issue 复杂度匹配（简单 issue 不写死路径行号）
• 当前行为描述基于代码阅读，不是猜测
• 每条验收标准可被检查（CI / review / 自测）
• Sub-issues 之间的依赖关系已标注（如有）
• 没有包含敏感信息（token/key/password）

示例

示例 1: 简单功能需求

用户说： "Hub 页面的点赞加个动画效果"

执行：

1. 搜索点赞相关代码，记录模块和当前行为（点击后立即切换状态，无过渡）
2. 向用户确认动画类型偏好（缩放、弹跳、粒子等）
3. 创建单个 issue，标注 good first vibe

示例 2: 需要拆分的大需求

用户说： "把认证系统从 mock 切换到 Supabase，帮我拆一下"

执行：

1. 分析 mock 和 Supabase 接口差异，列出涉及的模块
2. 向用户确认拆分方案和优先级
3. 创建 parent + sub-issues 并关联
4. 报告依赖关系和建议工作顺序