gravity_web/.agents/references/known-issues.md

Known Issues & Lessons Learned — Gravity Web

이 파일은 SSOT(Single Source of Truth)입니다. 디버깅이나 구현 전에 반드시 이 파일을 확인하세요. 세션 종료 시 새로 발견된 이슈를 이 파일에 추가합니다.

---

공통 이슈

[2026-03-08] PowerShell curl — Invoke-WebRequest 충돌

• 증상: curl 명령이 예상과 다른 응답 형식을 반환
• 원인: PowerShell에서 curl은 Invoke-WebRequest의 별칭
• 해결: **curl.exe**를 명시적으로 사용
• 주의: HTTP 관련 모든 명령에서 curl.exe 사용 필수

[2026-03-08] PowerShell npm — 실행 정책 오류

• 증상: npm run 명령이 실행 정책 관련 오류로 실패
• 원인: PowerShell 스크립트 실행 정책이 제한적으로 설정됨
• 해결: cmd /c npm run dev 형식으로 cmd를 통해 실행
• 주의: npm 관련 명령은 항상 cmd /c 접두어 사용

[2026-03-08] Vikunja API — POST 시 필드 덮어씌움

• 증상: 태스크 업데이트 시 기존 라벨/설명이 사라짐
• 원인: Vikunja API POST 시 body에 없는 필드를 빈값으로 덮어씀
• 해결: vikunja_helper.py 사용 (GET → 기존 필드 보존 → POST 패턴)
• 주의: 절대로 Invoke-RestMethod -Method Post -Body '{\"done\": true}' 같은 직접 API 호출 금지

[2026-03-08] PowerShell JSON 파이프 — 이스케이핑 문제

• 증상: PowerShell에서 JSON을 파이프로 전달할 때 따옴표/특수문자가 깨짐
• 원인: PowerShell의 이스케이핑 규칙이 bash와 다름
• 해결: JSON 처리가 필요하면 .py 스크립트로 만들어 실행
• 주의: 복잡한 API 호출은 반드시 Python 헬퍼 스크립트 사용

---

CDP 관련 이슈

[2026-03-08] CDP 연결 — Antigravity.exe 직접 실행 필수

• 증상: antigravity . CLI로 실행 시 CDP 포트가 열리지 않음
• 원인: CLI 래퍼가 ELECTRON_RUN_AS_NODE=1을 설정하여 CDP 비활성화
• 해결: "%LOCALAPPDATA%\Programs\Antigravity\Antigravity.exe" --remote-debugging-port=9000으로 직접 실행
• 주의: 기존 Antigravity 프로세스가 있으면 새 인스턴스가 합류하여 별도 CDP 포트 열리지 않음. 모든 인스턴스 종료 후 실행

---

프로젝트별 이슈

(세션 진행 중 발견되는 이슈를 여기에 추가)