next-dev-loop은(는) 무엇을 하나요?
next dev 중 수정/확인 리듬 — 변경을 가한 후, 타입이나 빌드만 통과하는 것이 아니라 실제로 런타임에 제대로 작동하는지 확인합니다.
동일한 실행 중인 앱을 두 가지 뷰로 확인합니다:
/_next/mcp— Next.js가 자신에 대해 노출하는 HTTP 엔드포인트입니다. 라우트, 세그먼트, RSC, 서버 액션, 서버 로그, Next.js가 본 에러 등 프레임워크 특정 정보를 알고 있습니다. 현재 표면을 보려면tools/list를 호출하세요.agent-browser— 실제 Chrome을 구동하는 CLI입니다. DOM, 콘솔, 네트워크, React 파이버, 바이탈 등 프레임워크에 구애받지 않는 브라우저 정보를 알고 있습니다. 사용하기 전에agent-browser skills get core를 한 번 실행하여 버전에 맞는 사용법 가이드를 확인하세요. 서브커맨드를 기억에서 추측하지 마세요.
두 뷰는 서로 교차 검증합니다.
필요 조건
- Turbopack을 사용하는 Next.js 16.3+ —
/_next/mcp와get_compilation_issues를 통한 사전 컴파일 검사. agent-browser>= 0.31.1 — React 내부 검사, 작업 트리 범위의session id, 멱등성--restore, 런치 플래그 조정.
이는 권장사항이 아닌 엄격한 최소 요구 사항입니다. 누락된 것이 있으면 사용자에게 업그레이드 방법을 알리고 중단하세요. 소스 코드를 grep하거나 약한 프로브로 대체하지 마세요 — 이 스킬은 두 뷰가 위 버전에서 모두 활성화되어 있다고 가정합니다.
- Next.js 업그레이드:
pnpm next upgrade(또는npx next upgrade). 문서: https://nextjs.org/docs/app/getting-started/upgrading (버전 16 가이드: https://nextjs.org/docs/app/guides/upgrading/version-16) agent-browser설치 또는 업그레이드:npm i -g agent-browser@latest. CLI가PATH에 없으면 계속 진행하기 전에 설치하세요 — 사전 점검에서 직접 호출할 것으로 예상합니다.
사전 점검
세션당 한 번, 두 뷰가 모두 활성화되어 있는지 확인합니다.
-
대상 URL에서
agent-browser를 열고, 저장된 로그인 상태가 있으면 복원합니다. 먼저 이 체크아웃에 대해 하나의 안정적인 세션 ID를 생성하고 모든agent-browser명령에 사용합니다:SESSION="$(agent-browser session id --scope worktree --prefix next-dev-loop)" export AGENT_BROWSER_SESSION="$SESSION" export AGENT_BROWSER_RESTORE="$SESSION"그런 다음 대상 URL을 엽니다:
agent-browser --session "$SESSION" --restore --headed --enable react-devtools open <url>--scope worktree는 병렬 작업 트리와 복사된 체크아웃이 충돌하는 것을 방지합니다. 기본--restore는 세션 ID를 지속성 키로 사용하고, 탐색 전에 저장된 쿠키/localStorage를 로드하며(있는 경우), 브라우저 종료 시 자동으로 상태를 저장합니다. 항상 원하는 런치 플래그를open에 전달하세요. agent-browser는 필요에 따라 범위가 지정된 백그라운드 상태를 재사용, 재실행 또는 재시작합니다.브라우저는 사용자의 것입니다. 상태가 복원되지 않았거나(첫 실행, 세션 만료) 페이지가 로그인으로 보호되어 있다면, 사용자가 로그인을 직접 수행합니다 — 확인할 때까지 기다리세요. 로그인 후에는 동일한 세션과 복원 컨텍스트를 계속 사용합니다.
agent-browser close는 쿠키 상태를 저장하므로 다음open에서 복원됩니다. -
/_next/mcp(tools/list)를 프로브합니다 — 연결 가능하고get_compilation_issues를 나열하는지 확인합니다:- 연결 불가 →
next dev가 실행 중이 아니거나 Next.js가 16.3 미만입니다.package.json을 확인하여 명확히 구분한 후 거부합니다. get_compilation_issues가 목록에 없음 → Next.js가 16.3 미만입니다. 거부하고 사용자에게 업그레이드하도록 알립니다.
- 연결 불가 →
-
get_compilation_issues는 Turbopack 프로브로도 사용됩니다. 오류 응답이"Turbopack project is not available..."이면 사용자가 webpack을 사용 중인 것입니다. 거부 — Turbopack이 필요합니다. -
get_routes→ 세션의 나머지 부분에 대한 라우트 맵입니다.
루프
편집 전 — 범위 좁히기
코드베이스가 아닌 실행 중인 앱에 물어보세요. /_next/mcp는 현재 라우트를 렌더링한 파일을 알고 있습니다. 이를 검색 범위로 사용하세요. 코드베이스가 커져도 런타임 내부 검사는 저렴합니다. 에이전트 검색은 그렇지 않습니다.
편집 후 — 확인
네 가지 실패 모드. 각각 확인하세요:
- 컴파일 —
get_compilation_issues. - 오류 없이 실행 —
/_next/mcp(서버 및 브라우저로 전파된 오류 모두 여기에서 표면화됩니다). - 의도한 대로 동작 —
agent-browser가 페이지를 구동합니다. 사용자가 실제로 보는 것을 확인하세요. - React 수준 동작 — react-devtools가 활성화된 상태에서
agent-browser는 컴포넌트 트리, props, 상태 및 렌더링 횟수를 노출합니다. 프레임워크 수준 검사(추가 렌더링, 서버/클라이언트 경계 이동, Suspense 폴백)는 여기에 고정하세요. DOM 어설션만으로는 이를 놓칩니다.
기억에서가 아니라 tools/list 또는 agent-browser 매뉴얼에서 특정 도구를 선택하세요.
주의사항
- 모든
agent-browser명령은 세션과 복원 키를 알고 있어야 합니다. 그렇지 않으면 빈 기본 브라우저를 사용하거나 로그인 상태 저장에 실패할 수 있습니다. 가장 쉬운 방법: agent-browser를 실행하는 각 셸의 상단에서AGENT_BROWSER_SESSION="$SESSION"및AGENT_BROWSER_RESTORE="$SESSION"을 모두 내보내세요. 내보내지 않으면 모든 명령에--session "$SESSION" --restore를 전달하세요. - 두 뷰가 일치하지 않으면 먼저 도구를 의심하세요.
agent-browser가 라우트가 깨졌다고 말하지만/_next/mcp와 서버는 깨끗하게 렌더링되었다고 말한다면, 실제 버그보다는 오래되었거나 잘못 지정된 브라우저 세션이 더 가능성 높은 원인입니다 — 앱을 디버깅하기 전에 뷰를 조정하세요. - 클릭 또는 탐색 확인: 페이지는 잠시 후에 안정화되므로
wait --load networkidle(잘못될 경로 없음)로 기다린 후, 스냅샷/읽기를 통해 페이지를 확인하세요. 링크의 정확한 href를 전달하지 않는 한wait --url은 피하세요 — 추측하거나 플레이스홀더 경로는 실제 URL과 일치하지 않으며 25초 후에 타임아웃됩니다. open직후 또는 클릭 후(심지어open이 페이지를 보고했다고 해도) 빈 읽기, 빈 스냅샷,about:blank또는 "no browser session" 오류는 브라우저가 페이지를 드롭한 것입니다(오래된 세션). 경로가 깨진 것이 아닙니다.--session "$SESSION" --restore를 사용하여 URL에서 세션을 다시 열고 다시 스냅샷을 찍으세요. 여전히 비어 있으면agent-browser --session "$SESSION" --restore close를 실행한 후 다시 여세요.curl로 대체하지 마세요. 테스트 중인 브라우저를 우회합니다.- React 내부 검사 출력은 탐색 후에 오래된 것입니다. 다시 실행하세요.
/_next/mcp응답은 SSE입니다.sed -n 's/^data: //p'를 사용하여data:줄에서 JSON을 읽으세요 (일반sed 's/^data: //'는event:줄을 남겨 구문 분석에 실패합니다).- 3000번이 아닌 dev 서버:
next dev배너를 읽고NEXT_MCP_URL=http://localhost:<port>/_next/mcp를 설정하세요. get_errors및get_page_metadata는 채워지기 위해 적어도 한 번의 탐색이 필요합니다.
참조
모든 아래 도구는 사전 점검이 통과되면 존재합니다. tools/list에 이 중 누락된 항목이 있으면 사전 점검이 거부했어야 합니다 — 다시 확인하세요.
# /_next/mcp 참고
get_project_metadata projectPath, devServerUrl, bundler
get_routes 파일 시스템 스캔; 브라우저 세션 불필요
get_errors 런타임 + 빌드; 브라우저 세션 필요; dev 서버가 포착한 브라우저 측 오류 포함
get_page_metadata 세그먼트 트라이 + routerType; 브라우저 세션 필요; 라우트를 제공하는 파일을 찾는 발견 바로 가기로 사용
get_logs logFilePath 반환
get_server_action_by_id 해시된 ID → 파일 + functionName
get_compilation_issues Turbopack 전용; webpack에서는 오류 발생("Turbopack project is not available")
종료
동일한 세션 및 복원 컨텍스트로 세션을 종료합니다: agent-browser --session "$SESSION" --restore close. close는 해당 세션의 쿠키와 저장소를 저장하여 다음 루프의 --restore open이 사용자를 로그인 상태로 유지합니다. 다음 루프를 위해 next dev는 실행 상태로 둡니다.
next-dev-loop-<topic> 관련 스킬(예: next-dev-loop-rsc, next-dev-loop-debug)은 이 사전 점검이 이미 실행되었다고 가정합니다. 루프부터 시작합니다.