next-cache-components-optimizer
두 개의 루프로 구성되며, 공유 도구와 기본 요소를 사용하지만 각각 다른 진단을 수행합니다:
- 페이지-렌더 루프 (ppr-loop.md) — 단일 페이지의 정적 셸을 확장합니다. 셸 전용 렌더링에서 Suspense 대체 영역 순위를 매깁니다.
- 네비게이션 루프 (instant-nav-loop.md) — 사용자가 A에서 B로 링크를 클릭할 때 B의 데이터가 해결될 때까지 A의 UI를 유지하는 대신 B의 정적 레이아웃(크롬, 구조, 콘텐츠 형태의 대체 영역)을 즉시 표시합니다.
pushstate후 B의 일시 중단된 경계를 캡처하고, 각각을suspended_by[].name으로 분류하며, SSR 전용 클라이언트 훅을 제거합니다.
하나를 선택하여 처음부터 끝까지 실행합니다.
요구 사항
- 이 세션을 위해
next-dev-loop이 시작되어 있어야 합니다. 헤드 브라우저를 열고,agent-browserCLI를 노출하며,mcp get_logs를 제공하는 개발 MCP 서버를 연결합니다. next.config.ts에cacheComponents: true가 설정되어 있어야 합니다. 그렇지 않으면 거부합니다.
사전 점검 (공유)
cacheComponents: true를 확인합니다.- 사용자는 (
next-dev-loop의) 헤드 브라우저에서 각 루프가 필요로 하는 페이지에 이미 접속해 있어야 합니다 — 로그인되고 필요한 상태가 설정된 상태여야 합니다. 이 스킬은 인증, SSO 또는 MFA를 처리할 수 없습니다. 수동 설정을 시작점으로 간주합니다. (각 하위 루프는 필요한 페이지를 지정합니다.) agent-browser get url로 현재 라우트를 고정합니다.
각 루프는 필요에 따라 인스턴트 쿠키를 설정합니다 (아래 공유 인스턴트 쿠키 섹션 참조).
인스턴트 쿠키 (공유)
두 루프 모두 next-instant-navigation-testing 쿠키를 사용하여 프레임워크의 동적 데이터 쓰기를 고정합니다. 설정되면 페이지의 표시 콘텐츠는 정적 셸 + Suspense 대체 영역입니다. 이것이 최적화를 평가하기 위해 캡처하는 내용입니다.
보류-잠금 튜플 [0, "<고유-id>"]로 설정합니다. id는 고유한 문자열이며, 관례적으로 동시 범위가 충돌하지 않도록 p 접두사가 붙은 무작위 스탬프를 사용합니다:
agent-browser cookies set next-instant-navigation-testing '[0,"p<random>"]' \
--url <원본>
각 루프의 사전 점검은 흐름 내에서 언제 설정할지 지정합니다. 마지막에 삭제합니다 (아래 종료 참조).
루프 결정
- 페이지-렌더: 한 라우트의 초기 로드에 대한 문제일 때. ppr-loop.md를 읽습니다.
- 네비게이션: 두 라우트 간의 탐색에 대한 문제일 때. instant-nav-loop.md를 읽습니다.
모호한 경우 → 사용자에게 질문합니다.
공유 리팩터링 수단
- Push down — I/O를 Suspense로 감싸인 자식 컴포넌트로 추출하여 부모가 정적 상태를 유지하고 정적 형제가 셸로 올라가도록 합니다.
- 재귀적으로 적용하고, 무작정 감싸지 마십시오. 이미 정적 콘텐츠와 I/O를 모두 포함하는 컴포넌트를 Suspense 경계가 감싸고 있다면, 내부를 읽고 I/O에 의존하는 JSX를 새 리프로 추출한 후 정적 형제를 위로 올립니다.
- 캐시 —
'use cache'+cacheLife(<프로파일>). 항상 사용자에게 신선도를 묻고, 사전 설정(seconds/minutes/hours/days/weeks/max/default)에 매핑합니다.
Push-down과 캐시는 함께 구성됩니다: push-down은 정적 구조를 끌어올리고, 캐시는 남은 데이터 격차를 제거합니다.
계획 모드를 통한 제안 (공유)
각 리팩터링은 적용 전에 계획 모드를 거칩니다. 이것을 신호로 간주하십시오: 실제 작업은 템플릿 편집이 아니라 중요한 에이전틱 엔지니어링입니다. 이 스킬은 프레임워크(어떤 수단을 사용할지, 어떤 대상을 수정할지, 예상되는 시각적 변화는 무엇인지)를 제공하지만, 실제 작업(어떤 파일을 편집할지, I/O를 어떻게 깔끔하게 추출할지, 새로운 Suspense 경계를 어디에 배치할지, 어떤 cacheLife 프로파일을 사용자에게 물어볼지)은 사용자가 판단해야 합니다. 계획 모드는 코드를 건드리기 전에 일관된 제안을 강제하고, 사용자가 이러한 결정에 대해 방향을 수정할 기회를 제공합니다.
셸 없는 경우의 처리 (공유)
이 수단들은 확장하거나 캐시할 셸이 존재한다고 가정합니다. 라우트가 완전히 차단된 경우(HTTP 500 + blocking-route 또는 mcp get_logs에서 NEXT_STATIC_GEN_BAILOUT, 또는 시각적으로 렌더링된 페이지에 Suspense 경계가 0개인 경우) 셸이 없습니다. 구조적 차단기를 표면화하고 중단하십시오. 사용자가 각 루프가 도움을 주기 전에 문제가 되는 동적 접근을 <Suspense>로 감싸야 합니다.
검증에는 시각적 변화가 필요함 (공유)
각 루프는 변경을 적용하기 전에 셸의 기준 스크린샷을 캡처한 후, 변경 후 다시 스크린샷을 캡처합니다. 최종 요약에서 두 경로를 모두 보고하여 사용자가 무엇이 변경되었는지 확인할 수 있게 합니다. 두 캡처는 시각적으로 달라야 합니다 — 대체 영역이 줄어듦, 콘텐츠가 정적 표면으로 승격됨, 대상 대체 영역이 사라지거나 콘텐츠 형태로 변경됨. 동일해 보이는 캡처는 리팩터링이 적용되지 않았음을 의미합니다. 실행 취소하십시오. "컴파일이 깔끔하게 성공함"은 기준이 아닙니다.
각 스크린샷 전에 개발 오버레이를 숨깁니다. Next.js 개발 오버레이(<nextjs-portal> at the document root)는 인스턴트 네비게이션 안내, 빌드 오류 및 기타 개발 크롬을 렌더링하여 전후 비교를 오염시킵니다. 숨기고, 스크린샷을 찍고, 복원합니다:
agent-browser eval "document.querySelector('nextjs-portal').style.display='none'"
agent-browser screenshot <경로>
agent-browser eval "document.querySelector('nextjs-portal').style.display=''"
안티 패턴 (공유)
세분화된 Suspense 경계를 최상위 로딩 스켈레톤으로 대체하지 마십시오. 전체 세그먼트에 대한 loading.tsx 또는 루트 레벨 <Suspense fallback={<Skeleton />}>(또는 더 나쁜 경우 UI를 빈 화면으로 만드는 fallback={null})는 이 스킬의 최적화를 무효화합니다. 이 스킬의 목표는 각 세분화된 경계 위에 실제 정적 크롬을 추출하고 영역별로 콘텐츠 형태의 대체 영역을 사용하는 것입니다. 조잡한 "페이지 로딩 중" 대체는 작업을 완전히 우회합니다.
주의사항 (공유)
- Dev는 프로덕션처럼 프리페치하지 않으며, 라우트는 첫 번째 히트 시 컴파일됩니다. 따라서 탐색 또는 새로고침 후 DOM은 최종 프로덕션 경험보다 눈에 띄게 오래 업데이트됩니다. React 트리를 캡처하거나 스크린샷을 찍기 전에 DOM이 안정될 때까지 인내심 있게 기다리십시오. 예를 들어,
document.documentElement.innerHTML.length를 폴링하여 두 번 연속 읽기에서 변경되지 않을 때까지 기다립니다. 고정된 짧은 지연은 렌더링 중간에 샘플링할 위험이 있습니다. - Dev 네트워크 트래픽을 검사하여 네비게이션 프리페치를 확인하려고 하지 마십시오. Dev는 프리페치 요청을 전혀 보내지 않으므로, 네트워크 탭, 수동
router.prefetch()호출 및<Link prefetch={true}>는 코드가 올바른지 여부와 관계없이 모두 손상된 것처럼 보입니다. instant-nav-loop.md의verify아래에 있는 쿠키-잠금 SPA-네비게이션 레시피는 이미 이에 대한 표준 레시피입니다. 프리페치가 실제로 실행될 필요 없이 프로덕션이 프리페치된 RSC에 프리렌더링할 내용을 시뮬레이션합니다. 이 레시피를 사용하고 네트워크 탭 대안을 발명하지 마십시오. - 진단 파이프라인은 불안정할 수 있습니다. DevTools 연결 타이밍, DOM 안정화 경쟁 및 개발 컴파일 효과는 각각 실행마다 일관되지 않은 캡처를 생성할 수 있습니다. 결과가 이상하다고 느껴지면(예상치 못한 후보가 나타나거나 예상한 후보가 나타나지 않는 경우) 진단을 2~3회 다시 실행하고 교차 확인하십시오. 일관되게 나타나는 경계는 실제이고, 한 번 나타나는 것은 노이즈입니다.
참조 (공유 기본 요소)
agent-browser react suspense add --only-dynamic to filter
--json server-side to actually-
suspended boundaries. Each
entry has jsx_source +
suspended_by[] with raw blocker
names (usePathname, cookies,
fetch, cache, ...); classify by
name for per-loop rules
POST /__nextjs_original-stack-frames body { frames: StackFrame[],
isServer, isEdgeServer,
isAppDirectory }; returns one
result per frame with
file:line:column
mcp get_logs dev MCP tool from
next-dev-loop; surfaces
blocking-route /
NEXT_STATIC_GEN_BAILOUT 500s
cacheLife('<profile>') default | seconds | minutes
| hours | days | weeks | max
루프별 기본 요소는 instant-nav-loop.md에 있습니다.
종료 (공유)
이름으로 쿠키를 삭제합니다 — 만료된 스탬프로 덮어씁니다:
agent-browser cookies set next-instant-navigation-testing x \
--url <원본> --expires 1
절대 agent-browser cookies clear(인수 없음)를 사용하지 마십시오 — auth가 삭제됩니다.
next-dev-loop의 형제입니다. 먼저 시작하십시오.