用 Antithesis 做代码库测试研究：映射系统…

在需要为某个代码库规划 Antithesis 测试（工作负载与环境）之前，先做一次系统研究并产出 scratchbook 工件。

适用场景

解决思路

1. 每次研究开始时先询问用户是否有外部参考资料（文档、设计笔记、相关仓库、issue tracker 等），并原样记录回答；每个外部引用记录为 path（或 URL）加简短 why 说明。
2. 把外部引用列表贯穿整个研究过程，作为输入传给所有产出顶层工# 件的参考工作流：sut-discovery.md、sut-analysis.md、property-discovery.md、deployment-topology.md、property-evaluation.md，并写入每个顶层工件的 provenance frontmatter；任何收到外部引用的 agent 都把它当作待验证的线索而非事实。
3. 除范围问题外，只询问无法安全推断的阻塞项或范围决策：仓库/代码库位置、最关注的子系统或组件、已知事故/已关闭 bug/值得针对的失败模式。
4. 如果 scratchbook 工件已存在，把它们当作输入进行扩展，除非用户要求重新做一遍，否则不要重写。
5. 先读 references/scratchbook-setup.md 初始化工作区。
6. 读 references/sut-discovery.md 和 references/sut-analysis.md，并按其中的 ensemble 或单 agent 工作流分析系统。
7. 扫描代码库中已有的 Antithesis SDK 断言：搜索 Antithesis SDK 的 import 以及断言函数调用（assert_always!、assert_sometimes!、assert_reachable!、assert_unreachable! 或其非宏等价物）；对每个断言记录文件路径、行号、断言类型和消息字符串，写入 antithesis/scratchbook/existing-assertions.md，并按 references/scratchbook-setup.md 在文件开头加 provenance frontmatter；若未找到断言，也要写文件说明代码库没有现有插桩。
8. 读 references/property-discovery.md 和 references/property-catalog.md，并按其中的 ensemble 或单 agent 工作流发现属性。
9. 读 references/deployment-topology.md，设计部署拓扑并写入 antithesis/scratchbook/deployment-topology.md。
10. 读 references/property-evaluation.md，并按其中的 ensemble 或单 agent 工作流评估属性目录。
11. 处理评估发现：应用改进、填补缺口、把偏差上报给用户。
12. 把所有剩余发现写入或更新到 antithesis/scratchbook/ 下的 scratchbook。
13. 做定向属性研究时：若系统模型缺失或过时，先读 references/sut-discovery.md 和 references/sut-analysis.md；再读 references/property-discovery.md 和 references/property-catalog.md；按 property-discovery 的工作流发现属性。
14. 把声称的保证转成显式属性；对事故和 bug 报告，在将其变成属性前先确认所报缺陷是真实的系统缺陷（见 references/validating-claims.md）；为每个属性选择匹配的 Antithesis 断言类型。
15. 更新 antithesis/scratchbook/property-catalog.md 并记录假设或未决问题；把新属性的证据文件写入 antithesis/scratchbook/properties/{slug}.md；用新的聚类或连接更新 antithesis/scratchbook/property-relationships.md。
16. 读 references/property-evaluation.md，按其中的工作流评估更新后的属性目录，并处理评估发现：应用改进、填补缺口、把偏差上报给用户。
17. 做属性扩展（triage 之后）时：读 references/property-discovery.md 和 references/property-catalog.md；查看 antithesis-triage skill 的 triage 发现；用 property-discovery 中的 attention focuses 寻找受 triage 发现启发的新属性。
18. 更新 scratchbook 中相关文件；把新属性的证据文件写入 antithesis/scratchbook/properties/{slug}.md；用新的聚类或连接更新 antithesis/scratchbook/property-relationships.md。
19. 若扩展规模较大（新属性类别或超过 3 个新属性），读 references/property-evaluation.md 并评估更新后的目录；现有类别中 1-3 个属性的小扩展不需要完整评估。
20. 优先选择具体、可检查的保证，而不是“测试 failover”这类模糊目标。
21. 如果系统文档或注释声称某个保证，就把它做成要测试的属性——属性用于验证该声称；不要在分析中把该保证写成已成立的事实。
22. issue 中的 bug 报告是线索而非事实；在基于它构建任何东西之前，先确认所报缺陷是真实的系统缺陷（见 references/validating-claims.md）。
23. 不仅记录不变量，还要记录为什么所选的 Antithesis 断言类型在语义上最匹配该属性。
24. 对活性或非平凡语义状态使用 Sometimes(cond)，不要用于每次求值都必须成立的不变量，也不要作为 Reachable(...) 的替代。
25. 识别在哪些地方做外科手术式的 SUT 侧断言能比仅靠工作负载检查提供实质更好的搜索引导，尤其是罕见、危险、时序敏感或外部不可见的状态。
26. 记住 Antithesis SDK 断言失败时不会让程序崩溃；它们被设计为在生产代码中安全，在 Antithesis 之外通常变成低开销回退或 no-op。
27. 聚焦时序敏感、并发敏感和部分失败场景，这些是 Antithesis 最擅长的。
28. 保持部署拓扑最小化；每多一个容器都会扩大状态空间。
29. 把假设和未决问题写进 scratchbook，而不是让它们保持隐含。
30. 如果只要求做部分研究，仍要更新相关 scratchbook 文件并注明还有哪些未完成。
31. 产出以下文件：antithesis/scratchbook/sut-analysis.md、antithesis/scratchbook/existing-assertions.md、antithesis/scratchbook/property-catalog.md、antithesis/scratchbook/deployment-topology.md、antithesis/scratchbook/property-relationships.md、antithesis/scratchbook/properties/{slug}.md（每个目录属性一个）、antithesis/scratchbook/evaluation/synthesis.md、antithesis/scratchbook/evaluation/{lens}.md（每个评估 lens 一个）。
32. 所有顶层 scratchbook 工件（除每属性证据文件外的上述列表）都要包含 provenance frontmatter，记录 sut_path、commit、updated 和 external_references；每属性证据文件从 property-catalog.md 继承上下文，不需要自己的 frontmatter（见 references/scratchbook-setup.md）。
33. 这些产出要足够具体，能被 antithesis-setup skill 和 antithesis-workload skill 直接使用。
34. 声明完成前按自检标准复核：sut-analysis.md 存在且覆盖架构、状态管理、并发模型和易失败区域；existing-assertions.md 存在且列出所有找到的 Antithesis SDK 断言（或明确说明没有找到）。
35. 证据文件要正确区分代码库中已存在的插桩、部分存在的插桩和缺失的插桩——不要建议添加已经存在的断言。
36. property-catalog.md 存在、有 provenance frontmatter，并列出具体可测属性而非“测试 failover”这类模糊目标；每个顶层工件都以 provenance frontmatter 开头。
37. external_references 列表反映用户声明的范围回答；被引用的条目要有 why 说明其用途。
38. 范围问题在研究开始时被询问，且用户的回答被传给每个执行分析的子 agent。
39. 每个属性都有描述性的 kebab-case slug 作为规范 ID；每个属性都有优先级以及所选 Antithesis 断言类型（Always、Sometimes、Reachable 等）的理由。
40. 需要内部分支引导或重放锚点的属性要指出可能的 SUT 侧插桩点，而不仅是工作负载可见的检查。
41. deployment-topology.md 存在并描述最小容器拓扑——每个容器都有理由。
42. 每个目录属性都有对应的证据文件 antithesis/scratchbook/properties/{slug}.md，记录证据链、相关代码路径和关键观察。
43. 每个属性的目录条目包含 Open Questions 列表，镜像其证据文件中的未决问题（简短摘要；完整上下文留在证据文件）。已解决的问题移除；剩余问题按 references/property-catalog.md 的“Open Questions Conventions”打标签。
44. 每个 (partial: ...) 或 (needs human input) 标签都要有证据文件中的 investigation log 条目支撑（见 references/property-catalog.md 的“Investigation Log”），记录检查了什么、发现了什么、没发现什么；未打标签（尚未调查）的问题不需要 log 条目；需要人工输入的未决问题是可接受的结果——必须出现在目录概览中，而不是埋在证据文件里。
45. 被调查证伪的属性要在目录中标注原因。
46. property-relationships.md 存在，把相关属性分组为聚类，并简要说明疑似连接和支配关系；其中引用的每个属性 slug 都对应目录中的一个属性。
47. 属性聚焦时序敏感、并发敏感和部分失败场景，这些是 Antithesis 最擅长的。
48. 来自文档或注释的声称保证被表示为要测试的属性，分析中不把任何保证陈述为既定事实。
49. 任何关于特定缺陷存在的陈述，若取自 bug 报告，都要引用证明该缺陷真实且排除报告者环境或配置的一手证据——而不只是 issue 链接或症状匹配。
50. 已执行属性评估：antithesis/scratchbook/evaluation/synthesis.md 存在且有分类发现；评估改进已应用到目录；评估缺口已通过定向发现填补，产生的属性在目录中并有证据文件；评估偏差（如有）已连同支持证据呈现给用户。
51. 产出足够具体，能被 antithesis-setup 和 antithesis-workload 直接使用——没有模糊步骤或缺失细节。
52. 若 agent 支持生成子 agent，则创建一个全新上下文的 agent 执行自检：给它本 skill 文件路径并让它读取所有产出工件；若不支持子 agent，则自行复核：重读本文件顶部的成功标准，然后对照实际产出逐项检查上述标准。

适用边界 · 注意事项

• 不适用于非 Antithesis 测试规划场景（该技能依赖 Antithesis SDK、scratchbook 结构及相关参考文件）。
• 当用户只想要快速修复而不需要系统研究或属性目录时，不必执行完整研究流程。
• 当 scratchbook 工件已存在且用户未要求重做时，不要重写，应作为输入扩展。