用途
backlog 用于管理项目的待办事项(backlog)。它覆盖两个方向:将单个条目登记进项目待办,或列出并梳理已有待办。技能会判断用户意图,选择进入 add 模式(登记一条)或 review 模式(查看已有内容)。两种模式共用同一套目标位置检测逻辑。
目标位置检测
按顺序尝试,并在同一流程的后续步骤中缓存结果:
- gh repo view 成功,则使用该仓库的 GitHub issues。
- 否则若存在 docs/BACKLOG.md,add 时追加,review 时读取。
- 否则若存在 docs/issues/ 目录,则按问题拆分文件(每个问题一个 .md,带数字前缀)。
- 否则询问用户放在哪里。不要在项目根目录静默创建文件。 如果用户在既无 git 也无 docs/ 的目录中调用此技能,应说明情况并在行动前先询问。
add 模式
用户有一条要登记的条目。目标是比用户自己手动输入 issue 更省事。
- 重复检查:在已有条目中搜索关键词重合(gh issue list --search "<keywords>" 或 grep 本地文件)。若存在近似项,提示并询问是更新已有项还是新建。
- 按输入量适度增强:用户只写一行时,可从 CLAUDE.md 和当前项目状态补充 2-3 条简短上下文要点(技术注意事项、相关模块、待解决问题)。若用户已写了一段或更多,则原样登记,不要重写其表述。
- 澄清问题最多一个,仅在范围或分类(bug 与 enhancement)确实含糊时提出。能从上下文猜测则直接猜。
- 登记后返回 URL 或路径,不附加末尾总结。
标签:GitHub 上从 gh label list 选择,不要未经询问发明新标签;本地 docs/BACKLOG.md 或按问题拆分文件,在标题前加 [bug] / [enhancement] / [question] 前缀以便扫读。
review 模式
用户想查看当前有哪些开放项,并可能对某项采取行动。
列出:
- GitHub:gh issue list --state open --limit 50 --json number,title,labels,createdAt。
- 本地文件:读取并解析其项目符号或标题结构。
- 按问题拆分文件:列出文件名及其首行标题。
分组展示:先按标签(bug / enhancement / question / 其他),组内再按年龄,每条一行给出编号、标题、年龄、标签。除非列表确实很长(超过 50 条),不做分页。
提供三种操作但不自动选择:
- 分类整理:重新打标签、关闭过期项、合并重复项,逐条确认。
- 选取一条:把该条完整内容载入上下文后停止。不要自动实现;用户可能只是在决定聚焦方向前扫一遍待办。
- 主题归纳:聚类相关条目,建议分组或父 issue。
“选取一条”是刻意的停止点。滑入实现工作会打断用户原本的审查流程。
何时转向其他技能
以下相邻情况不应由本技能处理,应尽早识别并在动手前建议合适的技能:
- 一次处理多条(如“我发现了三个 bug”)→ qa-to-issues,用于交互式多 bug 访谈。
- 完整规格与用户故事(如“为 X 写一份规格”“我想要 PRD”)→ to-spec。
- 将已有计划拆成切片(如“把这个计划拆成 issue”)→ to-tickets。
转向只用一句话说明哪个技能更合适,然后停止。
注意事项
- 不要在分类整理中批量关闭。应先展示,确认后再关闭;错误关闭的代价远高于多一次确认。
- 不要发明标签。gh label list 成本很低;尊重既有标签约定,因为标签会驱动下游的筛选器和项目看板。
- 登记必须比手动输入更省事。“最多一个澄清问题”是为了保住价值主张,若技能耗时超过用户自己输入,用户就会弃用。
- 按问题拆分文件需要沿用既有编号方案(如 0001-slug.md 或 001-slug.md),不要强加新的。
- 避免污染项目根目录:若既无 gh、也无 docs/BACKLOG.md、也无 docs/issues/,就询问用户。
- 不要重构用户的文字。用户写了一段就登记那一段,套模板会显得 AI 在覆盖其意图。
- 尊重 issue 模板:若仓库有 .github/ISSUE_TEMPLATE/,正文应符合对应模板(通常是 bug 与 feature);gh issue create --title --body 会静默跳过模板,令围绕模板字段构建筛选器或自动化的维护者感到意外。