antithesis-research

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Antithesis Research

Antithesis 研究

Purpose and Goal

目的与目标

Research a target system and produce scratchbook artifacts that unblock the rest of the workflow. Success means:

```
antithesis/scratchbook/sut-analysis.md
```
captures architecture, state, concurrency, and failure-prone areas
```
antithesis/scratchbook/property-catalog.md
```
lists concrete, testable properties with priorities
```
antithesis/scratchbook/deployment-topology.md
```
describes the minimal useful container topology
```
antithesis/scratchbook/properties/{slug}.md
```
captures per-property evidence trails and context
```
antithesis/scratchbook/property-relationships.md
```
maps suspected clusters and connections between properties

研究目标系统并生成研究笔记类产物，为后续工作流扫清障碍。成功完成的标志包括：

```
antithesis/scratchbook/sut-analysis.md
```
记录架构、状态、并发机制及易故障区域

antithesis/scratchbook/property-catalog.md

列出具体的可测试特性及优先级

antithesis/scratchbook/deployment-topology.md

描述最小可用容器拓扑结构

```
antithesis/scratchbook/properties/{slug}.md
```
记录每个特性的证据链及相关上下文

antithesis/scratchbook/property-relationships.md

梳理特性间的疑似关联与聚类情况

Prerequisites and Scoping

前置条件与范围界定

Start from the repo, checked-in docs, and existing scratchbook files first. Ask the user only for blockers or scoping decisions you cannot infer safely, such as:

The repo or codebase location, if it is not already clear
Which subsystem or component matters most, if the work is narrower than the whole repo
Known incidents, closed bugs, or specific failure modes worth targeting
External documentation, issue trackers, or design docs not present in the repo

If scratchbook artifacts already exist, treat them as inputs and extend them instead of rewriting them unless the user asks for a fresh pass.

首先从代码仓库、已提交的文档及现有研究笔记文件入手。仅在无法安全推断的情况下向用户询问阻塞问题或范围界定决策，例如：

若代码仓库或代码库位置不明确，需询问具体位置
若工作范围小于整个代码库，需询问最关键的子系统或组件
需询问已知事件、已修复的Bug或值得重点关注的特定故障模式
需询问代码库中未包含的外部文档、问题追踪器或设计文档

如果研究笔记类产物已存在，除非用户要求重新生成，否则应将其作为输入进行扩展而非重写。

Definitions and Concepts

定义与概念

SUT: System under test.
Workload: A synthetic workload designed to exercise the target system
Safety property (correctness): A bad thing never happens
Liveness property (progress): A good thing eventually happens
Reachability property: A code path or behavior is reachable or unreachable
Test Template: A directory of Test Commands located at
```
/opt/antithesis/test/v1/{name}/
```
. There may be more than one test template. Each timeline executes commands from a single Test Template. Files or subdirectories prefixed with
```
helper_
```
are ignored by Test Composer.
Test Command: An executable file in a Test Template with a valid prefix. Valid prefixes:
```
parallel_driver_
```
,
```
singleton_driver_
```
,
```
serial_driver_
```
,
```
first_
```
,
```
eventually_
```
,
```
finally_
```
,
```
anytime_
```
Timeline: A single linear execution of the target system and workload. Antithesis runs many timelines in parallel and branches them to search for interesting behaviors.

SUT: 被测系统
Workload: 为测试目标系统设计的合成工作负载
Safety property (correctness): 安全特性（正确性）：不良情况绝不会发生
Liveness property (progress): 活性特性（进展性）：良好情况最终会发生
Reachability property: 可达性特性：某一代码路径或行为可被触发或无法被触发
Test Template: 测试模板：位于
```
/opt/antithesis/test/v1/{name}/
```
的测试命令目录，可存在多个测试模板。每个时间线会执行单个测试模板中的命令。前缀为
```
helper_
```
的文件或子目录会被Test Composer忽略。
Test Command: 测试命令：测试模板中带有有效前缀的可执行文件。有效前缀包括：
```
parallel_driver_
```
,
```
singleton_driver_
```
,
```
serial_driver_
```
,
```
first_
```
,
```
eventually_
```
,
```
finally_
```
,
```
anytime_
```
Timeline: 时间线：目标系统与工作负载的单次线性执行流程。Antithesis会并行运行多条时间线并进行分支，以探寻有价值的行为。

Documentation Grounding

文档参考

Use the

antithesis-documentation

skill to ground Antithesis-specific terminology and implementation advice.

Properties and assertions:

https://antithesis.com/docs/properties_assertions/assertions.md

Sometimes assertions:

https://antithesis.com/docs/best_practices/sometimes_assertions/

Define test properties:

https://antithesis.com/docs/using_antithesis/sdk/define_test_properties/

SDK runtime modes and production behavior:

https://antithesis.com/docs/using_antithesis/sdk/

Optimize for testing:

https://antithesis.com/docs/best_practices/optimizing.md

使用

antithesis-documentation

技能来获取Antithesis专属术语的定义及实施建议。

特性与断言：

https://antithesis.com/docs/properties_assertions/assertions.md

有时断言：

https://antithesis.com/docs/best_practices/sometimes_assertions/

定义测试特性：

https://antithesis.com/docs/using_antithesis/sdk/define_test_properties/

SDK运行时模式与生产环境行为：

https://antithesis.com/docs/using_antithesis/sdk/

测试优化：

https://antithesis.com/docs/best_practices/optimizing.md

Reference Files

参考文件

Reference	When to read
`references/scratchbook-setup.md`	Always — read first to initialize the workspace
`references/sut-discovery.md`	Discovering system characteristics through structured attention focuses
`references/sut-analysis.md`	General methodology for analyzing the codebase and understanding components
`references/property-discovery.md`	Discovering properties through structured attention focuses
`references/property-catalog.md`	Format and methodology for documenting properties
`references/deployment-topology.md`	Designing the container topology for Antithesis

参考文件	阅读时机
`references/scratchbook-setup.md`	必读 — 首先阅读以初始化工作区
`references/sut-discovery.md`	通过结构化分析探寻系统特性时阅读
`references/sut-analysis.md`	分析代码库、理解组件的通用方法指南
`references/property-discovery.md`	通过结构化分析探寻测试特性时阅读
`references/property-catalog.md`	记录测试特性的格式与方法指南
`references/deployment-topology.md`	为Antithesis设计容器拓扑结构时阅读

Recommended Workflows

General Guidance

通用指导原则

Prefer specific, checkable guarantees over vague goals like "test failover"
If the system claims a guarantee in docs, comments, or issues, try to make it a property
Record not just the invariant, but why the chosen Antithesis assertion type is the right semantic fit for that property
Use
```
Sometimes(cond)
```
for liveness or non-trivial semantic states, not for invariants that must hold on every evaluation and not as a substitute for
```
Reachable(...)
```
Identify where surgical SUT-side assertions would give materially better search guidance than workload-only checks, especially for rare, dangerous, timing-sensitive, or externally invisible states
Remember that Antithesis SDK assertions do not crash the program on failure; they are intended to be safe in production code and usually become low-overhead fallbacks or no-ops outside Antithesis
Focus on timing-sensitive, concurrency-sensitive, and partial-failure scenarios where Antithesis is strongest
Keep the deployment topology minimal; every extra container expands state space
Write down assumptions and open questions in the scratchbook instead of keeping them implicit
If only part of the research is requested, still update the relevant scratchbook files and note what remains undone

优先选择具体、可验证的保障机制，而非“测试故障转移”这类模糊目标
若系统在文档、注释或问题记录中宣称了某一保障机制，尝试将其转化为测试特性
不仅要记录不变量，还要说明为何选择的Antithesis断言类型与该特性在语义上匹配
对于活性特性或非平凡语义状态，使用
```
Sometimes(cond)
```
，不要将其用于必须在每次评估时都成立的不变量，也不要用它替代
```
Reachable(...)
```
确定在SUT侧添加精准断言的位置，这相比仅通过工作负载检查能提供更有效的搜索引导，尤其是针对罕见、危险、对时序敏感或外部不可见的状态
请记住，Antithesis SDK断言在失败时不会导致程序崩溃；它们被设计为可安全用于生产代码，通常在Antithesis环境外会成为低开销的降级逻辑或空操作
重点关注Antithesis最擅长的场景：对时序敏感、对并发敏感及部分故障场景
保持部署拓扑结构最简；每增加一个容器都会扩大状态空间
将假设与待解决问题记录在研究笔记中，而非隐而不宣
若仅需完成部分研究工作，仍需更新相关研究笔记文件，并标注未完成的部分

Output

输出产物

```
antithesis/scratchbook/sut-analysis.md
```

antithesis/scratchbook/property-catalog.md

antithesis/scratchbook/deployment-topology.md

antithesis/scratchbook/property-relationships.md

antithesis/scratchbook/properties/{slug}.md

(one per cataloged property)

These outputs should be concrete enough for the

antithesis-setup

skill and the

antithesis-workload

skill to use directly.

```
antithesis/scratchbook/sut-analysis.md
```

antithesis/scratchbook/property-catalog.md

antithesis/scratchbook/deployment-topology.md

antithesis/scratchbook/property-relationships.md

```
antithesis/scratchbook/properties/{slug}.md
```
（每个已记录的特性对应一个文件）

这些输出产物需足够具体，以便

antithesis-setup

技能与

antithesis-workload

技能直接使用。

Self-Review

自我检查

Before declaring this skill complete, review your work against the criteria below. If your agent supports spawning sub-agents, create a new agent with fresh context to perform this review — give it the path to this skill file and have it read all output artifacts. A fresh-context reviewer catches blind spots that in-context review misses. If your agent does not support sub-agents, perform the review yourself: re-read the success criteria at the top of this file, then systematically check each item below against your actual output.

Review criteria:

```
antithesis/scratchbook/sut-analysis.md
```
exists and covers architecture, state management, concurrency model, and failure-prone areas
```
antithesis/scratchbook/property-catalog.md
```
exists, has provenance frontmatter (
```
commit
```
and
```
updated
```
), and lists concrete, testable properties — not vague goals like "test failover"
Each property has a descriptive kebab-case slug as its canonical ID
Each property has a priority and a rationale for its chosen Antithesis assertion type (
```
Always
```
,
```
Sometimes
```
,
```
Reachable
```
, etc.)
Properties that need internal branch guidance or replay anchors call out likely SUT-side instrumentation points, not just workload-visible checks
```
antithesis/scratchbook/deployment-topology.md
```
exists and describes a minimal container topology — every container is justified
Every cataloged property has a corresponding evidence file at
```
antithesis/scratchbook/properties/{slug}.md
```
that captures the evidence trail, relevant code paths, and key observations
Open questions in evidence files have been investigated and resolved — no unresolved questions remain in evidence files for active properties
Properties invalidated by investigation are marked in the catalog with the reason
```
antithesis/scratchbook/property-relationships.md
```
exists and groups related properties into clusters with brief notes on suspected connections and dominance
Every property slug referenced in
```
property-relationships.md
```
corresponds to a property in the catalog
Properties focus on timing-sensitive, concurrency-sensitive, and partial-failure scenarios where Antithesis is strongest
Claimed guarantees from docs, comments, or issues are represented as properties
The outputs are concrete enough for
```
antithesis-setup
```
and
```
antithesis-workload
```
to use directly — no ambiguous steps or missing details

在宣告本技能执行完成前，请对照以下标准检查工作成果。若你的Agent支持生成子Agent，可创建一个带有全新上下文的新Agent来执行此项检查——向其提供本技能文件的路径，并让它阅读所有输出产物。全新上下文的审核者能发现上下文内检查容易遗漏的盲点。若你的Agent不支持生成子Agent，请自行执行检查：重新阅读本文档顶部的成功标准，然后系统地对照实际输出检查以下每一项。

检查标准：

```
antithesis/scratchbook/sut-analysis.md
```
已生成，且涵盖架构、状态管理、并发模型及易故障区域
```
antithesis/scratchbook/property-catalog.md
```
已生成，包含来源前置信息（
```
commit
```
与
```
updated
```
），且列出了具体的可测试特性——而非“测试故障转移”这类模糊目标
每个特性都有一个描述性的短横线分隔式（kebab-case）别名作为其标准ID
每个特性都有优先级，且说明了选择对应Antithesis断言类型（
```
Always
```
、
```
Sometimes
```
、
```
Reachable
```
等）的理由
需要内部分支引导或重放锚点的特性，需明确指出可能的SUT侧 instrumentation 点，而非仅依赖工作负载可见的检查
```
antithesis/scratchbook/deployment-topology.md
```
已生成，且描述了最简容器拓扑结构——每个容器的存在都有合理依据
每个已记录的特性都在
```
antithesis/scratchbook/properties/{slug}.md
```
有对应的证据文件，记录了证据链、相关代码路径及关键观察结果
证据文件中的待解决问题已被调查并解决——活跃特性的证据文件中无未解决问题
经调查被验证无效的特性已在目录中标注原因
```
antithesis/scratchbook/property-relationships.md
```
已生成，将相关特性分组为聚类，并简要说明疑似关联与主导关系
```
property-relationships.md
```
中引用的所有特性别名都与目录中的特性对应
特性重点关注Antithesis最擅长的场景：对时序敏感、对并发敏感及部分故障场景
文档、注释或问题记录中宣称的保障机制已转化为测试特性
输出产物足够具体，可供
```
antithesis-setup
```
与
```
antithesis-workload
```
直接使用——无模糊步骤或缺失细节