effect-review

Effect-TS 代码审查

协调多个 Agent，按照 Effect-TS 最佳实践审查代码变更。

工作流

第 1 步：查找变更文件

运行 git diff --name-only main...HEAD，查找当前分支上所有变更文件。如果运行失败（例如当前位于 main 分支），则改用 git diff --name-only HEAD~1，或使用 git diff --name-only 查找尚未暂存的变更。

向用户列出变更文件。

第 2 步：对文件分类

将文件划分为以下类别：

• Backend Effect 文件：.ts 文件，但不包括以 .test.ts 结尾的文件、配置文件（.config.ts、tsconfig 等）以及 UI 组件库目录中的文件
• 测试文件：.test.ts 文件
• UI 文件：.tsx 文件
• 跳过：.md、.json、.yml、.css、配置文件、生成文件

第 3 步：并行启动子 Agent

根据文件所属类别，使用 Agent 工具启动相应的 Agent。通过一条消息启动所有适用的 Agent，以实现最大程度的并行处理。

如果存在 Backend Effect 文件，则并行启动以下 4 个 Agent：

• effect-primitives-reviewer — 检查 Effect 原语（Array、Match、Option、forEach、不得使用 try/catch、不得使用 async/await、使用 Layer 而非 Effect.provide）
• branded-types-reviewer — 检查所有实体 ID 是否使用 Branded 类型
• otel-reviewer — 检查追踪设置（Effect.fn 追踪名称、annotateCurrentSpan、结构化日志）
• error-reviewer — 检查错误定义和处理方式（Schema.TaggedError、catchTag、丰富的上下文）
• typescript-reviewer — 检查 TypeScript 模式（不得使用 as any、优先使用 satisfies 而非 as、不得为可推断的类型手动添加类型注解）

如果存在测试文件，则启动：

• test-coverage-reviewer — 检查 @effect/vitest 模式并评估覆盖率缺口

如果存在 UI 文件，则启动：

• ui-reviewer — 检查组件库用法、无障碍性、布局和品牌一致性

向每个 Agent 提供以下提示词：

请针对 [Agent 的专长] 审查以下文件。阅读每个文件，并按 Critical/Warning/Info 分类生成结构化报告。

待审查文件：

• [文件路径列表]

同时阅读参考指南 references/[相关参考文件].md（相对于此技能的路径），了解详细检查清单。

第 4 步：汇总报告

所有 Agent 完成后，将结果整理成一份报告：

# Effect Review Report

## Effect Primitives
[agent output]

## Branded Types
[agent output]

## OTEL / Observability
[agent output]

## Error Handling
[agent output]

## TypeScript Patterns
[agent output]

## Test Coverage
[agent output]

## UI Quality
[agent output]

---

## Summary

| Category | Critical | Warning | Info |
|----------|----------|---------|------|
| Primitives | X | Y | Z |
| Branded Types | X | Y | Z |
| OTEL | X | Y | Z |
| Errors | X | Y | Z |
| TypeScript | X | Y | Z |
| Tests | X | Y | Z |
| UI | X | Y | Z |
| **Total** | **X** | **Y** | **Z** |

**Verdict**: PASS / NEEDS WORK / FAIL

**Score: X/10**

• 通过：0 项 Critical 发现
• 需要改进：1–3 项 Critical 发现
• 失败：4 项或更多 Critical 发现

评分（0–10）

汇总所有发现后，给出 0 到 10 的总体评分：

• 10：完美——没有任何发现，Effect-TS 代码堪称典范
• 9：优秀——只有少量 Info 级建议
• 8：很好——有少量 Warning，没有 Critical
• 7：良好——有若干 Warning，但没有 Critical
• 6：尚可——有 1 项 Critical 或许多 Warning
• 5：需要改进——有 2–3 项 Critical
• 4：低于标准——有 4–5 项 Critical
• 3：较差——有 6 项或更多 Critical，或存在根本性模式违规
• 2：很差——大部分代码都忽略了 Effect 模式
• 1：基本符合——几乎没有遵循 Effect 模式
• 0：不符合——将完全不使用 Effect 的代码作为 Effect 代码提交

在报告末尾醒目地显示评分。

参考文件

包含针对代码库的详细示例的检查清单：

• references/effect-primitives.md — Effect Array、Match、Option、forEach、Schema、Layer
• references/branded-types.md — Branded 类型用法和已知类型列表
• references/otel-patterns.md — 追踪、Span 注解、结构化日志
• references/error-patterns.md — Schema.TaggedError、catchTag、错误上下文
• references/typescript-patterns.md — 不使用 as any、优先使用 satisfies 而非 as、不手动添加类型注解
• references/test-patterns.md — @effect/vitest、it.layer、覆盖率评估
• references/effect-atom-patterns.md — Effect-Atom React 模式、查询、变更、Result.builder