在已有 Momentic 端到端测试时…

适用于已有 Momentic 测试基础设施的团队，在开发用户可见功能时先写或改端到端规格测试，再实现代码，并在持久检查点征得确认后运行最小测试集。

适用场景

解决思路

1. 将期望的产品行为先写成 Momentic 测试，再实现；把测试当作契约，不要为了让测试迁就实现而修改测试。
2. 按不可协商顺序第 1 步：阅读仓库指南、`momentic.config.yaml`、附近测试与模块。
3. 按不可协商顺序第 2 步：识别并报告预计会受影响的准确 Momentic 测试。
4. 按不可协商顺序第 3 步：在改动产品代码之前创建或修改这些测试。
5. 按不可协商顺序第 4 步：将测试 diff 作为产品规格进行审查。
6. 按不可协商顺序第 5 步：只有在这之后才实现产品变更。
7. 按不可协商顺序第 6 步：实现过程中使用快速代码级检查；不要每次编辑或提交后都运行 Momentic。
8. 按不可协商顺序第 7 步：在持久化端到端检查点，准备所需测试状态，启用此时应通过的受影响测试，并询问是否运行最小受影响集合。
9. 在预期测试规格落盘前不要开始产品实现；若用户改变需求，先再次更新规格测试。
10. 若用户点名具体现有测试，从这些测试开始并保持工作聚焦；仅当仓库证据显示另一个测试或共享模块直接受影响时才扩大集合。
11. 对新的用户可见功能，创建描述新用户旅程的最小新测试。
12. 对变更功能，更新描述旧行为的现有测试，而不是添加重复覆盖。
13. 追踪共享组件和模块到足以发现真实行为影响的程度；不要仅凭文件名推断受影响集合。
14. 如果没有 Momentic 测试受影响，在改动产品前说明原因；不要仅为了产生测试 diff 而做表面测试编辑。
15. 在编辑产品代码前，报告每个受影响测试路径及其状态：新增、修改或保持不变。
16. 让实现前测试描述请求的结果，即使当前产品尚不能满足它。
17. 保留无关的 setup、teardown、数据、断言和测试意图。
18. 不要因为与当前实现一致就弱化断言或保留旧行为。
19. 当实现或所需依赖未就绪且测试暂不应通过时，将测试标记为 `disabled: true`；记录禁用原因以及启用前必须满足的条件。
20. 不要仅因本地凭据或可运行环境不可用就使用 `disabled: true`；那是验证限制，不一定是预期的产品失败。
21. 保持测试 delta 狭窄；一个变更的产品契约通常应只有一个聚焦的测试 delta。
22. 写完测试后，总结预期失败或禁用的行为，并在实现前确认测试表达了用户请求。
23. 阅读附近测试并遵循其既有约定，包括文件夹位置、命名、模块、setup、数据，以及偏好 AI checks、page checks 或 element checks。
24. 当代码库未表达偏好时，应用 Momentic 基线实践：优先使用原生 Momentic 步骤和自然语言目标，而不是 JavaScript 或选择器。
25. 保持断言最少且由用户驱动，在灵活动作后加明确的结果检查。
26. 对认证、setup、导航等既有流程复用现有模块，不要内联重建这些流程。
27. 除非请求的产品契约要求，不要重组或修改共享模块；对每个消费被改模块的测试负责。
28. 绝不要通过修改测试来绕过真实产品失败。
29. 对新测试，当高层目标更像产品规格时，优先使用 AI action V3 `act:` 步骤，尤其适用于长流程。
30. 对已知子流程复用现有模块，新行为用 `act:`，不要把可复用 setup 藏在一个大目标里。
31. 保持目标简短、具体、以结果为导向。
32. 将 `act:` 步骤与附近测试使用的断言风格配对，使测试验证结果，而不仅验证 agent 停止。
33. AI action V3 在成功运行后缓存生成的步骤，并在缓存步骤未命中时自愈。
34. 对稳定的产品流程保持缓存启用；缓存重跑更快、更确定。
35. 仅当目标本质上动态、每次运行都应重新推导时设置 `cache: false`，例如打开最新记录或响应频繁变化的内容。
36. 不要通过禁用缓存来掩盖过期或错误的规格；当预期行为变化时，更新目标或步骤描述，使其缓存身份改变。
37. 当 MCP preview 为将要持久化的步骤返回 `CacheId` 时，按 `momentic-test` skill 要求将该 cache ID 带入保存的步骤。
38. 把 Momentic 当作真正的端到端验证，不是 coding agent 的内部反馈循环；不要每次文件编辑、实现步骤、提交或小重构后运行受影响的 Momentic 测试。
39. 默认不要执行 Momentic 测试；允许无确认地编辑和 lint Momentic 测试，但测试执行可能耗时并消耗 credits。
40. 在持久化检查点，停止运行 Momentic 前，准确告诉用户拟运行哪些测试或命令，并在已知时说明预期耗时或 credit 影响。
41. 询问用户确认是否运行这些测试。
42. 仅在明确确认后运行；直接要求运行指定测试也算确认。
43. 确认只覆盖所提议的那次运行；在另一次 Momentic 执行前再次询问，除非用户明确授权迭代重跑。
44. 如果用户拒绝或未确认，继续非 Momentic 检查，并报告这些测试未运行。
45. 构建期间使用更快的仓库检查，如单元测试、typechecking 和 linting。
46. 当应用达到逻辑检查点且可通过真实 UI 持久可用时运行 Momentic；小改动的检查点通常是完整实现后的变更。
47. 对多阶段或超大型功能，检查点可以是已完成、可独立使用的 UI 切片，且具备受影响测试所需的所有前置条件；当有意义的组件已可端到端测试时，不要等待整个功能。
48. 不要把任意提交边界当作检查点；决定性问题是通过产品能否让用户执行预期行为并观察到指定结果。
49. 在每个检查点提议最小受影响测试集合。
50. 确认后运行一次，诊断失败并进行一致的修复。
51. 除非已授权迭代重跑，在重跑前再次请求确认；仅当有合理预期端到端结果已改变时才重跑。
52. 在对应检查点存在前，保持未来规格测试为禁用状态。
53. 实现产品变更的 coding agent 负责让检查点可干净运行；调用 Momentic 前，识别并建立所需的数据、账号状态、feature flags、权限、集成和服务状态。
54. 不要把前置条件创建留给浏览器 agent 通过无关 UI 流程临时发挥。
55. 优先使用现有测试 setup 设施。
56. 当应用缺少可靠创建前置条件的方式时，构建幂等端点或脚本，用于播种确定性记录和状态。
57. 当应用缺少可靠创建前置条件的方式时，构建 fixtures 和 factories，用于生成真实测试数据。
58. 当应用缺少可靠创建前置条件的方式时，构建专用测试账号、角色和认证状态。
59. 当应用缺少可靠创建前置条件的方式时，构建用于 feature flags 或外部服务替代品的测试专用控制。
60. 当应用缺少可靠创建前置条件的方式时，构建防止跨运行污染的作用域清理或唯一数据机制。
61. 任何新的测试能力必须生产不可访问、显式限定到批准测试环境、适当时认证、范围狭窄且可安全重复调用。
62. 绝不要添加生产后门、削弱生产授权，或将被测行为编码进种子机制。
63. 记录 setup 契约，并在 Momentic 运行前执行它，或从测试既有的 setup 部分调用它。
64. 使生成的测试可从干净环境重复运行，不依赖上一次运行的偶然状态。
65. 使用已安装的 `momentic-test` skill 获取详细编写、格式和 MCP 指南。
66. 当改动小且预期步骤清晰时，直接编辑 v2 测试（`fileType: momentic/test/v2`）。
67. 不要直接编辑 v1 测试 YAML；使用 Momentic MCP 工具持久化 v1 变更。
68. 当 UI 发现、实时状态或 locator 行为不确定时，使用 MCP browser validation。
69. 尽可能在产品实现前 lint 测试规格。
70. 在持久化端到端检查点，从此时预期通过的测试中移除 `disabled: true`，建立其所需状态，并询问是否运行最小受影响集合。
71. 仅当测试仍有意不预期通过时才保持禁用，并在 handoff 中包含原因和启用条件。
72. 实现后运行仓库要求的产品代码检查。
73. 在 handoff 中列出受影响测试、其启用/禁用状态、实现的产品行为，以及每一项已运行或未运行的验证。

适用边界 · 注意事项

• 项目未使用 Momentic、没有 `momentic.config.yaml`、未安装 `momentic-test`/MCP 工具时，不要套用本经验。
• 纯内部重构或无需真实 UI 端到端验证的小改动，不必把 Momentic 当作主要反馈循环。
• 无法承担 Momentic 执行耗时或 credits，或未获用户确认时，不要默认执行 Momentic 测试。