Next.js AI 세팅

설치 버전과 문서 확인

프로젝트 폴더에서 아래를 실행합니다.

cd C:\Projects\my-first-app
npm list next react react-dom
node --version
Test-Path node_modules\next\dist\docs

2026-10-23 npm 기준 Next.js·create-next-app latest는 16.4.2입니다. 이미 설치한 앱에서는 이 숫자를 강제로 맞추기보다 package-lock.json과 실제 설치 버전에 맞는 문서를 읽습니다.

Next.js AI agents.

AGENTS.md와 CLAUDE.md

현재 버전의 create-next-app이 생성했거나 next dev가 관리하는 AGENTS.md를 확인합니다. AI agent 감지 시 관리 지침이 생성·갱신되며 기본 활성화는 16.3+입니다.

<!-- BEGIN:nextjs-agent-rules -->
... Next.js가 생성한 버전별 문서 안내 ...
<!-- END:nextjs-agent-rules -->

## 프로젝트 규칙
- UI 문구는 한국어로 작성한다.
- 설정을 바꾸기 전에 설치 버전의 로컬 문서를 확인한다.
- 변경 후 해당 화면과 오류를 확인하고 npm run build를 실행한다.

위 ...를 생성 파일에 덮어쓰지 않습니다. 관리 구간을 그대로 두고 밖의 규칙만 추가합니다. Next.js가 관리하는 파일도 프로젝트 변경으로 검토·커밋하면 매번 미추적 변경이 생기는 일을 줄일 수 있습니다.

Claude용 CLAUDE.md에는 다음처럼 연결합니다.

@AGENTS.md

개발 서버와 로그

별도 PowerShell 창에서 npm run dev를 실행합니다. 브라우저 경고·오류는 기본 'warn' 설정으로 개발 서버 터미널에 전달됩니다. 명시하려면 다음처럼 설정합니다.

import type { NextConfig } from 'next'

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

export default nextConfig

true는 일반 로그까지 전달하고 false는 전달을 끕니다. 이 기능은 개발용이며 production 관측 시스템의 대체재가 아닙니다.

logging reference.

Next.js MCP 연결

런타임의 오류·라우트·페이지 상태가 필요하면 프로젝트 .mcp.json에 공식 서버를 추가합니다.

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

개발 서버가 실행 중인지 확인하고 Claude Code에서 /mcp reconnect all로 다시 연결할 수 있습니다. 팀에서 재현 가능한 환경이 필요하면 검토한 MCP 버전을 고정합니다. 연결되지 않을 때는 실행 폴더·실제 포트·서버 로그·MCP 인증 상태를 확인합니다.

Next.js MCP guide.

기존 프로젝트는 별도 변경으로 다루기

1. git status, 현재 Node·Next·React 버전과 lockfile을 확인합니다.
2. 목표 버전의 공식 migration guide와 peer dependency 범위를 확인합니다.
3. 변경 브랜치에서 필요한 패키지만 갱신하고 codemod의 변경 내용을 검토합니다.
4. 로그인·데이터 변경·라우트·빌드와 실제 화면을 검증합니다.

16.1 이하의 문서 연결이 필요할 때만 legacy 명령을 검토합니다. 문서를 받는 작업이며 프레임워크 업그레이드를 대신하지 않습니다.

npx @next/codemod@canary agents-md

Upgrading · Next.js AI agents.

AI에게 요청할 내용

이 프로젝트에 설치된 Next.js 버전과 AGENTS.md를 먼저 확인해줘.
node_modules/next/dist/docs/의 관련 문서를 읽고 실행 중인 개발 서버의 오류를 점검해줘.
필요한 파일만 수정한 다음 브라우저 동작과 npm run build 결과를 알려줘.

참고 자료

Next.js AI agents · 설치 · Claude Code setup.