Next.js 16.2: AI 개선사항

Next.js 16.2: AI Improvements

📅 2026-03-29 📰 Next.js Blog

요약

Next.js 16.2는 AI 에이전트 개발을 위한 여러 기능을 추가했습니다. create-next-app에 AGENTS.md 파일을 포함시켜 AI가 버전 맞춘 문서에 즉시 접근할 수 있으며(100% 평가 통과율 달성), 브라우저 로그 포워딩으로 터미널에서 클라이언트 에러를 볼 수 있고, Dev Server Lock File로 중복 시작 방지, 실험적 next-browser로 에이전트가 React DevTools와 Next.js 진단에 접근할 수 있습니다.

핵심 포인트

AGENTS.md 파일이 create-next-app에 기본으로 포함되어, AI 에이전트가 `node_modules/next/dist/docs/` 경로에서 번들된 문서에 접근할 수 있습니다. 연구 결과 번들된 문서 제공이 외부 검색 기반 방식(79% 통과율)보다 우수하여 100% 평가 통과율을 달성했습니다. 문서는 평문 Markdown 형식으로 제공되어 버전 일치성을 보장합니다.
Browser Log Forwarding으로 브라우저 에러가 개발 중 터미널로 자동 전달되며, `logging.browserToTerminal` 설정으로 'error'(기본), 'warn', true(모든 콘솔 출력), false(비활성화)를 선택할 수 있습니다. AI 에이전트는 브라우저 콘솔에 접근할 수 없으므로 이 기능이 특히 유용합니다.
Dev Server Lock File은 `.next/dev/lock` 경로에 실행 중인 개발 서버의 PID, 포트, URL을 저장하여, 두 번째 next dev 프로세스 시작 시 'Another next dev server is already running' 에러와 함께 PID와 URL을 표시합니다. AI 에이전트가 이 정보로 기존 프로세스를 자동 중단하거나 연결할 수 있습니다.
@vercel/next-browser는 실험적 CLI로, 에이전트가 셸 명령으로 스크린샷, 네트워크 요청, 콘솔 로그뿐만 아니라 React DevTools의 컴포넌트 트리·props·hooks, Next.js dev 오버레이의 Partial Prerendering 셸과 에러 등 프레임워크 특화 정보에 구조화된 텍스트로 접근할 수 있습니다.
next-browser는 지속적인 브라우저 세션에 대해 일회성 명령 기반으로 작동하므로, AI가 브라우저 상태 관리 없이 반복해서 앱을 조회할 수 있으며, 이는 브라우저를 추론 가능한 도구로 전환합니다.

왜 중요한가

AGENTS.md를 통한 100% 평가 통과율 달성과 AI 에이전트의 터미널 기반 디버깅·진단 지원은 자동화된 개발 워크플로우에서 AI의 효율성과 정확성을 획기적으로 향상시킵니다.

📄 전문 번역

Next.js 16.2: AI 개발을 위한 개선 사항들

Next.js 16.2에서는 AI 어시스턴트 개발을 염두에 두고 여러 기능을 개선했습니다. 이제 AI 에이전트가 프로젝트를 더 잘 이해하고, 터미널에서 직접 문제를 디버깅하며, 실행 중인 앱을 검사할 수 있게 됐거든요. 브라우저를 열 필요도 없습니다.

주요 개선 사항

AI 기반 create-next-app: 바로 사용할 수 있는 프로젝트 스캐폴딩
브라우저 로그 포워딩: 브라우저 에러를 터미널로 전달해 AI 디버깅 지원
개발 서버 락 파일: 두 개의 개발 서버가 동시에 시작되는 문제 해결
실험 중인 Agent DevTools: AI 에이전트에 React DevTools와 Next.js 진단 도구 접근 권한 제공

AI 기반 create-next-app

이제 create-next-app으로 새 프로젝트를 만들면 기본적으로 AGENTS.md 파일이 포함됩니다. 이 파일을 통해 AI 코딩 에이전트가 프로젝트 시작 단계부터 버전에 맞는 Next.js 문서에 접근할 수 있어요.

우리가 AGENTS.md에 대해 연구한 결과가 흥미로웠는데요. 에이전트에게 번들로 포함된 문서를 제공했을 때 Next.js 평가에서 100% 통과율을 달성했습니다. 반면 기술 기반 접근법은 최대 79% 수준에 머물렀거든요. 핵심 인사이트는 이겁니다. 에이전트는 필요할 때만 검색하는 방식보다는 항상 접근 가능한 문서가 있을 때 훨씬 잘 작동한다는 점이에요.

AGENTS.md 파일은 단순한 지시문입니다. 코드를 작성하기 전에 node_modules/next/dist/docs/에 번들로 포함된 문서를 먼저 읽도록 에이전트에게 알려주는 거죠. Next.js npm 패키지에 전체 문서가 마크다운 파일로 포함되어 있어서, 에이전트는 외부 데이터를 가져올 필요 없이 로컬에서 정확한 버전의 문서를 참조할 수 있습니다.

기존 프로젝트에 추가하는 방법

Next.js 16.2 이상이라면 문서가 이미 next 패키지에 포함되어 있습니다. 프로젝트 루트에 이 두 파일을 추가하세요.

<!-- AGENTS.md -->
<!-- BEGIN:nextjs-agent-rules -->
# Next.js: ALWAYS read docs before coding
Before any Next.js work, find and read the relevant doc in `node_modules/next/dist/docs/`. Your training data is outdated — the docs are the source of truth.
<!-- END:nextjs-agent-rules -->

주석 마커는 Next.js가 관리하는 섹션을 구분합니다. 마커 바깥에는 프로젝트 특화 지시사항을 추가해도 됩니다. 나중에 업데이트할 때는 마커 사이의 내용만 교체될 테니까요.

Claude Code용 instruction 파일인 CLAUDE.md에는 @ 지시어로 AGENTS.md를 추가 컨텍스트로 포함시킵니다.

<!-- CLAUDE.md -->
@AGENTS.md

더 오래된 버전을 사용 중이라면 codemod로 자동 생성할 수 있습니다.

npx @next/codemod@latest agents-md

더 자세한 내용은 [AI 에이전트 설정 가이드](https://nextjs.org/docs/app/building-your-application/guides/agents)를 참고하세요.

브라우저 로그 포워딩

이제 Next.js는 개발 중에 브라우저 에러를 기본적으로 터미널로 전달합니다. 브라우저 콘솔을 열지 않고도 클라이언트 사이드 에러를 볼 수 있게 된 거예요. 주로 터미널을 통해 작동하는 AI 에이전트에게 특히 유용합니다.

기본적으로는 에러만 터미널로 전달되지만, next.config.ts의 logging.browserToTerminal 옵션으로 수준을 조절할 수 있습니다.

// next.config.ts
const nextConfig = {
  logging: {
    browserToTerminal: true,
    // 'error' — 에러만 (기본값)
    // 'warn' — 경고와 에러
    // true — 모든 콘솔 출력
    // false — 비활성화
  },
};

export default nextConfig;

개발 서버 락 파일

Next.js는 이제 실행 중인 개발 서버의 PID, 포트, URL을 .next/dev/lock 파일에 저장합니다. 같은 프로젝트 디렉토리에서 두 번째 next dev 프로세스가 시작되면, Next.js가 락 파일을 읽고 실행 가능한 에러 메시지를 출력합니다.

Error: Another next dev server is already running.
- Local: http://localhost:3000
- PID: 12345
- Dir: /path/to/project
- Log: .next/dev/logs/next-development.log

Run kill 12345 to stop it.

AI 코딩 에이전트는 서버가 이미 실행 중인지 확인하지 않고 next dev를 시작하려는 경우가 자주 있는데요. 이렇게 구조화된 에러 메시지가 있으면 에이전트가 자동으로 기존 프로세스의 PID를 종료하거나 해당 URL에 연결할 수 있게 되어 수동 개입이 필요 없어집니다.

락 파일은 두 개의 next build 프로세스가 동시에 실행되는 것도 방지하므로, 빌드 산출물이 손상되는 문제도 예방할 수 있어요.

실험 중인 Agent DevTools

위의 기능들이 에이전트의 프로젝트 이해와 문제 디버깅을 돕는다면, @vercel/next-browser는 실행 중인 Next.js 애플리케이션을 검사하는 기능을 추가합니다.

next-browser는 실험 단계의 CLI 도구입니다. 스크린샷, 네트워크 요청, 콘솔 로그 같은 브라우저 수준의 데이터뿐 아니라 React DevTools와 Next.js dev overlay에서 얻을 수 있는 컴포넌트 트리, props, hooks, Partial Prerendering(PPR) 셸, 에러 같은 프레임워크 특화 정보를 구조화된 텍스트 형태로 셸 커맨드를 통해 반환합니다.

LLM은 DevTools 패널을 읽을 수 없습니다. 하지만 next-browser tree를 실행하고 그 출력을 파싱한 후 다음에 뭘 검사할지 결정할 수 있죠. 각 커맨드는 지속되는 브라우저 세션에 대한 일회성 요청이므로, 에이전트는 브라우저 상태를 관리할 필요 없이 앱을 반복적으로 조회할 수 있습니다. 이제 브라우저는 에이전트가 접근할 수 없는 UI가 아니라 추론할 수 있는 대상이 되었어요.

현재 가능한 기능

이 기능 세트는 계속 진화 중입니다.

🔗 원문 보기 👍 유용해요