两项技能，帮助 AI 编码代理为存储数据或跨多个进程或机器运行的系统设计有意义的测试、运行这些测试并解释结果。
从产品承诺开始——例如“一旦保存成功，重启后数据仍然存在”——并将其转化为你的代理可以运行和检查的测试。将这些技能用于数据库、队列、工作流引擎以及可能因重试、并发请求或故障而丢失或重复数据的服务。在单台机器上运行的服务也能从中受益。
你不需要成为测试专家。描述该功能以及应始终保持为真的内容；设计技能会帮助选择测试并解释其重要性。
这些技能是 Markdown 指令、模板和参考资料。你的编码代理使用你项目的测试工具和运行时来遵循它们。此仓库不捆绑数据库测试运行器或现成的集群。
| 技能 | 输入 | 产出 |
|---|---|---|
| 设计测试 | 一个代码库以及你想要测试的变更或功能 | 一份计划，说明要测试什么、如何检查以及测试做到什么程度 |
| 执行测试 | 一份计划和测试环境 | 结果、支持性日志和数据、复现失败的步骤以及一份报告 |
你可以单独使用设计技能。执行是一个单独的步骤，它会读取已保存的计划，因此你可以在运行之前审查工作及其成本。
将以下内容粘贴到你的编码代理中：
Read https://raw.githubusercontent.com/shenli/distributed-system-testing/main/INSTALL.md
and follow the instructions to install or update
distributed-testing-skills for this agent.
安装指南使用位于
~/.local/share/distributed-testing-skills/ 的共享检出目录，并为你的 agent 配置指针或
符号链接。复用同一提示词即可更新。下方提示词中的显式路径也让你无需自动发现即可加载技能。
如果你选择了不同的位置，请替换为你的安装路径。
对于 Claude Code，该仓库还提供了插件安装选项：
/plugin marketplace add shenli/distributed-system-testing
/plugin install distributed-testing-skills@distributed-testing-skills
在你要测试的仓库中启动你的 agent。针对特定变更：
Use ~/.local/share/distributed-testing-skills/skills/designing-distributed-system-tests/SKILL.md
Design a test plan for the current branch's changes to adding log entries,
retrying failed requests, and recovering after a crash.
Reuse the existing tests and setup instructions.
Save the plan to docs/testing-plans/append-recovery.md.
将示例功能替换为你自己的功能。如需更全面的审查，请要求一份项目级计划并指明要包含的部分。该模式会审查现有测试并识别整个系统中缺失的覆盖范围，而不是针对单个变更。
审查正在检查的承诺、提议的测试、所需工具和运行时间。文档拼写错误或类似的低影响变更应获得轻量级的测试建议，而不是分布式测试计划。
Use ~/.local/share/distributed-testing-skills/skills/executing-distributed-system-tests/SKILL.md
Run the small initial checks (the smoke tier) from
docs/testing-plans/append-recovery.md against this project's local test
environment. Keep temporary test scripts and results under
./test-sessions/. Use default mode; do not modify project source files.
Report what ran, what failed, and what remains untested.
执行技能会发现现有工具，询问你的环境中有什么可用，然后验证各项要求。缺失的依赖或无效的模拟失败必须被报告出来，而不能被静默地计为成功的测试。先从小规模开始，然后再请求计划中定义的更长、更彻底的运行。
有关详细提示、自定义输出路径和作者模式，请参阅 USAGE.md。
在 Codex 中运行上面的安装提示。该指南会将共享检出目录中的两个技能文件夹链接到 ~/.agents/skills/，Codex 会在那里发现它们。若仅针对项目安装，请改用该项目的 .agents/skills/。这些位置和符号链接支持在官方 Codex 技能文档中有说明。
打开你想要测试的项目。在 Codex CLI 或 IDE 扩展中，使用 /skills 检查两个技能是否都出现，或输入 $ 选择一个。如果新安装的技能没有出现，请重启 Codex。你也可以使用快速开始中的显式文件路径提示。请参阅官方调用指南。
例如，让 Codex 设计一个计划：
$designing-distributed-system-tests
Design a test plan for this project's retry and recovery behavior.
I have Docker locally and can run disposable containers.
Start with normal operation, then simultaneous requests and restarts.
Save the plan to docs/testing-plans/retry-recovery.md.
审查完成后，运行初始测试：
$executing-distributed-system-tests
Run the smoke tier of docs/testing-plans/retry-recovery.md.
Use default mode and save results under ./test-sessions/.
Docker is available; use the project's documented container setup.
Report any missing tools or permissions and which tests they prevent.
安装技能提供的是指令，而不是 Docker、远程访问或测试集群。Codex 必须能够访问命令将要运行的环境。对于远程测试，请提供测试主机、你现有的连接方式以及项目的设置命令。如果无法访问，它仍然可以设计计划，但无法报告远程测试已运行。
使用能够回答你问题的最小配置。这些是供你根据应用进行调整的起点，而不是硬件要求或捆绑的部署方案。
| 目标 | 建议配置 | 它能告诉你什么 |
|---|---|---|
| 快速发现正确性缺陷 | 你的笔记本电脑、项目的运行时，以及可丢弃的本地进程或容器 | 在该配置下，请求、重试、事务和重启是否表现正确 |
| 比较不同版本之间的性能 | 一台安静、专用的测试机；在测量服务时，用另一台机器发送请求 | 在相同条件下，某项更改是否影响速度或资源使用 |
| 测试跨机器的故障 | 独立的测试主机或虚拟机，每台主机一个服务器实例，外加一个独立的测试控制器 | 系统如何处理某台服务器停止或服务器之间通信中断 |
从项目现有的设置说明开始。安装其所需的语言/运行时，如果它使用容器，则安装 Docker 或其他受支持的容器运行时。为每个实例分配各自的端口和数据目录或卷。使用专用的测试数据库，并采用可重复的方式重置其数据。
对于通过名称通信的容器，用户定义的 Docker 网络可以在它们之间提供名称解析。参见 Docker 网络。一台笔记本电脑上的多个容器有助于演练通信，但仍共享主机的资源和故障风险。它们并不能建立对丢失独立机器的韧性。
负载生成器是发送测试请求的程序。优先使用项目现有的基准测试工具；例如，PostgreSQL 的 pgbench 支持重复事务和自定义 SQL 脚本。选择与你的应用相似的请求和数据规模，而不是把工具的默认工作负载当作有代表性的。
告诉设计技能你的目标请求速率、数据规模、可接受的响应时间和可用机器。如果你还没有目标，请要求一份初始测量计划；不要从正在被评判的同一次运行中编造通过阈值。
使用应用程序支持的集群规模。对于支持三个投票副本的服务，起始布局是三台服务器主机加上一个发送请求并收集结果的控制器。三节点多数需要两票，因此这种布局可以演练丢失一个投票者的情况；其他架构需要不同的布局。同一台物理主机上的独立虚拟机仍然无法测试物理主机丢失的情况。
运行测试之前：
从正常流量开始，然后进行一次服务器重启，再在请求持续进行时断开一条连接。测试成功恢复和数据正确性两方面。更大的集群、跨区域布局和存储故障应按照你实际需要测试的保证来进行。
给 Codex 一个具体的环境描述，例如：
$designing-distributed-system-tests
Design a plan for this project's three-replica test cluster.
Available: Linux test hosts test-a, test-b, test-c, plus test-controller.
The controller has SSH access and can reach the application ports.
Use our existing setup and reset commands in docs/testing.md.
Cover normal operation, one server restart, and one interrupted network link.
Record how each failure is verified and how the environment is restored.
Save the plan to docs/testing-plans/three-replica-recovery.md.
将这些示例主机和文件路径替换为你自己的。对于性能相关工作， 使用相同的模式，配合你的基准测试命令、机器详情、工作负载 和性能目标。将命令、版本、结果和重置说明 放在一起，以便其他开发者可以重复运行。
该工作流将产品承诺与可观察的结果联系起来：
对于涉及并发请求的测试，事件发生的顺序可能与 最终数据同样重要。代理会记录每个客户端尝试了什么、何时 发生以及返回了什么。超时是一种未知结果：服务器可能 已经完成了请求，即使客户端从未收到其响应。
| 术语 | 通俗含义 |
|---|---|
| SUT（被测系统） | 正在测试的应用程序、服务或数据库 |
| 声明 | 系统做出的承诺，例如在重启后保留数据 |
| 场景 | 一次测试设置：要发送的请求、要创建的条件以及要检查的结果 |
| 检查器或判定器 | 决定观察到的结果是否正确的代码 |
| 测试框架 | 用于设置和运行测试的脚本及支持代码 |
| 操作历史 | 请求、响应及其时间记录 |
| 故障注入；nemesis | 故意制造故障；制造故障的工具 |
| 预算 | 要执行多少测试：运行时间、请求数量、重复次数和配置 |
| 判定 | 记录的结果：通过、失败、未完成或未运行 |
假设你的服务向日志中添加条目且从不删除它们。每个请求 都包含一个幂等键：在重试同一请求时复用的标识符， 以便服务器能够识别它。该服务承诺：
一个聚焦的计划可以包含以下场景：
| 场景 | 它试图暴露的问题 | 证据与检查 |
|---|---|---|
| 同时从两个客户端发送相同请求 | 两个调用方都创建了条目 | 为两个请求提供相同的键，并检查创建的条目不超过一条 |
| 中断响应，然后重试 | 客户端重复了服务器已完成的请求 | 记录中断并重试；检查是否有重复，而不要假设第一个请求失败了 |
| 成功请求后重启 | 已保存的条目消失 | 记录哪些请求成功，并检查其条目在重启后是否仍然存在 |
真实计划还规定了测试文件、请求数量、运行时间、清理工作，以及检查结果所需的数据。承受断电需要单独的测试：停止进程可能会将数据留在操作系统内存中，如果机器断电，这些数据就会消失。
重启后成功的健康检查只能说明服务有响应。它并不能确立上述两项保证中的任何一项；记录的操作和状态检查才能完成这项工作。