momentic-spec

Momentic の仕様駆動開発

実装を始める前に、期待する製品の動作を Momentic テストとして記述します。 テストが契約を定義します。実装に合うようにテストを変更してはいけません。

必ず守る手順

1. リポジトリのガイダンス、momentic.config.yaml、近くにあるテストと モジュールを読みます。
2. 影響を受けると見込まれる Momentic テストを正確に特定し、報告します。
3. 製品コードを変更する前に、それらのテストを作成または変更します。
4. テストの差分を製品仕様としてレビューします。
5. その後に限り、製品の変更を実装します。
6. 実装中は高速なコードレベルのチェックを使います。編集やコミットの たびに Momentic を実行してはいけません。
7. エンドツーエンドの変更が安定した段階で、必要なテストの状態を整え、 これで通るはずの影響対象テストを有効にして、影響対象の最小セットを 実行してよいか確認します。

意図するテスト仕様がディスク上に保存されるまでは、製品の実装を始めてはいけません。ユーザーが要件を変更した場合は、まず仕様を再度更新します。

影響対象テストを選ぶ

• ユーザーが既存のテストを指定した場合は、それらのテストから始め、 作業範囲を絞ります。別のテストまたは共有モジュールが直接影響を 受けることをリポジトリの証拠が示す場合に限り、対象を広げます。
• ユーザー向けの新機能の場合は、新しいユーザージャーニーを記述する 最小限のテストを作成します。
• 機能を変更する場合は、重複するカバレッジを追加するのではなく、 古い動作を記述している既存テストを更新します。
• 実際の動作への影響を見つけるため、共有コンポーネントとモジュールを 十分に追跡します。ファイル名だけから影響対象を推測してはいけません。
• 影響を受ける Momentic テストがない場合は、製品を変更する前にその理由を 述べます。テストの差分を作ることだけを目的に、見た目だけのテスト編集を してはいけません。

製品コードを編集する前に、影響対象となる各テストのパスと、それを追加、変更、または変更せずに残すかを報告します。

まず製品仕様を書く

実装前のテストでは、現在の製品ではまだ満たせない場合でも、要求された結果を記述します。

• 無関係なセットアップ、ティアダウン、データ、アサーション、テストの意図を維持します。
• 現在の実装に合うという理由だけで、アサーションを弱めたり、古い動作を維持したりしてはいけません。
• 実装または必要な依存関係の準備が整っておらず、テストがまだ通る見込みのない場合は、disabled: true を設定します。無効にする理由と、有効化する前に満たす必要がある条件を記録します。
• ローカルの認証情報や実行可能な環境が利用できないというだけで、disabled: true を設定してはいけません。これは検証上の制約であり、製品が期待どおりに動作しないことを必ずしも意味しません。
• 差分の範囲を絞ります。通常、製品の契約を1つ変更する場合、焦点を絞ったテスト差分は1つにします。

テストを書いた後、想定される失敗または無効化された動作を要約し、そのテストが実装前にユーザーの要求を表現していることを確認します。

コードベースのテスト記法に従う

近くにあるテストを読み、フォルダーの配置、命名、モジュール、セットアップ、データ、および AI チェック、ページチェック、要素チェックの優先度など、確立された規約に従います。コードベースに明確な方針がない場合は、Momentic の基本的なプラクティスに従います。

• JavaScript やセレクターより、Momentic のネイティブステップと自然言語のターゲットを優先します。
• アサーションは最小限にしてユーザーの操作に沿ったものとし、柔軟な操作の後には明示的な結果確認を置きます。
• 認証、セットアップ、ナビゲーションなど、確立されたフローには既存のモジュールを再利用し、同じフローをテスト内に書き直さないようにします。
• 要求された製品の契約で必要とされない限り、共有モジュールを再編成または変更してはいけません。変更した共有モジュールを使用するすべてのテストを考慮します。
• 実際の製品の失敗を、テストを変更して回避してはいけません。

新しい仕様では AI action V3 を優先する

新しいテストでは、特に長いフローの場合、高レベルの目標を製品仕様として表現したほうが明確になるなら、AI action V3 の act: ステップを優先してください。既知のサブフローには既存のモジュールを再利用し、再利用可能なセットアップを大きな目標の中に隠すのではなく、新しい動作には act: を使用してください。

目標は短く、具体的で、結果を重視したものにしてください。act: ステップには近くのテストと同じアサーションスタイルを組み合わせ、エージェントが停止したことだけでなく、結果を検証するようにしてください。

短時間で終わるシーケンスやタイミングに依存するシーケンスでは、順序を明示し、待機しない指示を含めた、目的を絞った AI Action を優先し、動画に基づく実行時アサーションを組み合わせてください。意図した状態が実際に確認されたことを検証するには、時間依存のインタラクションに従ってください。AI Action だけでは、タイミングや競合状態のカバレッジは保証されません。

AI action V3 は、実行成功後に生成されたステップをキャッシュし、キャッシュされたステップが失敗すると自己修復します。

• 安定した製品フローでは、キャッシュを有効にしてください。キャッシュを使った再実行は高速で、決定性が高まります。
• 目標が本質的に動的で、最新のレコードを開く、頻繁に変化するコンテンツに応答するといったケースのように、毎回再導出する必要がある場合に限り、cache: false を設定してください。
• 古くなった仕様や誤った仕様を隠すために、キャッシュを無効にしないでください。意図した動作が変わった場合は、目標またはステップの説明を更新して、キャッシュの識別子が変わるようにしてください。
• MCP のプレビューで、保存するステップの CacheId が返された場合は、momentic-test スキルの要件に従って、そのキャッシュ ID を保存するステップに引き継いでください。

エンドツーエンドテストは確実なチェックポイントで実行する

Momentic は真のエンドツーエンド検証であり、コーディングエージェントの内部フィードバックループではありません。ファイルの編集、実装ステップ、コミット、小規模なリファクタリングのたびに、影響を受ける Momentic テストを実行しないでください。

確認なしで Momentic テストを編集し、lint を実行することはできます。時間のかかる Momentic テストまたはテストスイートを実行する前に、想定される所要時間と対象範囲を伝えて確認を求めてください。所要時間が不明な場合は、時間がかかる実行として扱ってください。確実なチェックポイントでは、次の手順に従ってください。

1. 時間のかかる Momentic の実行を開始する前に停止します。
2. 実行するテストまたはコマンドを正確にユーザーに伝え、わかる場合は想定所要時間も伝えます。
3. 実行してよいか、ユーザーに確認します。
4. 明示的な確認を得てから実行します。指定されたテストを実行するよう直接依頼された場合は、確認を得たものとします。

確認の対象となるのは、提案した時間のかかる実行のみです。ユーザーが反復実行を明示的に許可していない限り、次に時間のかかる Momentic の実行を行う前に、再度確認を求めてください。通常の検証手順として妥当な、短時間で目的を絞った実行は、依頼された作業の一環であれば確認なしで実行できます。ユーザーが時間のかかる実行を断る、または確認しない場合は、Momentic 以外のチェックを続け、テストを実行しなかったことを報告してください。

実装中は、ユニットテスト、型チェック、lint など、リポジトリのより高速なチェックを使用してください。アプリが、実際の UI を通じて利用できる、確実で論理的なチェックポイントに達したら、Momentic を実行します。

• 小規模な変更では、通常、実装が完了した時点がチェックポイントです。
• 複数段階にわたる機能や非常に大規模な機能では、影響を受けるテストに必要な前提条件がすべてそろった、単独で利用可能な UI の一部が完成した時点をチェックポイントにできます。意味のあるコンポーネントがすでにエンドツーエンドでテスト可能な場合は、機能全体の完成を待たないでください。
• 任意のコミット境界をチェックポイントとみなさないでください。判断基準は、ユーザーが製品を通じて意図した動作を実行し、指定された結果を確認できるかどうかです。

各チェックポイントでは、影響を受けるテストのうち最小限のセットを提案してください。時間のかかるテストセットの場合は、確認を得てから一度実行し、失敗を診断して、まとまりのある修正を行います。反復実行の許可をすでに得ていない限り、時間のかかるテストを再実行する前に、改めて確認を求めてください。エンドツーエンドの結果が変わると合理的に見込める場合に限り、再実行してください。チェックポイントが整うまで、今後の仕様は無効のままにしてください。

テストデータとアプリケーションの状態を管理する

プロダクト変更を実装するコーディングエージェントは、チェックポイントを問題なく実行できる状態にする責任があります。Momentic を実行する前に、必要なデータ、アカウントの状態、機能フラグ、権限、インテグレーション、サービスの状態を特定し、準備してください。無関係な UI フローを通じてブラウザーエージェントが場当たり的に準備するよう、前提条件の作成を任せてはいけません。

既存のテストセットアップ機能を優先してください。アプリケーションに前提条件を確実に作成する方法がない場合、コーディングエージェントは次のような、安全でテスト環境限定の機能を構築することが推奨されます。

• 決定的なレコードと状態をシードする、冪等なエンドポイントまたはスクリプト
• 現実的なテストデータ用のフィクスチャとファクトリー
• 専用のテストアカウント、ロール、認証状態
• 機能フラグや外部サービスの代替手段を制御する、テスト専用の機能
• 実行間のデータ汚染を防ぐ、対象を限定したクリーンアップや一意のデータを使う仕組み

新しいテスト機能はすべて本番環境からアクセスできないようにし、承認されたテスト環境でのみ明示的に有効化し、必要に応じて認証を必須とし、対象を限定したうえで、繰り返し安全に呼び出せるようにする必要があります。本番環境にバックドアを追加したり、本番環境の認可を弱めたり、テスト対象の動作をシード処理に埋め込んだりしてはいけません。

セットアップの手順を文書化し、Momentic の実行前に実行するか、テストの既定のセットアップセクションから呼び出してください。これにより、前回の実行で偶然残った状態に依存せず、クリーンな環境からテストを繰り返し実行できるようにします。

安全に編集・検証する

詳細な作成方法、フォーマット、MCP に関するガイダンスには、インストール済みの momentic-test スキルを使用してください。

• 変更が小さく、意図する手順が明確な場合は、v2 テスト（fileType: momentic/test/v2）を直接編集します。
• v1 テストの YAML を直接編集してはいけません。v1 の変更を保存するには、Momentic MCP ツールを使用してください。
• UI の探索、実際の状態、ロケーターの動作が不明確な場合は、MCP ブラウザー検証を使用してください。
• 可能であれば、プロダクトの実装前にテスト仕様をリントしてください。
• 安定したエンドツーエンドのチェックポイントに達したら、合格が見込まれるテストから disabled: true を削除し、必要な状態を準備して、影響を受ける最小限のテストセットを実行するか確認してください。
• まだ合格が見込まれず、意図的に無効化している場合に限り、テストを無効のままにします。引き継ぎには、その理由と有効化の条件を記載してください。

実装後、リポジトリで必須とされているプロダクトコードのチェックを実行してください。引き継ぎには、影響を受けるテスト、有効または無効の状態、実装したプロダクトの動作、実行した検証と実行しなかった検証をすべて記載してください。