claude-cookbooks 的 /review-issue 定制斜杠命令：用 Claude Code 标准化 GitHub Issue 审核流程

2026-09-06 16:29:49作者：郦嵘贵Just

claude-cookbooks 仓库在 .claude/commands/review-issue.md 中定义了一个名为 /review-issue 的 Claude Code 自定义斜杠命令，用于按社区规范审核并回复 GitHub issue：从拉取 issue 详情、六类问题分类、逐类型草拟回复，到标签建议与"人工批准后执行"的完整闭环。阅读本文你将掌握该命令的完整定义结构、八步审核流程、回复语气准则与三类范例回复，并能复用到自己的仓库中，用"最小权限工具声明 + 结构化流程提示词 + 人工审批门"这一模式把重复性的 issue 维护工作交给 AI 完成。

1. 命令定位：`.claude/commands/` 下的仓库级工作流

在 claude-cookbooks 中，所有 Claude Code 斜杠命令集中存放在 .claude/commands/ 目录，仓库根目录的 CLAUDE.md 将 .claude/ 标注为 "Claude Code commands and skills"，CONTRIBUTING.md 进一步说明这些命令"在 Claude Code（本地开发）和 GitHub Actions CI 中都能工作"，并强调其使用"与 CI 流水线完全相同的校验逻辑"，帮助开发者在 push 之前提前发现问题。

当前该目录下共有六个命令，各自覆盖一种协作场景：

命令文件	用途
review-issue.md	审核并回复 GitHub issue（本文主题）
review-pr.md	人工触发的 PR 代码审查（含审批交互）
review-pr-ci.md	面向 CI/自动化环境的 PR 审查，自动回帖
notebook-review.md	Jupyter notebook 与 Python 脚本综合审查
model-check.md	校验 notebook 中 Claude 模型引用是否过时
link-review.md	检查变更文件中的链接质量与安全问题

可以看到一个清晰的设计分界：PR 侧审查（/review-pr、/notebook-review 等）关注代码与 notebook 质量，而 /review-issue 是唯一面向 issue 队列的命令，承担的是"社区接口人"角色——它不写代码，而是帮助维护者快速判断一个 issue 属于什么性质、该怎么回、要不要关。

2. 定义文件完整结构解析

整个命令就是一个带 YAML frontmatter 的 Markdown 文件，由"元数据 + 提示词正文"两部分构成。

2.1 YAML frontmatter：最小权限的工具白名单

文件头部（review-issue.md 第 1–4 行）声明了：

---
allowed-tools: Bash(gh issue view:*), Bash(gh issue list:*), Bash(gh issue comment:*), Bash(gh issue edit:*), Bash(gh issue close:*), Read, Glob, Grep, AskUserQuestion
description: Review and respond to a GitHub issue
---

这里有两处值得借鉴的工程细节：

allowed-tools 做了细粒度收敛。 它没有笼统地放开 Bash，而是用 Bash(gh issue view:*) 这样的语法把 Shell 权限精确限定在 gh issue 子命令族内——view（查看）、list（列表）、comment（评论）、edit（加标签等编辑）、close（关闭）。这意味着即便提示词被"跑偏"，命令执行器层面也不允许 Claude 执行 git push、gh pr merge 等白名单之外的操作。对比同目录的 review-pr.md（声明了 Bash(gh pr checkout:*)、Bash(git log:*)、Task 等更宽的工具集），issue 命令的工具面更小，与其"只读调研 + 有限写操作"的任务性质匹配。
Read、Glob、Grep 与 AskUserQuestion 各司其职。 前者三个支撑流程中"读取被 issue 引用的 notebook/文件以验证问题是否属实"这一步；AskUserQuestion 则是后面 Step 7"人工审批门"的载体——所有对 GitHub 产生实际写操作（回帖、打标、关单）的动作，都必须在用户通过该工具明确点头之后才执行。

description 字段则用于命令发现与展示："Review and respond to a GitHub issue"。

2.2 参数约定

正文以 ## Arguments 开篇，声明唯一入参：

$ARGUMENTS：要审核的 issue 编号。

调用形式即 /review-issue <issue number>。$ARGUMENTS 是 Claude Code 斜杠命令的内置占位符，会在命令体中的所有 gh 命令里被替换为实际编号。

3. 八步审核流程

命令正文（## Your task 之后）把整个任务编排成 Step 1 至 Step 8，每一步都有明确的输入、动作和产出。以下按原文完整展开，并标注其中蕴含的设计意图。

Step 1：收集 issue 上下文

命令要求第一步就执行固定的 gh 命令，一次性拉取结构化数据：

gh issue view $ARGUMENTS --repo anthropics/claude-cookbooks --json number,title,body,author,labels,state,comments,createdAt

注意 --json 显式列出了七个字段（编号、标题、正文、作者、标签、状态、评论、创建时间），而不是默认的文本渲染输出——这让模型在分类时获得的是机器可读的完整结构，尤其 comments 字段保证了"issue 下面已经讨论了什么"不会遗漏。另外 --repo anthropics/claude-cookbooks 把目标仓库硬编码进了命令，从源码结构看这是一个适用前提：该命令直接在本仓库语境下运行；若要移植到其他仓库，需要同步改写这一参数。

Step 2：六类问题分类

命令要求根据 issue 内容将其归入六类，每一类对应完全不同的处理策略：

Spam/Noise（垃圾/噪音）：乱码、测试帖、跑题内容或有恶意的内容；
Bug Report（缺陷报告）：报告 cookbook 中损坏的代码、失效链接或错误信息；
Cookbook Proposal（内容提案）：提议新增内容或重大扩充；
Question（提问）：询问用法、API 行为或寻求澄清；
Community Resource（社区资源分享）：分享外部项目或资源（应引导至 Discord 等社区渠道）；
Duplicate（重复 issue）：已有同类 issue 或问题已被解决。

这套分类覆盖了维护一个内容型仓库（而非纯代码库）时 issue 队列的主要形态：代码仓库常见的"bug"在这里特指"notebook 里坏掉的代码/链接"，而"提案评估"与"资源分享分流"则是教程类仓库特有的高频场景。分类是后续所有分支决策（怎么回、打什么标签、关不关）的开关。

Step 3：核验相关上下文

对于引用了具体文件或 notebook 的 issue，命令要求模型做三件事：

读取被引用的文件，理解上下文；
验证 issue 是否属实（例如"失效链接"是否真的失效）；
查找可能已处理该问题的相关 issue 或 PR。

这一步把流程从"机械回帖"升级为"有据可依的回应"——回复中可以说"I can confirm the link is broken"（我已确认链接确实失效），而不是空泛的感谢。对仓库维护者而言，这也省去了人工翻查 notebook 的时间。

Step 4：按类型草拟回复

这是命令最核心的部分：为六类 issue 分别规定了回复策略。原文要求逐条继承如下。

Spam/Noise：

建议不留评论直接关闭；
如涉及安全问题则单独标记。

Bug Report：

确认收到并感谢报告者；
尽可能自行验证（检查被引用的文件/代码）；
若属实且修复简单：邀请报告者提交一个带签名提交（signed commits）的 PR；
若属实但复杂：确认收到并表示"已在关注"（on our radar）;
若已修复：直接引用修复所在的 PR/commit。

原文给出的示例话术是："Thanks for the report! Would you be open to submitting a PR to fix this? If so, please ensure you use signed commits"。这里"邀请提交者直接提 PR"的策略与 CONTRIBUTING.md 中的贡献流程（分支命名、conventional commits、pre-commit 钩子）是配套的——回复把新贡献者引导进了仓库既有的开发工作流。

Cookbook Proposal：

先致谢；
按三条标准评估：
- 是否直接聚焦 Claude API/SDK 能力？
- 是否实用且有清晰的教学价值？
- 是否与现有内容有差异化？
若有价值：表达兴趣，必要时提出澄清问题；
若不符：礼貌说明原因并引导至合适渠道。

原文的婉拒示例话术："While [topic] is interesting, we focus on showcasing Claude's native API capabilities. We'd encourage you to think about what specific Claude features you want to demonstrate rather than translating patterns from external frameworks." 这实际上把仓库的内容边界（只做 Claude 原生 API 能力演示，而非移植外部框架模式）固化进了回复模板。

Question：

能给直接答案就给；
指向 Claude 官方文档（docs.claude.com）；
如适用，引用仓库中具体的 cookbook 示例；
引导后续讨论去 Discord 社区；
若属 API 本身的 bug，引导至正确的报告渠道。

Community Resource：

感谢分享但分流到更合适的场地；
明确该仓库的 issue 只用于 cookbook 相关问题，不做社区展示墙；
分流后关闭 issue。

原文示例话术："Thanks for sharing your project! We don't track community resources as GitHub issues, but there are great places to share your work: the #share-your-project channel on our Discord or the r/ClaudeAI community on Reddit."

Duplicate：

引用原始 issue/PR；
情况合适时作为重复项关闭。

Step 5：建议标签

命令维护了一张七项标签映射表，让分类结果直接落成 GitHub label：

标签	适用类型
`bug`	Bug 报告
`enhancement`	功能请求或提案
`question`	提问
`documentation`	文档改进
`duplicate`	已存在
`wontfix`	不予处理
`good first issue`	适合新贡献者的简单修复

值得注意的是 good first issue 这一项：当 Step 4 判定"bug 属实且修复简单"、并邀请报告者提 PR 时，打上该标签可以进一步把它转化为社区新手的入口任务。分类、回复、标签三条线在这里汇合。

Step 6：结构化呈现审核结果

在采取任何动作之前，命令要求把调查结论以固定六段式呈现给用户：

Issue Summary：issue 说了什么的简述；
Classification：归类结果；
Validity Check：issue 是否成立/可操作（如果做过核验）；
Suggested Response：草拟好的、可直接发布的评论；
Suggested Labels：建议添加的标签；
Suggested Action：建议是评论、关闭还是其他操作。

这个输出模板让"AI 做了什么判断"完全透明可审查——维护者不需要逐条追问，一眼即可看到分类依据、草稿回复和建议动作，然后整体拍板或逐条修正。

Step 7：人工审批（Human-in-the-loop 门）

命令明确要求使用 AskUserQuestion 工具向用户确认三个独立问题：

是否发布草拟的回复？
是否添加建议的标签？
是否关闭该 issue（如果适用）？

把三个动作拆成三个可独立批准的选项，而不是一个"全部执行/全部取消"的总开关，是细粒度授权的体现：例如用户可能只想发评论、暂不打标签。所有对 GitHub 的写操作都被挡在这道门之后，这正是 frontmatter 里 AskUserQuestion 工具存在的意义。

Step 8：执行动作（仅当获批）

批准后，按用户选择执行对应的 gh 命令，原文给出的四条命令为：

发布评论：

gh issue comment $ARGUMENTS --repo anthropics/claude-cookbooks --body "YOUR_RESPONSE"

添加标签：

gh issue edit $ARGUMENTS --repo anthropics/claude-cookbooks --add-label "label1,label2"

关闭 issue（指定原因）：

gh issue close $ARGUMENTS --repo anthropics/claude-cookbooks --reason "not planned"

或附带评论关闭：

gh issue close $ARGUMENTS --repo anthropics/claude-cookbooks --comment "Closing because..."

这四条命令恰好与 frontmatter 白名单中的 Bash(gh issue comment:*)、Bash(gh issue edit:*)、Bash(gh issue close:*) 一一对应——流程用到的每一类写操作都有且仅有对应的工具权限，工具声明与流程步骤互相印证。

4. 回复语气准则与三类范例

命令正文在流程之后还固定了两段"软规范"，约束草拟回复的风格。

语气准则（Response Tone Guidelines）

原文六条准则为：

专业、友好、简洁；
感谢贡献者的参与；
婉拒提案时直接但不居高临下；
尽可能给出可执行的下一步；
用链接指向资源，而不是把所有解释内联写进评论；
不过度解释、不过度道歉。

三类范例回复

原文附带了三段可直接参照的回复模板，分别对应最高频的三种 issue 类型：

Bug 报告回复：

Hi @username, thanks for the detailed report!

I can confirm the link is broken. Would you be open to submitting a PR to fix this? If so, please ensure you use signed commits.

If you'd prefer not to submit a PR, no worries - we'll get this fixed.

注意"确认属实（I can confirm the link is broken）→ 邀请提 PR → 兜底承诺（你不提我们也会修）"的三段结构，与 Step 4 的 Bug Report 策略完全一致。

提问回复：

Hi @username!

The `cache_control` parameter is needed because... [explanation]

For more details, check out the prompt caching documentation.

If you have follow-up questions, our Discord is a great place for discussion!

以 cache_control 参数为例展示了"直接解释 + 指向官方文档 + 引导社区讨论"的组合拳，其中 prompt caching 主题在仓库内有对应实战内容可查，如 misc/prompt_caching.ipynb，这也呼应了 Step 4 中"引用具体 cookbook 示例"的要求。

提案婉拒回复：

Hi @username, thanks for the detailed proposal!

While the concept is interesting, we focus our cookbooks on demonstrating Claude's native API capabilities directly. We'd encourage you to consider:

- What specific Claude API features are you showcasing?
- How is this differentiated from existing documentation?
- Can users run this self-contained without external dependencies?

If you can reframe the proposal around these questions, we'd be happy to reconsider. Thanks for your engagement with the SDK!

婉拒模板把三条评估标准（Claude 能力聚焦、差异化、自包含可运行）转成了反问清单，给提案者留下重新提交的路径，而不是简单关门。

5. 与仓库内其他审查命令的协同

从源码结构看，/review-issue 并非孤立存在，而是与 PR 侧命令构成完整的质量闭环：

/review-pr 与 /review-pr-ci：分别面向人工与 CI 环境的 PR 审查。人工版通过 Task 工具调用 code-reviewer 子代理（一位"专精本仓库 notebook 审查的资深工程师"人设，检查 TLO 学习目标、密钥管理、ruff 规范等），审查报告按 APPROVE / REQUEST_CHANGES / COMMENT 三档给出建议，同样经 AskUserQuestion 批准后回帖；CI 版则去掉交互直接回帖，并把 Detailed Review 折叠进 <details> 标签以降低噪音。
/model-check：拉取官方当前模型列表，检查变更文件中是否引用了已废弃模型（如旧版 Sonnet 3.5、Opus 3）；CLAUDE.md 中的 Key Rules 也同步要求"使用不带日期后缀的模型别名、Never use dated model IDs"。
/link-review：检查变更文件里的失效链接、过时链接与安全问题，与 /review-issue 中"bug 特指 notebook 里坏掉的链接/代码"相互呼应——issue 报告失效链接，PR 侧则防止新链接问题混入。
/notebook-review：调用 .claude/skills/cookbook-audit/ 中的 notebook 审查技能做综合质量检查，并按 ✅/⚠️/❌ 三级输出结论。

也就是说，issue 侧命令负责"入口分流"（判断问题真伪、引导贡献者、清理噪音），PR 侧命令负责"出口把关"（代码与 notebook 质量、模型时效、链接健康），两条线合起来覆盖了 claude-cookbooks 社区贡献的主要协作路径。

6. 可复用的设计模式总结

以 review-issue.md 为样本，可以提炼出一套在任意 GitHub 仓库中复刻"AI 值守 issue 队列"的做法：

一个 Markdown 文件即一条命令：YAML frontmatter 声明 description（可发现性）与 allowed-tools（最小权限边界），正文用编号步骤写清流程。工具白名单与正文实际使用的命令应严格对齐，形成双重约束。
固定数据入口：第一步就用 gh ... --json 拉取结构化字段，避免模型基于不完整的上下文做判断。
先分类后分支：定义一张覆盖 issue 队列全部形态的分类表，每类绑定独立的回复策略、标签与处置动作，避免"一刀切"模板。
验证再说话：要求模型读取被引用文件核验真伪，回复中才能给出"已确认"级别的表述。
结构化中间产物：用固定的六段式输出（摘要/分类/核验/草稿/标签/动作）把 AI 的判断链完整暴露给人类。
写操作必经审批门：把发布评论、加标签、关单拆成独立的 AskUserQuestion 选项，批准后才调用对应的 gh 写命令；--repo 等目标参数建议按实际仓库改写后固定。
语气与范例内置：把语气准则和三类回复范例直接写进命令文件，让草拟出的评论风格稳定可预期，而不是依赖模型自由发挥。