momentic-spec

Momentic 规范驱动开发

在实现之前，先将预期的产品行为编写为 Momentic 测试。 测试定义契约；不要让测试迁就实现。

不可妥协的流程

1. 阅读仓库指南、momentic.config.yaml 以及附近的测试和模块。
2. 找出并报告预计受影响的确切 Momentic 测试。
3. 在更改产品代码之前，先创建或修改这些测试。
4. 将测试差异作为产品规范进行审查。
5. 只有完成上述步骤后，才能实现产品变更。
6. 实现过程中使用快速的代码级检查；不要每次编辑或提交后都运行 Momentic。
7. 在可靠的端到端检查点，准备好所需的测试状态，启用现在应该通过的受影响测试，并询问是否运行最小的受影响测试集。

在预期的测试规范写入磁盘之前，不要开始实现产品功能。如果用户更改了需求，请先再次更新规范。

选择受影响的测试

• 如果用户点名了特定的现有测试，请从这些测试开始，并将工作范围限定在这些测试上。只有仓库证据表明另一个测试或共享模块会直接受到影响时，才扩大范围。
• 对于新的用户可见功能，创建能描述新用户流程的最少数量的新测试。
• 对于功能变更，更新描述旧行为的现有测试，而不是添加重复覆盖。
• 充分追踪共享组件和模块，以找出实际的行为影响。不要仅根据文件名推断受影响范围。
• 如果没有 Momentic 测试受到影响，请在更改产品代码之前说明原因。不要为了制造测试差异而进行表面性的测试修改。

编辑产品代码之前，报告每个受影响的测试路径，并说明该测试将被新增、修改还是保持不变。

先编写产品规范

实现前的测试应描述所请求的结果，即使当前产品暂时无法满足该结果。

• 保留无关的设置、清理、数据、断言和测试意图。
• 不要削弱断言，也不要仅仅因为旧行为符合当前实现而保留旧行为。
• 如果实现或所需依赖尚未就绪，且测试目前预期无法通过，请将测试标记为 disabled: true。说明禁用原因以及启用前必须满足的条件。
• 不要仅仅因为本地凭据或可运行的环境不可用就使用 disabled: true。这属于验证限制，不一定代表产品预期会失败。
• 将改动范围控制在最小。一个变更的产品契约通常应对应一个聚焦的测试差异。

编写测试后，总结预期失败或禁用的行为，并确认测试表达了用户的需求，然后再开始实现。

遵循代码库的测试语言

阅读附近的测试并遵循其既定惯例，包括目录位置、命名、模块、设置、数据，以及对 AI 检查、页面检查或元素检查的偏好。如果代码库没有明确偏好，请遵循 Momentic 的基本实践：

• 优先使用 Momentic 原生步骤和自然语言目标，而不是 JavaScript 或选择器。
• 保持断言精简并以用户为中心；执行灵活操作后，明确检查结果。
• 对于身份验证、设置和导航等既有流程，复用现有模块，而不是在测试中重复编写这些流程。
• 除非所请求的产品契约要求，否则不要重组或修改共享模块。对于所有使用已修改模块的测试，都要纳入考虑。
• 绝不要通过修改测试来绕过真实的产品故障。

新规格优先使用 AI action V3

编写新测试时，如果高层目标作为产品规格读起来更清晰，尤其是流程较长时，优先使用 AI action V3 act: 步骤。对于已知子流程，复用现有模块；对于新行为，使用 act:，不要把可复用的设置隐藏在一个庞大的目标中。

目标应简短、具体，并以结果为导向。将 act: 步骤与附近测试采用的同类断言方式搭配使用，这样测试验证的是结果，而不只是 Agent 已停止运行。

对于快速或对时序敏感的序列，优先使用一个专注的 AI Action，明确指定操作顺序并要求不等待，同时搭配基于视频的运行断言。遵循 Time-sensitive interactions，验证预期状态是否确实得到执行；仅使用 AI Action 无法保证时序或竞态覆盖。

AI action V3 会在成功运行后缓存生成的步骤，并在缓存步骤未命中时自动修复：

• 对稳定的产品流程，保持启用缓存。缓存重跑速度更快，也更具确定性。
• 仅当目标本身具有动态性、每次运行都应重新推导时，才设置 cache: false，例如打开最新记录或响应频繁变化的内容。
• 不要通过禁用缓存来掩盖过时或不正确的规格。如果预期行为发生变化，请更新目标或步骤描述，以改变其缓存标识。
• 当 MCP 预览为将要保存的步骤返回 CacheId 时，请按 momentic-test 技能的要求，将该缓存 ID 带入已保存的步骤。

在持久的端到端检查点运行

Momentic 用于真正的端到端验证，而不是编码 Agent 的内部反馈循环。不要在每次文件编辑、实现步骤、提交或小型重构后运行受影响的 Momentic 测试。

无需确认即可编辑和 lint Momentic 测试。在运行耗时较长的 Momentic 测试或测试套件之前，请根据预计耗时和范围征求确认。如果耗时未知，则按耗时较长处理。在持久的检查点：

1. 在运行耗时较长的 Momentic 测试前暂停。
2. 明确告知用户你计划运行哪些测试或命令，并在已知时说明预计耗时。
3. 询问用户是否确认运行。
4. 仅在获得明确确认后运行。用户直接要求运行指定测试即视为确认。

确认仅适用于所提议的耗时较长的运行。除非用户明确授权迭代重跑，否则再次运行耗时较长的 Momentic 测试前应重新征求确认。作为所请求工作的常规验证步骤，简短且范围明确的运行可无需确认直接进行。如果用户拒绝或未确认耗时较长的运行，请继续执行非 Momentic 检查，并报告未运行相关测试。

在开发过程中，使用单元测试、类型检查和 lint 等更快的仓库检查。当应用达到一个持久且可通过真实 UI 使用的逻辑检查点时，再运行 Momentic：

• 对于小型变更，检查点通常是变更已完全实现。
• 对于多阶段或超大型功能，检查点可以是一个已完成且可独立使用的 UI 部分，并具备相关测试所需的所有前置条件。如果有意义的组件已经可以进行端到端测试，不要等到整个功能完成。
• 不要将任意提交边界视为检查点。判断标准是：用户能否通过产品体验预期行为，并观察到指定结果。

在每个检查点，提出范围最小的受影响测试集。对于耗时较长的测试集，获得确认后运行一次，诊断失败原因，并进行连贯的修复。除非先前已获准迭代重跑，否则耗时较长的测试重跑前应再次征求确认。仅当有合理预期认为端到端结果会发生变化时才重跑。在检查点具备之前，保持未来规格处于禁用状态。

掌控测试数据和应用状态

实现产品变更的编码 Agent 负责确保检查点能够顺利运行。调用 Momentic 之前，应确定并建立所需的数据、账户状态、功能标志、权限、集成和服务状态。不要让浏览器 Agent 通过无关的 UI 流程自行摸索并创建前置条件。

优先使用现有的测试设置设施。如果应用没有可靠的方式来创建前置条件，鼓励编码 Agent 构建安全且仅限测试环境使用的能力，例如：

• 可幂等执行、用于填充确定性记录和状态的端点或脚本
• 用于生成逼真测试数据的固件和工厂
• 专用测试账户、角色和身份验证状态
• 用于功能标志或外部服务替代方案的仅限测试环境的控件
• 有范围限制的清理机制或唯一数据机制，以防止不同运行之间相互污染

任何新的测试能力都必须无法在生产环境中访问，明确限定为经批准的测试环境，在适当情况下要求身份验证，严格限制作用范围，并且可安全地重复调用。绝不要添加生产后门、削弱生产授权，或将被测行为编码到填充机制中。

记录设置约定，并在 Momentic 运行之前执行设置，或从测试既定的设置部分调用设置。这样得到的测试应能在干净环境中重复运行，而不依赖上一次运行意外留下的状态。

安全地编辑和验证

有关详细的编写、格式和 MCP 指南，请使用已安装的 momentic-test 技能。

• 如果变更较小且预期步骤明确，可直接编辑 v2 测试（fileType: momentic/test/v2）。
• 不要直接编辑 v1 测试 YAML。使用 Momentic MCP 工具保存 v1 变更。
• 如果 UI 探索、实时状态或定位器行为存在不确定性，请使用 MCP 浏览器验证。
• 尽可能在实现产品之前对测试规范进行 lint 检查。
• 在持久的端到端检查点，移除现已预期能够通过的测试中的 disabled: true，建立其所需状态，并询问是否运行受影响范围最小的一组测试。
• 只有在测试仍然有意不通过时才保留禁用状态，并在交接说明中写明原因和启用条件。

实现完成后，运行代码仓库要求的产品代码检查。在交接说明中，列出受影响的测试及其启用或禁用状态、已实现的产品行为，以及所有已运行或未运行的验证。