code-review

代码审查方法

针对 template-ts 代码库开展系统化的 PR 前审查。优先识别关键风险，然后报告重大和次要问题，并提供具体修复方案。

审查流程

1. 确定范围 — 明确要审查的内容。
2. 扫描变更 — 根据 template-ts 审查类别进行分析。
3. 验证不确定的模式 — 仅在仍有疑问时使用外部查询。
4. 对发现的问题分类 — 分为严重、重大或次要问题。
5. 生成报告 — 输出可执行的审查摘要。
6. 运行自动化检查 — 执行仓库标准质量门禁。

---

步骤 1：确定范围

按以下顺序确定审查范围：

1. 优先采用用户明确指定的范围。 审查用户提供的确切文件、PR、提交或分支比较。
2. 范围缺失时，默认推断最近的提交。 在未指定范围且有仓库上下文时，使用 git log -5 --oneline 和 git diff HEAD~5..HEAD --stat。
3. 仅在必要时提出一个明确的范围问题。 只有在无法获取仓库状态，或存在多个合理的范围且无法可靠推断时才提问。

---

步骤 2：应用 Template-ts 审查类别

使用 references/review-pattern-catalog.md 中的完整类别清单和示例。

应用以下类别组：

• TRPC 模式
• TanStack Router 和 Query 模式
• 代码去重（DRY）
• 代码质量和风格约定
• 安全
• 性能
• 测试
• Effect 模式（审查范围涉及 Effect 代码时）

需要更深入的专项审查时，加载相关技能：

• trpc-patterns
• tanstack-frontend
• effect-ts
• scan-effect-solutions（用于深入审查 Effect）

---

步骤 3：验证不确定的模式

仅当本地代码库中的证据不足时，才使用查询工具。

使用 Exa 验证外部库或不断演进的 API 在实际场景中的不确定用法。

使用 Context7 确认官方文档细节（确切的 API 名称、特定版本的行为、弃用情况）。

如果仓库中已有明确的规范模式，则两者都跳过。

---

步骤 4：按比例应用测试要求

行为变更必须要求编写测试。

以下情况视为行为变更：

• 新增或修改业务逻辑
• API 契约变更
• 查询/加载器行为变更
• 安全或授权逻辑变更
• 用户可见的组件行为变更

以下情况属于低风险变更，可选编写新测试：

• 仅修改文档
• 仅修改注释
• 不涉及逻辑变更的机械式重构（例如仅重命名、仅调整格式、仅调整导入顺序）

在最终审查摘要中明确说明测试依据。

---

步骤 5：运行自动化检查

如果仓库使用标准的 template-ts 质量门禁脚本，则运行 bun run check。

如果使用其他约定，则运行仓库对应的命令集（例如分别运行 lint、类型检查和测试命令）。

在最终报告中记录命令的执行结果。

---

严重程度分类

严重（合并前必须修复）

• 安全漏洞
• SQL 注入或硬编码密钥
• 受保护的端点缺少身份验证
• 对公共 API 的破坏性变更

重大（应修复）

• 错误的 TRPC v11 模式（使用 .useQuery 而不是 .queryOptions）
• N+1 数据库查询
• 缺少预取，导致页面加载缓慢
• 手动定义类型，而不是使用 RouterInputs/RouterOutputs
• 代码重复，违反 DRY 原则

次要（可考虑修复）

• 风格不一致
• 缺少文档
• 非关键的重构机会

---

报告模板

# Code Review Report

**Scope:** [What was reviewed]
**Date:** [Current date]

---

## CRITICAL ISSUES

[List with file:line, description, fix]

---

## MAJOR ISSUES

[List with file:line, description, fix]

---

## MINOR ISSUES

[List with file:line, brief description]

---

## TEST EXPECTATIONS

- Behavior-changing code paths covered: [Yes/No + details]
- Low-risk changes with test exemption: [Yes/No + rationale]

---

## AUTOMATED CHECKS

- Commands run: [List]
- Result: [Pass/Fail]

---

## POSITIVE OBSERVATIONS

- [Good patterns found]

---

## SUMMARY

**Assessment:** [APPROVE / NEEDS_WORK / REJECT]
**Next steps:** [Specific actions]

## Quick Stats

- Files reviewed: [N]
- Issues: Critical: [N], Major: [N], Minor: [N]

---

评估标准

批准

• 没有严重问题
• 核心 TRPC 和 TanStack 模式正确
• 仓库质量门禁检查通过

需要改进

• 存在重大模式违规
• 行为变更缺少必需的测试
• 性能问题影响可靠性或用户体验

拒绝

• 存在安全漏洞
• 引入了破坏性变更，但没有迁移路径
• 存在根本性的设计缺陷，导致变更无法安全合并

---

相关技能

• trpc-patterns — TRPC 路由器模式、过程、错误处理
• tanstack-frontend — Router、Query、Form 模式
• effect-ts — Effect 服务、层、ManagedRuntime、错误处理
• scan-effect-solutions — 深度 Effect 合规性扫描
• production-troubleshooting — 性能调查