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단계: 레드 단계 (실패하는 테스트 작성)

1. tests/(Pytest) 또는 remotion/src/__tests__/(Vitest/Jest) 아래에 새로운 테스트 파일이나 테스트 케이스를 작성합니다.
2. 스키마 유효성 검사, 엣지 케이스, 예상 직렬화 출력을 단언(assert)합니다.
3. 테스트를 실행하고 실패를 확인합니다:

   pytest tests/
   # remotion/package.json에 프론트엔드 테스트 러너가 설정된 경우:
   npm --prefix remotion test -- --run
   

4. 실패 트레이스를 기록합니다. 테스트가 즉시 통과하면, 실제 새로운 기능을 테스트하도록 다시 작성하세요. 레드 단계는 오직 테스트가 예상된 단언문으로 실패할 때만 충족됩니다.

3단계: 그린 단계 (최소 구현)

1. engine/ 또는 remotion/src/에 실패한 테스트를 통과시키기 위한 최소한의 코드를 작성합니다.
2. Remotion에서는 결정론적 프레임 법칙(Deterministic Frame Law)을 엄격히 준수하세요:
   • 값 도출은 반드시 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: Headless 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"