Communitygithub.com

next-dev-loop

Next.js 앱 코드 편집 후 런타임 동작을 확인합니다. 컴파일이나 타입 체크뿐만 아니라 변경 사항이 실제 실행 중인 앱에서 제대로 작동하는지 확인할 때 사용하세요. /_next/mcp (Next.js 뷰)와 agent-browser (브라우저 뷰)를 결합합니다. next dev가 실행 중이어야 합니다.

next-dev-loop란 무엇인가요?

이 스킬은 Next.js 개발자가 next dev 환경에서 코드 변경 사항을 런타임에 실제로 검증할 수 있도록 설계된 전문 도구입니다. 단순한 컴파일 또는 타입 체크를 넘어, 두 가지 상호 보완적인 뷰(/_next/mcp 및 agent-browser)를 사용하여 애플리케이션의 동작을 최종 사용자 관점에서 확인합니다. /_next/mcp는 Next.js 16.3+의 Turbopack에서 제공하는 HTTP 엔드포인트로, 라우트, 서버 액션, RSC, 서버 로그 및 에러 등 프레임워크별 정보를 노출합니다. agent-browser는 실제 Chrome 브라우저를 제어하여 DOM, 콘솔, 네트워크, React 파이버 트리, 웹 바이탈 등 브라우저 수준의 정보를 수집합니다. 두 뷰를 교차 검증함으로써 개발자는 서버 측 문제와 클라이언트 측 문제를 정확히 분리하여 디버깅할 수 있습니다. 이 스킬은 특히 React 컴포넌트 트리, props, 상태, 렌더링 횟수와 같은 React 수준의 동작을 검사해야 할 때 유용하며, DOM만으로는 발견하기 어려운 여분의 리렌더링이나 서버/클라이언트 경계 이동 문제를 포착할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add https://github.com/0n6k4v-Coder/skills/tree/HEAD/next.js/next-dev-loop

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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하거나 약한 프로브로 대체하지 마세요 — 이 스킬은 두 뷰가 위 버전에서 모두 활성화되어 있다고 가정합니다.

사전 점검

세션당 한 번, 두 뷰가 모두 활성화되어 있는지 확인합니다.

  1. 대상 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에서 복원됩니다.

  2. /_next/mcp(tools/list)를 프로브합니다 — 연결 가능하고 get_compilation_issues를 나열하는지 확인합니다:

    • 연결 불가 → next dev가 실행 중이 아니거나 Next.js가 16.3 미만입니다. package.json을 확인하여 명확히 구분한 후 거부합니다.
    • get_compilation_issues가 목록에 없음 → Next.js가 16.3 미만입니다. 거부하고 사용자에게 업그레이드하도록 알립니다.
  3. get_compilation_issues는 Turbopack 프로브로도 사용됩니다. 오류 응답이 "Turbopack project is not available..."이면 사용자가 webpack을 사용 중인 것입니다. 거부 — Turbopack이 필요합니다.

  4. 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)은 이 사전 점검이 이미 실행되었다고 가정합니다. 루프부터 시작합니다.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

0n6k4v-Coder/skills

Translates Figma motion and animations into production-ready application code. Use when implementing animation/motion from a Figma design — user mentions "implement this motion", "add animation from Figma", "animate this component", provides a Figma URL whose node is animated, or when `get_design_context` returns motion data or instructs you to call `get_motion_context`.

0n6k4v-Coder/skills

Motion / animation context for the `use_figma` MCP tool — animating Figma nodes via manual keyframes, animation styles, easing, and timeline duration. Load alongside figma-use whenever a task involves adding, editing, or inspecting animation on a node.

0n6k4v-Coder/skills

Generate motion specification annotations from After Effects timeline data. Use when the user mentions "motion", "motion spec", "animation spec", "timeline", or wants to document a component's animation properties.

0n6k4v-Coder/skills

Turn on Cache Components in a Next.js app and resolve the blocking routes it surfaces. Use when the user wants to enable, adopt, or migrate to Cache Components, flip the `cacheComponents` flag, work through a flood of blocking-prerender / instant validation errors, run the `cache-components-instant-false` codemod, or decide between opting routes out with `export const instant = false` and fixing them in place.

0n6k4v-Coder/skills

Optimize a Next.js app that has `cacheComponents: true` — either the static shell on first paint, or the in-app navigation between routes. Picks the matching diagnostic loop and runs it.

관련 스킬