docs-review

文档审查技能

@./../_shared/metabase-style-guide.md

审查模式检测

重要：在开始审查之前，确定使用哪种模式：

1. PR 审查模式：如果 mcp__github__create_pending_pull_request_review 工具可用，说明你正在审查一个 GitHub PR

   • 使用待处理审查工作流，将所有问题作为一次统一的审查发布
   • 遵循下方“PR 审查模式格式”中的工作流步骤

2. 本地审查模式：如果该 MCP 工具不可用，在对话中输出问题

   • 将所有问题格式化为带编号的 Markdown 列表（如下方“反馈格式”所述）

审查流程

1. 检测审查模式 - 检查 mcp__github__create_pending_pull_request_review 是否可用
2. 通读一遍改动，理解意图
3. 检查所有违反风格指南或严重影响可读性的问题
4. 只标记值得提及的问题 - 如果对读者不会产生实质性影响，就跳过
5. 必须：为所有反馈按顺序编号 - 从问题 1 开始，每发现一个问题就递增

审查清单

浏览 diff，查找以下问题：

语气和声音：

• 正式/企业化语言（用“utilize”而不是“use”、“offerings”等）
• 用“Users”而不是“people”或“companies”
• 过多感叹号或过于热情的语气
• 只是告诉读者某件事很酷，而不是展示给他们看

结构和清晰度：

• 重要信息被埋没而不是放在开头
• 冗长但价值不大的文字
• 没有明确目的的段落
• 无法传达重点的模糊标题
• 说明在告诉“该做什么”之前先解释“为什么”
• 将任务描述为“easy”或“simple”

链接和引用：

• 将“here”一词作为链接，而不是使用描述性文字
• 标题中包含链接（除非整个标题都是链接）

格式：

• 用 & 符号代替“and”（专有名词除外）
• 列表格式不一致

代码和示例：

• 无法运行或会报错的代码示例
• 命令未按执行顺序排列
• 使用全宽截图而不是限定范围的 UI 元素
• 过多或不必要的图片

句子结构：

• 引入新术语时过度使用代词

快速扫描表

模式	问题
we can do X, our feature	应改为“Metabase”或“it”
click here, read more here	需要描述性链接文字
easy, simple, just	删除居高临下的限定词
users	如有可能，应改为“people”或“companies”

反馈格式

强制要求：每一条问题都必须从问题 1 开始按顺序编号。

这种编号格式不可协商。它让用户能够高效地引用特定问题（例如，“修复问题 1、3 和 5”），并跟踪哪些反馈已得到处理。

本地审查模式格式

在对话中输出问题（本地模式）时，使用此格式：

## Issues

**Issue 1: [Brief title]**
Line X: Succinct description of the issue
[code or example]
Suggested fix or succinct explanation

**Issue 2: [Brief title]**
Line Y: Description of the issue
Suggested fix or explanation

**Issue 3: [Brief title]**
...

示例：

问题 1：语气正式 第 15 行：这里可以更口语化。考虑改为：“You can't...” 而不是 “You cannot...”

问题 2：标题模糊 第 8 行：标题可以更具体。尝试直接点明重点：“Run migrations before upgrading” 而不是 “Upgrade process”

PR 审查模式格式

在发布到 GitHub（PR 模式）时，请使用 待处理审查工作流：

工作流步骤：

1. 开始一次审查：使用 mcp__github__create_pending_pull_request_review 开始一次待处理审查

   • 这会创建一个草稿审查，在提交之前不可见

2. 获取 diff 信息：使用 mcp__github__get_pull_request_diff 了解代码更改和行号

   • 这有助于你为评论确定正确的文件路径和行号

3. 识别所有问题：通读所有更改，找出每个值得提及的问题

   • 在发布任何评论之前收集所有问题
   • 按顺序编号（Issue 1、Issue 2、Issue 3 等）

4. 添加审查评论：对每个问题使用 mcp__github__add_pull_request_review_comment_to_pending_review

   • 关键：在单次响应中使用多个工具调用并行发布所有评论
   • 每条评论都应引用 diff 中的特定文件路径和行号
   • 每条评论正文以 **Issue N: [Brief title]** 开头
   • 包含描述和建议的修复方案

5. 提交审查：使用 mcp__github__submit_pending_pull_request_review 一次性发布所有评论

   • 使用事件类型 "COMMENT"（而不是 "REQUEST_CHANGES"）使其成为非阻塞的
   • 不要包含正文消息 - 将正文留空或完全省略
   • 所有评论将作为一次连贯的审查一起显示

评论格式示例：

**Issue 1: Formal tone**

This could be more conversational. Consider: "You can't..." instead of "You cannot..."

重要：

• 每个问题都有自己的审查评论，附加到待处理审查中
• 按顺序为所有评论编号（Issue 1、Issue 2、Issue 3 等）
• 评论正文始终以 **Issue N: [Brief title]** 开头
• 必须在单次响应中并行添加所有评论 - 不要在单独的响应中逐个添加
• 不要向对话输出摘要消息 - 只发布 GitHub 审查评论
• 提交审查时，不要包含 body 参数（或将其留空），以避免用摘要文本弄乱 PR
• 提交后，审查将显示为包含多条评论的单次审查

最终检查

1. 从你的评估中移除任何即使解决后也不会给读者带来实质性差异的问题。只标记值得作者花时间修复的问题。
2. 验证所有问题都按顺序编号，从 Issue 1 开始且编号没有空缺。
3. 确认格式完全匹配：**Issue N: [Brief title]**，其中 N 是问题编号。
4. 在 PR 模式中：验证每个问题都作为单独的 GitHub 评论发布（而不是输出到对话）。