Motion Studio SDLC実行プレイブック (balantrapu87/amds)

Motion Studio SDLC実行プレイブック

このリポジトリで機能追加またはバグ修正を実装するよう指示された場合、以下の手順を順番に実行します。

ステップ 1: 契約同期（仕様ゲート）

1. engine/schemas.py と remotion/src/types.ts を検査します。
2. 機能要件を満たすためにフィールドを追加または変更します。
3. Pydanticモデルがコンパイルされることを検証します。

   python3 -c "import engine.schemas as s; print('Schemas OK')"
   

   （注：プロジェクトの仮想環境が存在する場合は、.venv/bin/python3 経由で呼び出してください）
4. 両方の言語でコントラクトが調整されるまで、実装コードに進まないでください。

ステップ 2: Redフェーズ（失敗するテストの作成）

1. tests/（Pytest）または remotion/src/__tests__/（Vitest/Jest）の下に、新しいテストファイルまたはテストケースを作成します。
2. スキーマバリデーション、エッジケース、期待されるシリアライズ出力をアサートします。
3. テストを実行し、失敗を確認します。

   pytest tests/
   # フロントエンドテストランナーがremotion/package.jsonで設定されている場合:
   npm --prefix remotion test -- --run
   

4. 失敗トレースを記録します。テストが即座に合格した場合は、実際の新しい機能をテストするようにテストを書き直します。Redフェーズは、テストが期待されるアサーションで失敗した場合にのみ満たされます。

ステップ 3: Greenフェーズ（最小限の実装）

1. 失敗したテストを満たすために、engine/ または remotion/src/ に最小限のコードを記述します。
2. Remotionでは、決定論的フレームの法則に厳密に従ってください。
   • 導出は useCurrentFrame() と useVideoConfig() からのみ行わなければなりません。
   • Date.now()、Math.random()、または無制限の requestAnimationFrame() を決して使用してはいけません。
3. 既存のアーキテクチャパターン（<Series>、<Sequence>、<ThreeScene>、<KineticScene>）を維持します。
4. GSAPターゲティングのために、ベクターアセットが remotion/svgo.config.mjs に従ってIDとクラスを保持していることを確認します。

ステップ 4: 品質ゲート＆自動自己修復ループ

ループ反復カウンター（ATTEMPT ∈ {1, 2, 3}）を追跡します。各ゲートを順番に実行し、終了コードをマスクしないでください（|| true を付加しないでください）。

# ティア 1: 静的型解析
python3 -m mypy engine/schemas.py engine/api.py
npm --prefix remotion run build -- --bundle-cache=false

# ティア 2: 自動テストスイート
pytest tests/
# フロントエンドテストランナーがremotion/package.jsonで設定されている場合:
npm --prefix remotion test -- --run

# ティア 3: ヘッドレスChromiumフレームラスタライゼーション
(cd remotion && npx remotion still src/index.ts MainComposition /tmp/smoke.png \
  --props='{"scenes":[],"theme":{}}' \
  --gl=angle \
  --overwrite)

自己修復＆ロールバックポリシー

• 失敗時（試行 1 または 2 回目）:

  1. 正確なファイルパス、失敗行番号、stderr/トレースバックを取得します。
  2. 報告されたエラーにのみ対処する、最小限のターゲットパッチを実装します。
  3. ATTEMPT をインクリメントし、ティア 1 から再開します。

• 失敗時（試行 3 回目 - 予算使い切り）: 推測による変更を直ちに停止し、変更および作成された機能ファイルのみを元に戻します（決して包括的なグローバルクリーンは行わないでください）。

  # ティア 4 使い切りフォールバック: 機能コードスコープのみをターゲット
  git restore --staged --worktree engine/ remotion/ tests/
  git clean -fd engine/ remotion/ tests/
  rm -f /tmp/smoke.png
  echo "品質ゲートが3回の試行後に失敗しました。ターゲットコードパスをクリーンベースラインに復元しました。"
  exit 1
  

  （事後分析のために作業内容を保持する代替案: git stash push -u -m "sdlc-failed-attempt-$(date +%s)" -- engine/ remotion/ tests/）

• 成功時（全ティアが終了コード0）: 一時アーティファクトを削除し、検証済みコミットを作成します。

  rm -f /tmp/smoke.png
  git add engine/ remotion/ tests/
  git commit -m "feat(motion-sdlc): implement verified feature with green test gate"