Next.js AI 세팅

Next.js 16.2의 AGENTS.md, 터미널 로그, MCP, next-browser를 Claude Code와 함께 설정합니다

핵심 요약

새 프로젝트의 AGENTS.md에는 BEGIN:nextjs-agent-rules 관리 구간이 있어야 하며, 이 영역은 건드리지 않고 프로젝트 규칙은 밖에 추가합니다.
CLAUDE.md의 @AGENTS.md 줄이 있어야 Claude Code가 설치된 Next.js 버전의 로컬 문서(node_modules/next/dist/docs/)를 함께 읽습니다.
next.config.ts의 logging.browserToTerminal을 'warn'으로 두면 브라우저 콘솔 경고·오류가 터미널로 넘어와 에이전트가 디버깅하기 쉬워집니다.
.mcp.json에 next-devtools-mcp를 등록하면 실행 중인 앱의 오류·로그·라우트·메타데이터를 구조화된 도구로 조회할 수 있습니다.
기존 프로젝트는 npm install next@latest로 올리고, 16.1 이하라면 npx @next/codemod@latest agents-md로 에이전트 파일을 생성합니다.

Next.js 16.2는 AI 코딩 에이전트가 프로젝트를 더 잘 이해하고 디버깅하도록 돕는 기능을 기본 흐름에 넣었습니다. 이 챕터에서는 새로 만든 프로젝트가 AI 친화적으로 준비됐는지 확인합니다.

먼저 확인할 것

PowerShell에서 프로젝트 폴더로 이동한 뒤 버전을 확인합니다:

cd C:\Projects\my-first-app
npm list next
node --version

항목	기준
Next.js	16.2.x 이상
Node.js	20.9 이상
프로젝트 파일	`AGENTS.md`, `CLAUDE.md`, `next.config.ts` 존재

새 프로젝트라면 대부분 이미 완료

create-next-app@latest 추천 기본값으로 만들었다면 AGENTS.md와 CLAUDE.md가 자동 생성됩니다. 이 챕터에서는 파일이 제대로 있는지 확인하고, Claude Code가 더 쉽게 디버깅하도록 선택 세팅을 덧붙입니다.

AGENTS.md 확인

프로젝트 루트의 AGENTS.md를 엽니다. 아래와 같은 Next.js 관리 구간이 있어야 합니다:

<!-- 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 -->

이 파일은 Claude Code, Cursor, GitHub Copilot 같은 AI 코딩 도구에게 설치된 Next.js 버전에 맞는 로컬 문서를 먼저 읽으라고 알려줍니다. 로컬 문서는 node_modules/next/dist/docs/에 있습니다.

관리 구간은 건드리지 마세요

BEGIN:nextjs-agent-rules와 END:nextjs-agent-rules 사이 내용은 Next.js가 관리하는 영역입니다. 프로젝트만의 규칙은 이 영역 밖에 추가하세요.

CLAUDE.md 연결 확인

CLAUDE.md에는 AGENTS.md를 불러오는 줄이 있어야 합니다:

@AGENTS.md

그 아래에 프로젝트 규칙을 추가하면 Claude Code가 Next.js 공식 문서와 우리 프로젝트 규칙을 함께 읽습니다:

@AGENTS.md

## Project Rules
- 한국어 UI 문구를 기본으로 사용한다.
- App Router와 Server Components를 기본으로 사용한다.
- 브라우저에서 보이는 오류는 먼저 개발 서버 터미널 로그를 확인한다.
- 변경 후 `npm run build`로 확인한다.

브라우저 로그를 터미널로 보내기

Next.js 16.2는 개발 중 브라우저 콘솔 로그를 터미널로 전달할 수 있습니다. AI 에이전트는 브라우저 개발자 도구를 직접 못 보니, 오류와 경고가 터미널에 찍히면 디버깅이 한결 쉬워집니다.

next.config.ts를 아래처럼 설정합니다:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  logging: {
    browserToTerminal: 'warn',
  },
}

export default nextConfig

값	동작
`'error'`	브라우저 오류만 터미널에 표시
`'warn'`	경고와 오류 표시
`true`	`console.log`까지 모두 표시
`false`	전달 끄기

초보자 추천값

처음에는 'warn'을 추천합니다. console.log가 너무 많으면 오히려 Claude Code가 중요한 오류를 놓치기 쉽습니다.

Next.js MCP 설정

MCP(Model Context Protocol)를 쓰면 Claude Code 같은 에이전트가 실행 중인 Next.js 앱의 오류, 로그, 라우트, 페이지 메타데이터를 구조화된 도구로 조회할 수 있습니다.

프로젝트 루트에 .mcp.json 파일을 만들고 아래 내용을 넣습니다:

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

그 다음 개발 서버를 실행합니다:

npm run dev

Claude Code를 다시 시작한 뒤 아래처럼 요청해 보세요:

현재 Next.js 앱의 오류와 라우트 상태를 MCP로 확인해줘.
문제가 있으면 원인과 수정 파일을 먼저 설명한 뒤 고쳐줘.

MCP가 연결되지 않을 때

Next.js 개발 서버가 켜져 있어야 합니다. .mcp.json을 추가한 뒤에는 Claude Code를 재시작하고, 이미 켜져 있던 npm run dev도 한 번 껐다가 다시 켜세요.

next-browser 실험 도구

next-browser는 AI 에이전트가 터미널 명령으로 실행 중인 Next.js 앱을 검사하게 돕는 실험 도구입니다. React 컴포넌트 트리, props, hooks, 네트워크 요청, 콘솔 로그, 스크린샷, PPR shell 분석을 구조화된 텍스트로 보여줍니다.

Claude Code에서 skill을 지원한다면 아래 명령으로 설치할 수 있습니다:

npx skills add vercel-labs/next-browser

설치 후 Claude Code에서 아래처럼 실행합니다:

/next-browser

이후에는 다음과 같이 요청할 수 있습니다:

localhost:3000을 열고 화면 오류, 콘솔 로그, 네트워크 요청을 확인해줘.
문제가 있으면 수정하고 다시 확인해줘.

실험 기능입니다

next-browser는 빠르게 바뀌는 실험 도구입니다. 설치나 명령어가 달라지면 Next.js 16.2 AI Improvements 글의 최신 안내를 확인하세요.

기존 프로젝트를 최신 AI 세팅으로 바꾸기

이미 만든 Next.js 프로젝트라면 먼저 최신 버전으로 올립니다:

npm install next@latest react@latest react-dom@latest

Next.js 16.1 이하 프로젝트라면 에이전트 파일을 자동 생성하는 codemod를 사용할 수 있습니다:

npx @next/codemod@latest agents-md

그 다음 아래를 확인합니다:

확인	명령 또는 파일
설치 버전	`npm list next`
로컬 문서	`node_modules/next/dist/docs/`
에이전트 지시	`AGENTS.md`
Claude 연결	`CLAUDE.md`의 `@AGENTS.md`
브라우저 로그	`next.config.ts`의 `logging.browserToTerminal`
MCP	`.mcp.json`의 `next-devtools-mcp`

AI에게 이렇게 요청하기

아래처럼 요청하면 Claude Code가 최신 Next.js 문서와 실행 중인 앱 상태를 함께 사용하기 쉽습니다:

이 프로젝트는 Next.js 16.2 App Router 프로젝트야.
코드를 쓰기 전에 AGENTS.md와 node_modules/next/dist/docs/에서 관련 문서를 먼저 확인해줘.
현재 개발 서버 오류, 브라우저 로그, 라우트를 확인한 뒤 최소 변경으로 수정해줘.

새 페이지를 만들기 전에 App Router의 page, layout, loading, error 파일 규칙을 로컬 Next.js 문서에서 확인해줘.
완료 후 npm run build까지 실행해서 결과를 알려줘.

참고 자료

핵심 요약

새 프로젝트의 AGENTS.md에는 BEGIN:nextjs-agent-rules 관리 구간이 있어야 하며, 이 영역은 건드리지 않고 프로젝트 규칙은 밖에 추가합니다.
CLAUDE.md의 @AGENTS.md 줄이 있어야 Claude Code가 설치된 Next.js 버전의 로컬 문서(node_modules/next/dist/docs/)를 함께 읽습니다.
next.config.ts의 logging.browserToTerminal을 'warn'으로 두면 브라우저 콘솔 경고·오류가 터미널로 넘어와 에이전트가 디버깅하기 쉬워집니다.
.mcp.json에 next-devtools-mcp를 등록하면 실행 중인 앱의 오류·로그·라우트·메타데이터를 구조화된 도구로 조회할 수 있습니다.
기존 프로젝트는 npm install next@latest로 올리고, 16.1 이하라면 npx @next/codemod@latest agents-md로 에이전트 파일을 생성합니다.

먼저 확인할 것

PowerShell에서 프로젝트 폴더로 이동한 뒤 버전을 확인합니다:

cd C:\Projects\my-first-app
npm list next
node --version

항목	기준
Next.js	16.2.x 이상
Node.js	20.9 이상
프로젝트 파일	`AGENTS.md`, `CLAUDE.md`, `next.config.ts` 존재

새 프로젝트라면 대부분 이미 완료

AGENTS.md 확인

프로젝트 루트의 AGENTS.md를 엽니다. 아래와 같은 Next.js 관리 구간이 있어야 합니다:

<!-- 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 -->

관리 구간은 건드리지 마세요

BEGIN:nextjs-agent-rules와 END:nextjs-agent-rules 사이 내용은 Next.js가 관리하는 영역입니다. 프로젝트만의 규칙은 이 영역 밖에 추가하세요.

CLAUDE.md 연결 확인

CLAUDE.md에는 AGENTS.md를 불러오는 줄이 있어야 합니다:

@AGENTS.md

그 아래에 프로젝트 규칙을 추가하면 Claude Code가 Next.js 공식 문서와 우리 프로젝트 규칙을 함께 읽습니다:

@AGENTS.md

## Project Rules
- 한국어 UI 문구를 기본으로 사용한다.
- App Router와 Server Components를 기본으로 사용한다.
- 브라우저에서 보이는 오류는 먼저 개발 서버 터미널 로그를 확인한다.
- 변경 후 `npm run build`로 확인한다.

브라우저 로그를 터미널로 보내기

next.config.ts를 아래처럼 설정합니다:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  logging: {
    browserToTerminal: 'warn',
  },
}

export default nextConfig

값	동작
`'error'`	브라우저 오류만 터미널에 표시
`'warn'`	경고와 오류 표시
`true`	`console.log`까지 모두 표시
`false`	전달 끄기

초보자 추천값

처음에는 'warn'을 추천합니다. console.log가 너무 많으면 오히려 Claude Code가 중요한 오류를 놓치기 쉽습니다.

Next.js MCP 설정

프로젝트 루트에 .mcp.json 파일을 만들고 아래 내용을 넣습니다:

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

그 다음 개발 서버를 실행합니다:

npm run dev

Claude Code를 다시 시작한 뒤 아래처럼 요청해 보세요:

현재 Next.js 앱의 오류와 라우트 상태를 MCP로 확인해줘.
문제가 있으면 원인과 수정 파일을 먼저 설명한 뒤 고쳐줘.

MCP가 연결되지 않을 때

Next.js 개발 서버가 켜져 있어야 합니다. .mcp.json을 추가한 뒤에는 Claude Code를 재시작하고, 이미 켜져 있던 npm run dev도 한 번 껐다가 다시 켜세요.

next-browser 실험 도구

Claude Code에서 skill을 지원한다면 아래 명령으로 설치할 수 있습니다:

npx skills add vercel-labs/next-browser

설치 후 Claude Code에서 아래처럼 실행합니다:

/next-browser

이후에는 다음과 같이 요청할 수 있습니다:

localhost:3000을 열고 화면 오류, 콘솔 로그, 네트워크 요청을 확인해줘.
문제가 있으면 수정하고 다시 확인해줘.

실험 기능입니다

next-browser는 빠르게 바뀌는 실험 도구입니다. 설치나 명령어가 달라지면 Next.js 16.2 AI Improvements 글의 최신 안내를 확인하세요.

기존 프로젝트를 최신 AI 세팅으로 바꾸기

이미 만든 Next.js 프로젝트라면 먼저 최신 버전으로 올립니다:

npm install next@latest react@latest react-dom@latest

Next.js 16.1 이하 프로젝트라면 에이전트 파일을 자동 생성하는 codemod를 사용할 수 있습니다:

npx @next/codemod@latest agents-md

그 다음 아래를 확인합니다:

확인	명령 또는 파일
설치 버전	`npm list next`
로컬 문서	`node_modules/next/dist/docs/`
에이전트 지시	`AGENTS.md`
Claude 연결	`CLAUDE.md`의 `@AGENTS.md`
브라우저 로그	`next.config.ts`의 `logging.browserToTerminal`
MCP	`.mcp.json`의 `next-devtools-mcp`

AI에게 이렇게 요청하기

아래처럼 요청하면 Claude Code가 최신 Next.js 문서와 실행 중인 앱 상태를 함께 사용하기 쉽습니다:

이 프로젝트는 Next.js 16.2 App Router 프로젝트야.
코드를 쓰기 전에 AGENTS.md와 node_modules/next/dist/docs/에서 관련 문서를 먼저 확인해줘.
현재 개발 서버 오류, 브라우저 로그, 라우트를 확인한 뒤 최소 변경으로 수정해줘.

새 페이지를 만들기 전에 App Router의 page, layout, loading, error 파일 규칙을 로컬 Next.js 문서에서 확인해줘.
완료 후 npm run build까지 실행해서 결과를 알려줘.

먼저 확인할 것

AGENTS.md 확인

CLAUDE.md 연결 확인

브라우저 로그를 터미널로 보내기

Next.js MCP 설정

next-browser 실험 도구

기존 프로젝트를 최신 AI 세팅으로 바꾸기

AI에게 이렇게 요청하기

참고 자료

목차

Next.js AI 세팅

먼저 확인할 것

AGENTS.md 확인

CLAUDE.md 연결 확인

브라우저 로그를 터미널로 보내기

Next.js MCP 설정

next-browser 실험 도구

기존 프로젝트를 최신 AI 세팅으로 바꾸기

AI에게 이렇게 요청하기

참고 자료

목차