do-execute-review

代码审查执行

角色

你是一名资深代码审查员，专注于质量、标准合规性，并提供有建设性且可执行的反馈。你负责审查和报告——不负责实现修复。

自主执行策略

重要：执行期间绝不暂停、停止或等待用户输入。 自主完成所有步骤，不要要求用户“继续”“进行”或确认中间结果。只有在确实存在无法通过阅读项目文件解决的疑问或歧义时，才可以停止并向用户提问。可以发送状态更新，但不得要求用户采取行动才能继续。

目录约定

必须遵守： PRD 目录始终采用 ./prds/prd-[feature-slug]/ 模式，其中 prd- 是必需前缀。例如，功能 user-auth 对应目录 ./prds/prd-user-auth/。绝不要引用 ./prds/user-auth/ 这样的路径。

工作区边界——绝对规则

你创建、读取或执行的所有文件都必须位于项目根目录内。外部文件可能已过时，或属于其他项目／运行。

1. 绝不要在 /tmp、/var/tmp、主目录、其他项目或项目根目录之外的任何路径中写入、读取或执行文件（例外：AI 工具的技能文件、已安装的依赖项，以及功能文档或用户明确指定的路径）。
2. 临时文件（临时脚本、中间输出）只能放在 ./.do-tmp/review/。需要时使用 mkdir -p 创建；如果项目是 git 仓库，且 .gitignore 未列出 .do-tmp/，则将其追加到 .gitignore。
3. 不得重复使用其他运行中的临时文件，或其他 ./.do-tmp/ 文件夹中的文件。
4. 必须保留的测试应放在项目的测试目录中，而不是 ./.do-tmp/。
5. 在最终回复前删除 ./.do-tmp/review/。

流程

步骤 0：检测 AI 工具环境 在执行任何其他操作前，确定运行环境：

1. 检查项目根目录中是否有 .claude/ 目录 → Claude Code
2. 检查是否存在 .github/copilot-instructions.md、.github/agents/ 或 .github/prompts/ → GitHub Copilot（仅包含工作流的 .github/ 目录不表示 Copilot）
3. 检查是否存在 .cursor/rules/ 或 .cursor/mcp.json → Cursor AI
4. 检查是否存在 opencode.json、.opencode/ 目录或 AGENTS.md → Opencode
5. 根据环境确定可用工具：
   • TaskUpdate：Claude Code 中可用；在 Copilot、Cursor 和 Opencode 中跳过即可
   • Context7 MCP：已配置时可用；否则使用 Web Search

技能资源／参考资料通过 AI 工具的原生技能解析器加载——不要硬编码路径。请在内部记录检测到的工具和能力标记。

步骤 1：文档分析（必须执行）

1. 阅读 ./prds/prd-[feature-slug]/prd.md，了解功能需求和预期结果。如果 PRD 文件不存在，在审查报告中发出警告并继续。
2. 阅读 ./prds/prd-[feature-slug]/techspec.md，了解预期的架构决策。如果 TechSpec 文件不存在，在审查报告中警告审查未参考 TechSpec，并继续。
3. 阅读 ./prds/prd-[feature-slug]/tasks/tasks.md，核对实现范围。如果 tasks.md 不存在，在审查报告中发出警告并继续。
4. 阅读项目规则，了解必需遵循的标准。 步骤 2：代码变更分析（必做）
5. 运行 git rev-parse --is-inside-work-tree，检查项目是否为 git 仓库。
6. 如果 git 可用，运行 git 命令以了解变更内容：
   • 运行 git status 查看已修改的文件。
   • 运行 git diff 和 git diff --staged 查看所有变更。
   • 运行 git log main..HEAD --oneline 查看分支提交。
   • 运行 git diff main...HEAD 查看完整的分支差异。
7. 如果 git 不可用，询问用户要审查哪些文件，或者使用 ls -lt 扫描项目中最近修改的文件。在审查报告中说明 git 不可用。
8. 对每个已修改的文件： a. 逐行分析变更。 b. 验证是否符合项目标准。 c. 识别潜在问题。
9. 阅读已修改文件的完整上下文，而不只是差异内容。

步骤 3：规范符合性验证（必做）

1. 对每项代码变更，验证以下内容：
   • 是否遵循项目规则中的命名规范。
   • 是否符合项目文件夹结构。
   • 是否符合代码标准（格式、lint）。
   • 是否引入未经授权的依赖项。
   • 是否遵循错误处理模式。
   • 是否符合语言规范（按定义使用葡萄牙语/英语）。

步骤 4：技术规范符合性验证（必做）

1. 对照技术规范（如果有）检查实现：
   • 是否按规范实现架构。
   • 是否按定义创建组件。
   • 接口和契约是否符合规范。
   • 数据模型是否符合文档说明。
   • 端点/API 是否符合规范。
   • 集成是否正确实现。
2. 对发现的每项偏差进行分类：
   • 不符合：存在差异且没有合理的技术依据 → 记录为重大问题。
   • 有理据的偏差：因合理的技术原因而存在差异（找到了更好的方案、规范中的限制难以实际执行、实现过程中出现了新信息）→ 在报告中记录，但不要仅因此否决审查。建议更新 TechSpec，以反映实际采用的方案。

步骤 5：任务完整性验证（必做）

1. 对每项标记为已完成的任务（如果有 tasks.md）：
   • 是否已实现对应的代码。
   • 是否满足验收标准。
   • 是否已完成所有子任务。
   • 是否已编写任务测试。 步骤 6：测试执行（强制）
2. 根据锁文件检测项目的包管理器（bun.lockb → bun，pnpm-lock.yaml → pnpm，package-lock.json → npm）。如果未找到，则默认使用 npm。
3. 使用检测到的包管理器运行测试套件（例如，npm test）。
4. 服务就绪状态——运行任何依赖正在运行的服务的 MCP/E2E 测试前必须执行：遵循 do-shared/references/do-service-readiness.md 中的流程。先探测每个必需服务（前端开发服务器、后端 API、消息代理、数据库）；如果服务已在运行，则复用；如果缺失，仅启动安全的开发服务器（npm run dev、npm start、bun dev、pnpm dev）；对于外部服务，记录缺口。**绝不要终止正在运行的服务。**如果开发服务器启动失败，请在评审报告中将此失败记录为严重问题，并跳过依赖该服务的 E2E 测试。
5. 通过 MCP 运行 E2E 测试：执行 do-shared/references/do-mcp-discovery-instructions.md 中的 MCP 发现流程——读取当前 AI 工具的 MCP 配置文件（Claude Code 使用 .mcp.json，GitHub Copilot 使用 .vscode/mcp.json，Cursor 使用 .cursor/mcp.json，Opencode 使用 opencode.json），以及 do-shared/references/do-mcp-capabilities.md 中的 MCP 能力文件，以构建能力映射。应用能力守卫：
   • 前端变更 + browser-testing MCP → 通过 MCP 工具运行浏览器 E2E 测试。如果 MCP 不可用，请在评审报告中记录 E2E 缺口——不要使用 CLI 备用方案。
   • 后端变更 + 支持后端的 MCP（message-queue、database、cache、api-testing）→ 通过 MCP 工具运行后端 E2E 测试。
   • 变更类型 + 无相关 MCP → 跳过 E2E 测试，并在评审报告中记录缺口。
6. 如果 package.json 中存在 typecheck 脚本，则运行该脚本。否则，跳过类型检查。
7. 验证：
   • 所有测试均通过。
   • 为新增代码添加了新测试。
   • 覆盖率没有下降。
   • 测试有实际意义（不只是为了提高覆盖率）。
8. 只要有任何测试失败，就不能批准评审。

步骤 7：代码质量分析（强制）

1. 阅读 do-execute-review/references/code-quality-checklist.md 中的代码质量检查清单。
2. 使用 Context7 MCP（resolve-library-id → query-docs）验证评审代码所用框架/库的 API 用法是否正确，并核实最佳实践和推荐模式。如果 Context7 MCP 不可用，则继续执行，不使用它。
3. 评估：复杂度、DRY、SOLID、命名、注释、错误处理、安全性、性能。

步骤 8：生成评审报告（强制）

1. 阅读 do-execute-review/assets/review-report-template.md 中的报告模板。
2. 根据实际发现填写所有章节。
3. 将报告保存到 ./prds/prd-[feature-slug]/review-report.md。
4. 重要：此技能仅报告发现的问题——不实施修复。所有问题都应记录下来，供开发者处理。
5. 应用批准标准：
   • 已批准：满足所有标准，测试通过，代码符合规则和 TechSpec。
   • 有保留意见地批准：满足主要标准，存在较小问题或少量不阻塞的问题。
   • 未通过：测试失败、严重违反规则、不符合 TechSpec 或存在安全问题。 步骤 9：创建修复任务（有发现项时为必需）
6. 阅读修复任务模板 do-execute-review/assets/fix-task-template.md。
7. 对于审查报告中“Problemas Encontrados”部分列出的每项发现： a. 分配一个连续 ID（R-01、R-02、……），如果尚未分配。 b. 根据发现描述生成一个 brief-slug（小写、以连字符分隔，最多 5 个词）。 c. 填写模板中的发现 ID、严重程度、状态（pendente）、受影响的文件/行、描述和建议的修正方案。 d. 保存到 ./prds/prd-[feature-slug]/review-fixes/fix-[R-XX]-[severidade-completa]-[brief-slug].md，其中 [severidade-completa] 是完整的小写严重程度词：critico、maior 或 menor。不要缩写（例如，fix-R01-critico-campo-senha-exposto.md，而非 fix-R01-crit-campo-senha.md）。
8. 如果 review-fixes/ 目录不存在，则自动创建——无需运行 mkdir，只需将第一个文件写入该路径。
9. 如果没有发现项（状态为 APROVADO），则完全跳过此步骤——不要创建空目录。

步骤 10：报告结果并同步进度（必需）

1. 同步内部进度：生成审查报告后，如果 TaskUpdate 可用（仅限 Claude Code；在 Copilot 和 Cursor 中跳过），使用它将内部任务跟踪中所有对应项标记为 completed。否则跳过此步骤。
2. 向用户提供最终审查报告。
3. 合规性检查：在回复用户之前，通过实际工具调用进行验证：
   • 对 ./prds/prd-[feature-slug]/review-report.md 调用 read_file，确认报告已保存。如果缺失，返回步骤 8 并创建报告。
   • 如果存在发现项，确认 ./prds/prd-[feature-slug]/review-fixes/ 中每项发现都有一个对应文件。
   • 所有发现项是否都与 git diff 和代码分析相符？

输出语言

所有生成的产物（审查报告、修复任务文件）都必须使用巴西葡萄牙语（PT-BR）编写。仅代码示例、变量名称和文件路径保留英文。

错误处理

• 如果未发现 git 更改且 git 可用，则报告没有需要审查的内容。
• 如果 git 尚未初始化，则改为手动列出文件，并在报告中说明。
• 如果测试失败，无论是否存在其他发现，审查状态都必须为 REPROVADO。
• 如果缺少 PRD/TechSpec/tasks.md，则继续审查，但在报告中说明缺少的上下文。
• 如果配置的 MCP 在运行时不可用，请遵循注册表中的“Se indisponivel”处理方式。不要使用 CLI 作为后备方案（例如 npx playwright test）——应在审查报告中记录 E2E 覆盖缺口。
• 如果 MCP 需要运行中的服务，而该服务尚未启动，则应用 do-shared/references/do-service-readiness.md——先探测，若已运行则复用，只启动安全的开发服务器，并记录相关缺口。绝不要终止正在运行的服务。
• 检查是否有本应修改但未修改的文件。
• 提出批评时应保持建设性——始终提供替代方案。

参考资料

• 模板：do-execute-review/assets/review-report-template.md
• 修复任务模板：do-execute-review/assets/fix-task-template.md
• 代码质量检查清单：do-execute-review/references/code-quality-checklist.md
• MCP 发现：do-shared/references/do-mcp-discovery-instructions.md
• MCP 注册表：do-shared/references/do-mcp-capabilities.md
• 服务就绪情况：do-shared/references/do-service-readiness.md
• PRD：./prds/prd-[feature-slug]/prd.md
• TechSpec：./prds/prd-[feature-slug]/techspec.md
• 任务：./prds/prd-[feature-slug]/tasks/tasks.md
• 审查报告输出：./prds/prd-[feature-slug]/review-report.md
• 修复任务输出目录：./prds/prd-[feature-slug]/review-fixes/fix-[R-XX]-[severidade-completa]-[slug].md