# Issue Creator

> 创建结构化的 GitHub Issue，采用"人类优先、AI 友好"的双层信息架构，支持 sub-issue 拆解与自动关联。当用户说"创建 issue"、"建个需求"、"拆 issue"、"创建子 issue"、"写个 feature issue"时触发。

- Skill: `centitenka/issue-creator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add centitenka/issue-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/centitenka/issue-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: centitenka (https://skillmd.com/u/centitenka)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/centitenka/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: 理解需求并收集上下文

```bash
# 仓库基本信息
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 关闭又被重提的需求）：

```bash
# 关键词检索，默认覆盖 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 的**核心意图**（不是字面措辞），判断：

| 判定 | 行动 |
|------|------|
| 完全重复 | 停止创建，向用户报告已有 issue 编号和链接 |
| 部分重叠（范围更大或角度不同） | 向用户说明重叠点，询问：补充到已有 issue / 创建新 issue 并关联 / 取消 |
| 无重复 | 继续 Step 2 |

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

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

| Issue 类型 | 定位粒度 | 示例 |
|-----------|---------|------|
| 简单功能 / `good first vibe` | 涉及的**模块或功能域** | "点赞相关逻辑"、"用户认证模块" |
| 中等复杂度 | 相关**文件路径** + 当前行为概述 | "`src/features/hub/` 下的点赞组件，目前无动画" |
| 复杂 bug / 难复现问题 | 精确**文件路径 + 行号** + 当前行为 | "`src/lib/auth.ts:42-58` 中 token 刷新逻辑在并发时竞态" |

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

### Step 3: 判断是否需要拆分

| 信号 | 行动 |
|------|------|
| 范围可被一个 AI agent session 完成 | 单个 issue |
| 涉及多个独立模块或有先后依赖 | 拆分 sub-issues |
| 用户明确说"拆一下" | 创建 parent + sub-issues |

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

### Step 4: 向用户提问对齐

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

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

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

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

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

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

### Step 5: 生成 Issue 内容

使用下方模板。**关键**：
- TL;DR 必须让人类 10 秒内理解核心
- 定位信息必须来自实际代码探索，不能猜测
- 验收标准必须可机械检查

### Step 6: 创建 Issue 并关联

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

Sub-issues 关联：

```bash
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](references/glab.md)——GitLab 没有 GitHub 式 sub-issue，需用 issue links 表达父子/依赖关系。

### Step 7: 输出摘要

创建完成后，向用户报告：
- 创建了哪些 issue（编号 + 链接）
- sub-issue 关联状态
- 建议的工作顺序（如有依赖关系）

---

## Issue 模板

### 单一 Issue

```markdown
## 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）

```markdown
## 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 是什么性质）：

| 类型 | 标签 | 判断依据 |
|------|------|---------|
| 新功能 | `enhancement` | 当前不存在的能力，需要新增 |
| Bug 修复 | `bug` | 现有功能的行为不符合预期 |
| UI/视觉 | `enhancement` + `design`（如有） | 涉及样式、布局、交互体验 |
| 文档 | `documentation` | 仅涉及文档变更，不改代码逻辑 |

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

| 标签 | 判断依据 |
|------|---------|
| `good first issue` | 改动范围小、上下文自包含、不需要深入理解项目架构，适合新贡献者上手 |
| `good first vibe` | Issue 正文本身已提供充足上下文，AI agent 仅凭 Issue 内容（无需额外对话）就能独立完成 |

**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. 报告依赖关系和建议工作顺序