effect-review-v4

Effect v4 评审

评审程序行为及其公开的契约。如果 Effect 原语能消除自定义的取消、调度、资源管理或协调逻辑，优先使用它们。说明其语义优势；Effect API 的数量并不能衡量代码质量。

除非用户也要求修复，否则请以只读方式使用此技能。用户要求评审或改进此技能本身时，请检查其说明和示例；不要启动产品代码审计。

默认只使用一名评审者：当前 Agent，不使用子 Agent，包括整个仓库的审计。遵循第 3 节中的委派和上下文限制。

1. 确定范围和事实依据

在提出发现之前，请阅读 version-grounding.md 和适用的仓库说明。

• 遵循明确指定的文件／目录、PR、分支和先前对话。“我的更改”通常指存在时的工作区更改；否则检查当前分支实际的基准。说明推断出的范围。只有在尚未解决的歧义会实质性影响评审时才提问。
• PR／分支：确定实际基准，检查其合并基点差异及相关调用方。工作区更改：纳入已暂存、未暂存和相关未跟踪文件。差异为空不代表命令失败。绝不要默默地评审 HEAD~1。
• 仓库：先找出第一方源码，排除生成内容／依赖／参考目录。.context 是 API 证据，不属于待评审的产品代码。
• 按内容和归属分类，而不只看扩展名。index.ts、配置、.tsx、.spec.* 和类型测试都可能包含重要的 Effect 行为。沿着契约检查间接使用方和运行时适配器。
• 确认实际解析的包和补丁。技能示例只能作为其测试版本的证据，不能作为不同已安装版本的权威依据。

可选的只读清单辅助工具（请提供实际路径）：

node <skill>/scripts/inspect-project.mjs --project <repo> --mode working
node <skill>/scripts/inspect-project.mjs --project <repo> --mode diff --base <actual-base>
node <skill>/scripts/inspect-project.mjs --project <repo> --mode repo

此辅助工具会列出候选项和排除项；它不能证明语义评审已覆盖完整，也不会替你找出 PR 基准。将范围缩小到用户要求的路径，并阅读相关的非源码契约。

2. 评审关联行为

阅读 known-pitfalls.md，了解哪些情况会使先前提出的修复不安全。然后沿相关路径检查：

输入 → schema → 服务 → 驱动程序／资源 → 错误映射 → 使用方 → 测试。

在提出风格改进之前，先对涉及 Effect 的工作进行错误处理和生命周期检查。若涉及其他参考资料中的问题，请加载相应资料：

关注点	参考资料
预期失败、缺陷、中断、恢复、公开契约	errors-and-cause.md
资源作用域、fiber、取消、状态、背压	resources-concurrency.md
原语选择；HTTP、重试、缓存、轮询、数据转换	primitives.md
延迟构造、生成器、追踪、Promise 互操作	effect-fn-and-gen.md
依赖、layer 获取／记忆化、配置	services-layers.md
解码／构造／编码、可选性、品牌	schema.md
追踪／日志／指标上下文、状态、导出生命周期	observability.md
Atom 身份、运行时所有权、异步状态、失效	effect-atom.md
行为断言、时钟、layer、类型化失败	test-patterns.md

对于每种自定义机制，都要考虑现有的 Effect 原语或仓库抽象。提出建议前，请检查 API 是否可用、生命周期、失败／取消语义、性能以及受影响的调用方。简短的组合器链、局部变量、穷尽式 switch 和原生边界适配器，可能就是最清晰且正确的实现。

3. 默认由一个 Agent 进行审查

委派预算：默认零个；仅当用户明确要求并行或由独立 Agent 审查时，最多可使用两个子 Agent。 仓库规模、文件数量、可用名额或彻底审计的请求都不构成委派授权。不要例行询问是否添加 Agent；继续在本地审查。用户明确要求更多 Agent 时，可突破此限制，但须遵守宿主规则。用户或宿主设定的较低限制始终优先。

• 上限适用于整个审查，而非并行 Agent 数量或每一轮的数量。计算每位受委派的独立审查者，包括重复使用的审查者。不要因其他问题、阶段、重试或验证而重置预算。
• 不得递归委派。每位受委派的审查者都必须独立工作。不要按文件、问题、发现或分片与问题的组合逐一创建 Agent。
• 仅委派范围明确、与主要审查不重复的独立工作。分配不同子系统，或在用户要求独立核查时分配某个具体的未解决主张。整合和最终验证由主要审查者负责；不要自动安排第二组验证者。
• 提供简洁的任务说明，列明分配的路径、已确认的版本或补丁、适用规范、相关参考路径及预期结果。避免在每个提示中复制完整对话、整套技能或参考资料、差异或整个仓库。若支持，请选择隔离或无历史上下文；简短提示本身并不能阻止宿主继承完整对话。审查者可以查看分配范围以外的调用方，作为证据。
• 要求报告已确认的发现、必要证据及重要的覆盖缺口；报告通常不超过 600 字。长篇复现内容请使用文件引用；不要重复粘贴源代码或逐一叙述检查过的每个文件。
• 预算用尽或审查者未能完成时，在本地完成剩余工作。仅为具体的缺失检查重用现有审查者；不要重新开始已完成的审查，也不要添加替补 Agent 来规避上限。

对关联路径一次性审查，并一并处理相关问题。将已确认的版本或策略证据简要记录下来；仅加载相关参考资料部分。大型审计应维护简洁的覆盖记录，并按顺序继续，除非出现新证据，否则不要重读已完成的部分。 保留要求的覆盖范围和重要验证；报告任何实际遗漏。不要假设特定工具、模型或令牌计量功能可用，也不要在没有测量的情况下声称节省了令牌。

4. 验证并报告

遵循 review-protocol.md。每项拟议的 API（包括可选建议）都需要与版本匹配的证据。重要发现必须有具体触发条件、正向支持证据，并经过反证尝试。

将以下三类输出分开：

• 正确性： 可观察到的故障、丢失的保证或已证实的成本。
• 仓库策略： 适用的本地要求，并注明其来源。
• 可选简化： 在行为不变的前提下使用更清晰的基本用法；绝不能仅因语法不同就作为阻塞性缺陷。

注释是意图的证据，但不能使代码免于审查。不安全的拟议修复不能推翻真实漏洞。将未解决的主张列入开放问题，而非降级为已确认发现。若缺少执行结果或源码证据，应保留不确定性。

按影响从高到低报告已确认的发现，并注明位置、触发条件、影响、规则、证据、修复方向或风险，以及验证情况。包括审查范围、覆盖情况和已执行的检查。可选改进应简明列出并单独说明。如果没有发现已确认的缺陷，应明确说明，并列出重要的覆盖限制。省略空类别章节、数值化合规评分和文件排名。

维护此技能

完整的 TypeScript 示例位于 examples/README.md 和相邻的源文件中；不要将它们重复放入未经检查的 GOOD 代码块中。 这些示例包含负向对照测试，用于证明不安全模式为何会失败。使用 Node 和项目已安装的依赖项运行 scripts/check-examples.mjs --project <repo>；它不会安装或升级软件包。

当 API／运行时指南或依赖项发生变化时，请验证受影响的源文件和补丁，并运行受影响的示例。对于仅涉及说明的更改，请检查元数据、 链接和一致性；不要自动启动 Agent 或运行完整基准测试。 如需比较评审行为，请使用 evals/evals.json，并确保总委派预算相同。 常规代码评审不会运行此技能的维护评估。 请参阅 evals/README.md。请将快照／结果保存在所有技能发现根目录之外，例如 ~/.agents/skill-workspaces/effect-review-v4。 ~/.agents/skills 下包含 SKILL.md 的备份可能会被发现为另一个已安装技能，即使它位于此技能自身目录之外。