Claude-Code-Workflow/docs/zh/commands/claude/issue.md

Issue 工作流命令

一句话定位

Issue 工作流命令是问题管理的闭环系统 — 从发现、规划到执行，完整追踪问题解决全流程。

核心概念速览

概念	说明	存放位置
Issue	结构化问题定义	.workflow/issues/ISS-*.json
解决方案	执行计划	.workflow/solutions/SOL-*.json
队列	执行队列	.workflow/queues/QUE-*.json
执行状态	进度跟踪	队列内状态

命令列表

命令	功能	语法
new	从 GitHub URL 或文本描述创建结构化 Issue	/issue:new [-y] <github-url | 描述> [--priority 1-5]
discover	从多个角度发现潜在 Issue	/issue:discover [-y] <路径模式> [--perspectives=维度] [--external]
discover-by-prompt	通过用户提示发现 Issue	/issue:discover-by-prompt [-y] <提示> [--scope=src/**]
plan	批量规划 Issue 解决方案	/issue:plan [-y] --all-pending <issue-id>[,...] [--batch-size 3]
queue	形成执行队列	/issue:queue [-y] [--queues N] [--issue id]
execute	执行队列	/issue:execute [-y] --queue <queue-id> [--worktree [路径]]
convert-to-plan	转换规划工件为 Issue 解决方案	/issue:convert-to-plan [-y] [--issue id] [--supplement] <来源>

命令详解

new

功能: 从 GitHub URL 或文本描述创建结构化 Issue，支持需求清晰度检测。

语法:

/issue:new [-y|--yes] <github-url | 文本描述> [--priority 1-5]

选项:

• --priority 1-5: 优先级（1=关键，5=低）

清晰度检测:

输入类型	清晰度	行为
GitHub URL	3	直接创建
结构化文本	2	直接创建
长文本	1	部分澄清
短文本	0	完全澄清

Issue 结构:

interface Issue {
  id: string;                    // GH-123 或 ISS-YYYYMMDD-HHMMSS
  title: string;
  status: 'registered' | 'planned' | 'queued' | 'in_progress' | 'completed' | 'failed';
  priority: number;              // 1-5
  context: string;               // 问题描述（单一真相源）
  source: 'github' | 'text' | 'discovery';
  source_url?: string;

  // 绑定
  bound_solution_id: string | null;

  // 反馈历史
  feedback?: Array<{
    type: 'failure' | 'clarification' | 'rejection';
    stage: string;
    content: string;
    created_at: string;
  }>;
}

示例:

# 从 GitHub 创建
/issue:new https://github.com/owner/repo/issues/123

# 从文本创建（结构化）
/issue:new "登录失败：预期成功，实际 500 错误"

# 从文本创建（模糊 - 会询问）
/issue:new "认证有问题"

# 指定优先级
/issue:new --priority 2 "支付超时问题"

discover

功能: 从多个角度（Bug、UX、测试、质量、安全、性能、可维护性、最佳实践）发现潜在 Issue。

语法:

/issue:discover [-y|--yes] <路径模式> [--perspectives=bug,ux,...] [--external]

选项:

• --perspectives=维度: 分析维度
  • bug: 潜在 Bug
  • ux: UX 问题
  • test: 测试覆盖
  • quality: 代码质量
  • security: 安全问题
  • performance: 性能问题
  • maintainability: 可维护性
  • best-practices: 最佳实践
• --external: 使用 Exa 外部研究（安全、最佳实践）

示例:

# 全面扫描
/issue:discover src/

# 特定维度
/issue:discover src/auth/ --perspectives=security,bug

# 带外部研究
/issue:discover src/payment/ --perspectives=security --external

discover-by-prompt

功能: 通过用户提示发现 Issue，使用 Gemini 规划的迭代多代理探索，支持跨模块比较。

语法:

/issue:discover-by-prompt [-y|--yes] <提示> [--scope=src/**] [--depth=standard|deep] [--max-iterations=5]

选项:

• --scope=路径: 扫描范围
• --depth=深度: standard 或 deep
• --max-iterations=N: 最大迭代次数

示例:

# 标准扫描
/issue:discover-by-prompt "查找认证模块的问题"

# 深度扫描
/issue:discover-by-prompt "分析 API 性能瓶颈" --depth=deep

# 指定范围
/issue:discover-by-prompt "检查数据库查询优化" --scope=src/db/

plan

功能: 批量规划 Issue 解决方案，使用 issue-plan-agent（探索+规划闭环）。

语法:

/issue:plan [-y|--yes] --all-pending <issue-id>[,<issue-id>,...] [--batch-size 3]

选项:

• --all-pending: 规划所有待规划的 Issue
• --batch-size=N: 每批处理的 Issue 数量

示例:

# 规划特定 Issue
/issue:plan ISS-20240115-001,ISS-20240115-002

# 规划所有待规划的 Issue
/issue:plan --all-pending

# 指定批次大小
/issue:plan --all-pending --batch-size 5

queue

功能: 从绑定解决方案形成执行队列，使用 issue-queue-agent（解决方案级别）。

语法:

/issue:queue [-y|--yes] [--queues <n>] [--issue <id>]

选项:

• --queues N: 创建的队列数量
• --issue id: 特定 Issue

示例:

# 形成队列
/issue:queue

# 创建多个队列
/issue:queue --queues 3

# 特定 Issue
/issue:queue --issue ISS-20240115-001

execute

功能: 执行队列，使用 DAG 并行编排（每个解决方案一次提交）。

语法:

/issue:execute [-y|--yes] --queue <queue-id> [--worktree [<existing-path>]]

选项:

• --queue id: 队列 ID
• --worktree [路径]: 可选的工作树路径

示例:

# 执行队列
/issue:execute --queue QUE-20240115-001

# 使用工作树
/issue:execute --queue QUE-20240115-001 --worktree ../feature-branch

convert-to-plan

功能: 转换规划工件（lite-plan、工作流会话、markdown）为 Issue 解决方案。

语法:

/issue:convert-to-plan [-y|--yes] [--issue <id>] [--supplement] <来源>

选项:

• --issue id: 绑定到现有 Issue
• --supplement: 补充模式（添加到现有解决方案）

来源类型:

• lite-plan 工件
• 工作流会话
• Markdown 文件

示例:

# 从 lite-plan 转换
/issue:convert-to-plan .workflow/sessions/WFS-xxx/artifacts/lite-plan.md

# 绑定到 Issue
/issue:convert-to-plan --issue ISS-20240115-001 plan.md

# 补充模式
/issue:convert-to-plan --supplement additional-plan.md

from-brainstorm

功能: 从头脑风暴会话想法转换为 Issue 并生成可执行解决方案。

语法:

/issue:from-brainstorm SESSION="会话-id" [--idea=<索引>] [--auto] [-y|--yes]

选项:

• --idea=索引: 特定想法索引
• --auto: 自动模式

示例:

# 转换所有想法
/issue:from-brainstorm SESSION="WFS-brainstorm-2024-01-15"

# 转换特定想法
/issue:from-brainstorm SESSION="WFS-brainstorm-2024-01-15" --idea=3

# 自动模式
/issue:from-brainstorm --auto SESSION="WFS-brainstorm-2024-01-15"

Issue 工作流程

graph TD
    A[发现 Issue] --> B[创建 Issue]
    B --> C[规划解决方案]
    C --> D[形成执行队列]
    D --> E[执行队列]
    E --> F{成功?}
    F -->|是| G[完成]
    F -->|否| H[反馈学习]
    H --> C

相关文档

• 工作流命令
• 核心编排
• 团队系统