spec-to-issue

spec-to-issue — 将规格转换为 GitHub Issue

从规格目录（.specs/{feature}/）自动生成 GitHub Issue。

语言规则

1. 自动检测输入语言 → 使用相同语言输出
2. 日语输入 → 使用日语撰写 Issue，并将 references/issue-template.ja.md 用作模板参考
3. 英语输入 → 使用英语撰写 Issue，并将 references/issue-template.md 用作模板参考
4. 显式指定的覆盖选项优先

参考文件选择：根据检测到的输出语言，使用相应模板：

• 英语 → references/issue-template.md
• 日语 → references/issue-template.ja.md

执行流程

1. 定位规格目录

带参数：spec-to-issue auth-feature → 使用 .specs/auth-feature/

不带参数：扫描 .specs/ 并显示列表 → 请用户选择

Spec directories found in .specs/:
1. auth-feature (requirement.md, design.md, tasks.md)
2. member-management (requirement.md, tasks.md)
Which spec do you want to create an issue from?

2. 文件验证

必需：必须存在 requirement.md。否则，报错并退出。 建议：提供 design.md 和 tasks.md。 如果缺少其中任一文件，只有在其余文档仍能定义具体范围和验收标准时才继续；创建 Issue 前报告缺少的来源。

3. 规格分析

将规格文件视为候选来源，而非可直接复制的章节。 提取并筛选：

requirement.md：

• 标题：首个以 # 开头的行，去掉“Requirements”“要件定義書”等后缀
• 问题及可观察到的完成状态
• 当前行为和预期行为
• 包含的范围和排除的范围
• 需求层面的验收标准

design.md：

• 受兼容性、安全性、外部契约或其他需求约束的决策，包括原因
• 实施者无法独自安全决定的待解决问题

tasks.md：

• 辅助实施细节和额外的完成证据
• 默认不复制阶段标题、任务标题、估算值或技术列表

只有在删除候选内容会改变实施决策或完成情况判断时，才保留该内容。完整筛选流程请参阅对应语言的 Issue 模板参考文件。

4. 确定项目设置

按以下优先级顺序确定默认值：

Command arguments > .specs/.config.yml > CLAUDE.md > Built-in defaults

来自 CLAUDE.md：

• 分支名称：Git Workflow 部分中的 PR 目标分支 → --branch 默认值
• GitHub 组织：根据仓库 URL 推断

.specs/.config.yml（可选）：

default-branch: develop
default-labels: [feature, spec-generated]
project-number: 7
assignee: username

5. 确定项目模板并编写 Issue 正文

编写正文前，检查仓库的 Issue 表单、Issue 模板、贡献规则和必填字段。项目模板优先：保留其标题、顺序、字段和复选框，并将筛选出的信息填入其中。

模板详情请参阅相应的参考文件（根据语言规则选择）：

• 英语：references/issue-template.md
• 日语：references/issue-template.ja.md

如果没有项目模板，则编写执行契约，明确问题、完成状态、当前行为和预期行为、包含的范围和排除的范围、验收标准、约束性决策以及待解决问题。链接到规格文件，以便查看任务分解和辅助细节。

6. 创建 Issue

不带 --preview（默认）：显示简要摘要并执行 gh issue create

Creating Issue:
  Title: [Feature] Member Management
  Labels: feature, spec-generated
  Outcome: Members can be invited and assigned a repository role
  Acceptance criteria: 4
→ Running gh issue create...
Issue #42 created: https://github.com/org/repo/issues/42

带 --preview：显示完整 Issue 正文，确认后再执行

7. 其他操作（可选）

• --label：应用指定标签
• --project：通过 gh project item-add 添加到 GitHub Project 看板
• --assignee：设置指派人

选项

选项	描述	默认值
--preview	显示 Issue 正文以供确认	关闭
--label <labels>	以逗号分隔的标签	.config.yml 中的值或无
--project <number>	添加到 GitHub Project	.config.yml 中的值或无
--branch <name>	规格链接的基础分支	CLAUDE.md 中的值或 main
--assignee <user>	设置指派人	.config.yml 中的值或无

与 spec-generator 集成

spec-generator 的 full 阶段完成后，建议：

All three spec documents have been generated.
→ Create a GitHub Issue from them? (Y/n)

如果是，则在同一目录运行 spec-to-issue。

错误处理

情况	响应
.specs/ 不存在	错误：未找到规格目录
缺少 requirement.md	错误：必须提供 requirement.md
缺少 design.md 或 tasks.md	仅当仍有明确的范围和验收标准时继续；否则停止并报告缺失的来源
gh CLI 未通过身份验证	错误：引导用户运行 gh auth login
缺少明确的验收标准	在创建 issue 前停止；不要编造通用的完成检查项
找到项目模板	保留其必需的标题和字段，而不是附加内置模板

使用示例

# With argument
/spec-to-issue auth-feature

# Auto-detect and select
/spec-to-issue

# With preview
/spec-to-issue auth-feature --preview

# With labels and Project
/spec-to-issue auth-feature --label "feature,priority:high" --project 7

# After spec-generator
"Create full spec for todo-app" → done → "Turn this into an issue"

# Japanese
「仕様書を全部作って」→ 完了 →「これをIssueにして」