adversarial-zod

对抗式 Zod 门禁

用于 TypeScript 应用中 Zod schema 代码的货币性与正确性门禁——一个通过/失败门禁：由单个盲审子 Agent 按照本门禁规则并以对抗性立场评判工作，只有每条规则都为 PASS 或 N/A 时，工作才算通过。此技能只给出判定，绝不会修复工作。

规则以 zod 4.4.x 为准（自 [email protected] 起使用包根路径，2025 年 7 月），对于 start- 类别，则以 TanStack Start v1 RC 为准（当前使用 .validator()，.inputValidator() 已弃用）。

适用时机

• 即将合并的 diff 或功能定义或修改了 Zod schema，需要针对 Zod 4 的时效性给出客观的 PASS/FAIL，而非建议性反馈。
• Agent（Claude、Codex）编写了 schema 代码，你想独立检查它是否重复了 Zod 3 训练数据中的模式——已弃用的方法形式、已移除的参数或虚构的 z.interface()。
• Zod 3 → 4 迁移声称已完成，需要审计那些不易察觉的语义变更（.default() 短路、键为枚举的记录变为穷举式、z.coerce.boolean() 处理字符串标志）。
• TanStack Start 应用使用 Zod 验证服务端函数输入或搜索参数，并应采用不依赖适配器的 Standard Schema 模式。

不要用于 Zod 3 代码库（审查者提示词的前置条件会中止，并返回“GATE NOT APPLICABLE”），也不要用于用户想要解释和重构而非判定的情况——这属于经过整理的 zod 提炼技能的职责。在 TanStack 应用之外，两条 start- 规则为 N/A；其余门禁规则适用于任何使用 Zod 4 的 TypeScript 项目。

审查流程

严格遵循以下步骤——本门禁的价值在于确保每次审查都以相同方式运行。

1. 确定目标。 准确界定审查对象（diff、文件集或 PR），并记录 ref/路径，确保审查针对明确且固定的目标运行。目标路径始终包含 package.json——即使 diff 未涉及它，Zod 4 前置条件以及 pkg-、compose-native-json-schema 和 start- 适配器规则也由其中的依赖版本锁定信息决定。
2. 加载规则。 阅读 references/_sections.md 以及 references/ 中的每个规则文件（所有 sem-*.md、gone-*.md、err-*.md、dep-*.md、compose-*.md、start-*.md、pkg-*.md 文件）。
3. 编写审查者提示词。 将规则和目标填入 references/reviewer-prompt.md。组合后的提示词必须完全自包含——审查者看不到对话历史，因此不能引用提示词之外的上下文。
4. 派发一名盲审者。 启动单个 Task 子 Agent，其全部输入仅为组合后的提示词——不要附带对话上下文或其他评论。
5. 按失败关闭原则给出结果。 审查者的结构化输出就是判定结果——不进行合并步骤。只有每条规则都为 PASS 或 N/A 时，总判定才为 PASS；任何单条 FAIL 都会导致门禁失败。绝不取平均、权衡严重程度或豁免规则——“轻微”的 FAIL 仍然是 FAIL。如果审查者返回“GATE NOT APPLICABLE”（Zod 3 或未使用 Zod），则停止并报告该结果，而不是给出判定。
6. 呈现判定结果。 填写 assets/templates/verdict.md。若为 FAIL，将审查者给出的“通过所缺内容”建议汇总到修复清单中，每条都注明位置，并按类别重要性排序。每条最终结果为 FAIL 的规则都必须出现在修复清单中，并给出具体到可直接照做的修改——如果审查者的建议只是重述违规内容，则在呈现结果前依据规则中的 Correct 示例推导修复方案。

如果对未变更目标重复审查时，同一规则的判定反复变化，或者人工阅读证据后推翻了判定，这就说明规则存在可判定性缺陷——将其记录在 gotchas.md 中并完善规则；不要推翻门禁结果。

判定格式

审查者针对每条规则返回：PASS | FAIL | N/A、证据（file:line 或引文——PASS 和 FAIL 都必须提供），以及每个 FAIL 对应的修复方案：应用后可使该规则变为 PASS 的修改及其位置，不能只是重述违规内容。最终报告遵循 assets/templates/verdict.md。

规则类别

#	类别	前缀	涵盖内容
1	静默语义变更	sem-	对解析后的默认值使用 .prefault()、对稀疏枚举键使用 z.partialRecord()、对字符串标志使用 z.stringbool()
2	已移除的 API	gone-	.ip()/.cidr()、单参数 z.record()、错误参数三件套、.errors getter、函数工厂、虚构的 z.interface()
3	错误自定义与格式化	err-	使用统一的 error 参数替代 message、顶层 z.treeifyError/z.flattenError/z.prettifyError
4	已弃用的方法形式	dep-	顶层字符串格式、z.strictObject/z.looseObject、优先使用 .extend 而非 .merge、优先使用 z.enum 而非 z.nativeEnum、z.int()、不使用 z.promise()
5	组合、递归与编解码器	compose-	Getter 递归、使用 z.codec() 进行双向线格式转换、原生 z.toJSONSchema()
6	TanStack Start 集成	start-	将裸 schema 传给 .validator()、不使用适配器的 validateSearch
7	打包与导入	pkg-	根目录 "zod" 导入路径、仅在严格限制打包体积时使用 zod/mini

相关技能

• zod（精选）——面向教学的 Zod 用法精要；当目标是解释或重构，而非给出判定时使用。
• adversarial-tanstack——针对 TanStack Start 应用的框架级检查；对 Start 的差异同时运行这两项以全面覆盖（其 serverfn-validate-input 会检查是否存在 validator；本检查的 start- 规则则检查 validator 是否使用当前的 Zod 4 模式）。

参考文件

文件	描述
references/reviewer-prompt.md	供盲审查者使用的独立提示词模板
assets/templates/verdict.md	判定报告模板
references/_sections.md	类别定义与顺序
metadata.json	版本与来源参考