momentic-spec
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMomentic spec-driven development
Momentic规范驱动开发
Write the expected product behavior as Momentic tests before implementing it.
The tests define the contract; do not make the tests fit the implementation.
在实现产品功能前,先将预期的产品行为编写为Momentic测试。测试定义了契约,切勿让测试去适配实现。
Non-negotiable sequence
不可变更的执行顺序
- Read repository guidance, , and nearby tests and modules.
momentic.config.yaml - Identify and report the exact Momentic tests expected to be affected.
- Create or modify those tests before changing product code.
- Review the test diff as a product specification.
- Only then implement the product change.
- Use fast code-level checks while implementing; do not run Momentic after every edit or commit.
- At a durable end-to-end checkpoint, prepare the required test state, enable the affected tests that should now pass, and run the smallest affected set.
Do not begin product implementation until the intended test specifications are
on disk. If the user changes the requirement, update the spec first again.
- 阅读代码库指南、配置文件以及相关的测试和模块。
momentic.config.yaml - 识别并报告预计会受影响的具体Momentic测试。
- 在修改产品代码前,创建或修改这些测试。
- 将测试差异作为产品规范进行评审。
- 完成上述步骤后,再实施产品变更。
- 实现过程中使用快速代码级检查,无需在每次编辑或提交后运行Momentic。
- 在稳定的端到端检查点,准备好所需的测试状态,启用现在应该能通过的受影响测试,并运行最小范围的受影响测试集。
在预期的测试规范写入磁盘前,请勿开始产品实现。如果用户更改需求,请先再次更新规范。
Choose the affected tests
选择受影响的测试
- If the user names specific existing tests, start with those tests and keep the work focused on them. Expand the set only when repository evidence shows another test or shared module is directly affected.
- For new user-visible functionality, create the smallest new test or tests that describe the new user journey.
- For changed functionality, update the existing tests that describe the old behavior instead of adding duplicate coverage.
- Trace shared components and modules far enough to find real behavioral impact. Do not infer the affected set from filenames alone.
- If no Momentic test is affected, state why before making product changes. Do not make cosmetic test edits merely to produce a test diff.
Before editing product code, report each affected test path and whether it will
be added, changed, or left unchanged.
- 如果用户指定了具体的现有测试,从这些测试入手,保持工作聚焦。仅当代码库证据显示其他测试或共享模块直接受影响时,再扩大范围。
- 对于新的用户可见功能,创建最小化的新测试来描述新的用户流程。
- 对于功能变更,更新描述旧行为的现有测试,而非添加重复的测试覆盖。
- 追踪共享组件和模块,找到实际的行为影响。切勿仅通过文件名推断受影响的测试集。
- 如果没有Momentic测试受影响,请在修改产品代码前说明原因。切勿仅为了生成测试差异而进行无意义的测试编辑。
在编辑产品代码前,报告每个受影响的测试路径,以及该测试将被添加、修改还是保持不变。
Write the product specification first
先编写产品规范
The pre-implementation test should describe the requested outcome, even when the
current product cannot satisfy it yet.
- Preserve unrelated setup, teardown, data, assertions, and test intent.
- Do not weaken an assertion or preserve old behavior just because that matches the current implementation.
- Mark a test when the implementation or a required dependency is not ready and the test is not expected to pass yet. Record why it is disabled and what must become true before enabling it.
disabled: true - Do not use merely because local credentials or a runnable environment are unavailable. That is a validation limitation, not necessarily an expected product failure.
disabled: true - Keep the delta narrow. One changed product contract should normally have one focused test delta.
After writing the tests, summarize the expected failing or disabled behavior and
confirm the tests express the user's request before implementing it.
预实现测试应描述请求的预期结果,即使当前产品还无法满足该要求。
- 保留无关的初始化、清理、数据、断言和测试意图。
- 切勿因为当前实现的情况而弱化断言或保留旧行为。
- 当实现或所需依赖未就绪、测试预计无法通过时,将测试标记为。记录禁用原因以及启用测试所需满足的条件。
disabled: true - 切勿仅因为本地凭证或可运行环境不可用就使用。这属于验证限制,而非预期的产品故障。
disabled: true - 保持变更范围狭窄。一项产品契约变更通常应对应一个聚焦的测试变更。
编写完测试后,总结预计的失败或禁用行为,并在实现前确认测试准确表达了用户的需求。
Follow the codebase's testing language
遵循代码库的测试语言规范
Read nearby tests and follow their established conventions, including folder
placement, naming, modules, setup, data, and preference for AI checks, page
checks, or element checks. Apply baseline Momentic practices where the codebase
does not express a preference:
- Prefer native Momentic steps and natural-language targets over JavaScript or selectors.
- Keep assertions minimal and user-driven, with an explicit outcome check after a flexible action.
- Reuse existing modules for established flows such as authentication, setup, and navigation instead of recreating those flows inline.
- Do not reorganize or modify a shared module unless the requested product contract requires it. Account for every test that consumes a changed module.
- Never work around a real product failure by changing the test.
阅读相关测试并遵循已确立的约定,包括文件夹位置、命名规则、模块、初始化、数据以及对AI检查、页面检查或元素检查的偏好。如果代码库未明确表达偏好,则应用Momentic的基础实践:
- 优先使用原生Momentic步骤和自然语言目标,而非JavaScript或选择器。
- 保持断言最小化且以用户为导向,在灵活操作后进行明确的结果检查。
- 重用现有模块来处理已确立的流程,如认证、初始化和导航,而非在测试中重新创建这些流程。
- 除非请求的产品契约要求,否则不要重组或修改共享模块。需考虑所有使用该变更模块的测试。
- 切勿通过修改测试来规避真实的产品故障。
Prefer AI action V3 for new specifications
新规范优先使用AI action V3
For a new test, prefer an AI action V3 step when a high-level goal reads
more clearly as a product specification, especially for a long flow. Reuse
existing modules for known subflows and use for the new behavior rather
than hiding reusable setup inside one large goal.
act:act:Keep goals short, specific, and outcome-oriented. Pair an step with the
same assertion style used by nearby tests so the test verifies the result, not
only that the agent stopped.
act:AI action V3 caches generated steps after a successful run and self-heals when a
cached step misses:
- Keep caching enabled for stable product flows. Cached reruns are faster and more deterministic.
- Set only when the goal is inherently dynamic and should be re-derived every run, such as opening the most recent record or responding to frequently changing content.
cache: false - Do not disable cache to hide a stale or incorrect specification. When the intended behavior changes, update the goal or step description so its cache identity changes.
- When MCP preview returns a for a step that will be persisted, carry that cache ID into the saved step as required by the
CacheIdskill.momentic-test
对于新测试,当高层级目标作为产品规范更清晰时,优先使用AI action V3的步骤,尤其是针对长流程。重用现有模块处理已知子流程,对新行为使用步骤,而非将可重用的初始化隐藏在一个大目标中。
act:act:保持目标简短、具体且以结果为导向。将步骤与相关测试使用的相同断言风格配对,确保测试验证的是结果,而非仅验证代理是否停止。
act:AI action V3在成功运行后会缓存生成的步骤,当缓存步骤失效时会自我修复:
- 对于稳定的产品流程,保持缓存启用。缓存重运行更快且更具确定性。
- 仅当目标本身具有动态性、需要每次运行重新生成时,设置,例如打开最新记录或响应频繁变化的内容。
cache: false - 切勿为了隐藏过时或不正确的规范而禁用缓存。当预期行为变更时,更新目标或步骤描述,使其缓存标识发生变化。
- 当MCP预览返回将被持久化的步骤的时,按照
CacheId技能的要求,将该缓存ID带入保存的步骤中。momentic-test
Run at durable end-to-end checkpoints
在稳定的端到端检查点运行测试
Momentic is true end-to-end validation, not the coding agent's inner feedback
loop. Do not run affected Momentic tests after every file edit, implementation
step, commit, or small refactor.
Use faster repository checks such as unit tests, typechecking, and linting while
building. Run Momentic when the app has reached a logical checkpoint that is
durable and usable through the real UI:
- For a small change, the checkpoint is usually the fully implemented change.
- For a multi-stage or extra-large feature, a checkpoint can be a completed, independently usable UI slice with all prerequisites needed for its affected test. Do not wait for the entire feature when a meaningful component is already testable end to end.
- Do not treat an arbitrary commit boundary as a checkpoint. The deciding question is whether a user can exercise the intended behavior through the product and observe the specified outcome.
At each checkpoint, run the smallest affected test set once, diagnose failures,
make a coherent fix, and rerun only when there is a reasonable expectation that
the end-to-end outcome changed. Keep future specifications disabled until their
checkpoint exists.
Momentic是真正的端到端验证,而非编码代理的内部反馈循环。无需在每次文件编辑、实现步骤、提交或小型重构后运行受影响的Momentic测试。
开发过程中使用更快的代码库检查,如单元测试、类型检查和代码扫描。当应用达到一个稳定且可通过真实UI使用的逻辑检查点时,再运行Momentic:
- 对于小型变更,检查点通常是完全实现的变更。
- 对于多阶段或超大型功能,检查点可以是一个已完成、可独立使用的UI片段,且具备其受影响测试所需的所有先决条件。当有意义的组件已可进行端到端测试时,无需等待整个功能完成。
- 切勿将任意提交边界视为检查点。判断标准是用户是否可以通过产品操作预期行为并观察到指定结果。
在每个检查点,运行最小范围的受影响测试集一次,诊断故障,进行连贯修复,仅当有合理预期端到端结果已变更时才重新运行。在检查点出现前,保持未来的规范处于禁用状态。
Own the test data and application state
管理测试数据和应用状态
The coding agent implementing the product change is responsible for making the
checkpoint cleanly runnable. Before invoking Momentic, identify and establish
the required data, account state, feature flags, permissions, integrations, and
service state. Do not leave prerequisite creation for the browser agent to
improvise through unrelated UI flows.
Prefer existing test setup facilities. When the application lacks a reliable
way to create prerequisites, the coding agent is encouraged to build safe,
test-environment-only capabilities such as:
- idempotent endpoints or scripts that seed deterministic records and state
- fixtures and factories for realistic test data
- dedicated test accounts, roles, and authentication state
- test-only controls for feature flags or external-service substitutes
- scoped cleanup or unique-data mechanisms that prevent cross-run pollution
Any new test capability must be inaccessible in production, explicitly gated to
approved test environments, authenticated where appropriate, narrowly scoped,
and safe to call repeatedly. Never add a production backdoor, weaken production
authorization, or encode the behavior under test inside the seed mechanism.
Document the setup contract and either execute it before the Momentic run or
invoke it from the test's established setup section. The resulting test should
be repeatable from a clean environment without relying on accidental state from
a previous run.
实现产品变更的编码代理负责确保检查点可干净运行。在调用Momentic前,识别并建立所需的数据、账户状态、功能标志、权限、集成和服务状态。切勿让浏览器代理通过无关的UI流程来临时创建先决条件。
优先使用现有的测试初始化工具。当应用缺乏可靠的先决条件创建方式时,编码代理可构建安全的、仅适用于测试环境的功能,例如:
- 幂等的端点或脚本,用于生成确定性的记录和状态
- 用于生成真实测试数据的 fixtures 和工厂
- 专用的测试账户、角色和认证状态
- 功能标志或外部服务替代项的测试专用控制
- 范围化的清理或唯一数据机制,防止跨运行污染
任何新的测试功能必须在生产环境中不可访问,明确限制在已批准的测试环境中,必要时进行认证,范围狭窄且可安全重复调用。切勿添加生产后门、弱化生产授权或将测试中的行为编码到种子机制中。
记录初始化契约,并在Momentic运行前执行,或从测试已确立的初始化部分调用。最终的测试应能从干净环境中重复运行,无需依赖前一次运行的意外状态。
Edit and validate safely
安全编辑和验证
Use the installed skill for detailed authoring, format, and MCP
guidance.
momentic-test- Edit v2 tests () directly when the change is small and the intended steps are clear.
fileType: momentic/test/v2 - Do not edit v1 test YAML directly. Use Momentic MCP tools to persist v1 changes.
- Use MCP browser validation when UI discovery, live state, or locator behavior is uncertain.
- Lint the test specifications before product implementation when possible.
- At a durable end-to-end checkpoint, remove from tests that are now expected to pass, establish their required state, and run the smallest affected set.
disabled: true - Leave a test disabled only when it is still intentionally not expected to pass, and include the reason and enablement condition in the handoff.
Run the repository's required product-code checks after implementation. In the
handoff, list the affected tests, their enabled or disabled state, the product
behavior implemented, and every validation that was or was not run.
使用已安装的技能获取详细的编写、格式和MCP指南。
momentic-test- 当变更较小时且预期步骤明确,直接编辑v2测试()。
fileType: momentic/test/v2 - 请勿直接编辑v1测试YAML文件。使用Momentic MCP工具来持久化v1测试的变更。
- 当UI发现、实时状态或定位器行为不确定时,使用MCP浏览器验证。
- 尽可能在产品实现前对测试规范进行代码扫描。
- 在稳定的端到端检查点,移除现在预计可通过的测试的标记,建立其所需状态,并运行最小范围的受影响测试集。
disabled: true - 仅当测试仍预计无法通过时才保持禁用状态,并在交接时说明原因和启用条件。
实现完成后运行代码库要求的产品代码检查。在交接时,列出受影响的测试、它们的启用/禁用状态、已实现的产品行为以及已运行和未运行的所有验证。