안녕하세요 여러분! 오늘은 최근 프론트엔드 개발 트렌드에서 빼놓을 수 없는 'AI 코딩 에이전트'를 우리 Next.js 프로젝트에 똑똑하게 연동하는 방법을 공식 문서를 통해 살펴볼게요.
Next.js는 next 패키지 안에 현재 버전에 딱 맞는 문서를 함께 제공(ship)하고 있어요. 이를 통해 AI 코딩 에이전트들이 정확하고 최신 상태인 API와 패턴들을 참조할 수 있게 해주죠. 여러분의 프로젝트 루트(최상위 폴더)에 있는 AGENTS.md 파일은 에이전트들에게 본인들의 과거 학습 데이터 대신, 이렇게 번들로 제공되는 문서를 기준으로 코드를 작성하라고 지시하는 역할을 한답니다.
💡 강사의 팁: 요즘 Cursor나 GitHub Copilot 많이들 쓰시죠? 그런데 AI가 가끔 예전 Page Router 시절의 구형 문법을 알려주거나, 없는 App Router 기능을 지어내는(할루시네이션) 경험 해보셨을 거예요. AI의 학습 데이터가 Next.js의 빠른 업데이트 속도를 못 따라가서 그런데요, 이 설정 하나면 AI가 우리 프로젝트에 설치된 '진짜' 최신 문서를 읽고 코드를 짜게 만들 수 있습니다. 실무에서 생산성을 확 끌어올릴 수 있는 엄청난 꿀팁이죠!
어떻게 동작하나요? (How it works)
여러분이 next를 설치하게 되면, Next.js 공식 문서가 node_modules/next/dist/docs/ 경로에 함께 묶여서(bundled) 들어오게 됩니다. 이 번들된 문서들은 실제 Next.js 공식 문서 사이트의 구조를 그대로 반영하고 있어요.
node_modules/next/dist/docs/
├── 01-app/
│ ├── 01-getting-started/
│ ├── 02-guides/
│ └── 03-api-reference/
├── 02-pages/
├── 03-architecture/
└── index.mdx이게 무슨 뜻이냐고요? 에이전트들이 네트워크 요청을 보내거나 외부에서 검색해볼 필요 없이, 여러분이 설치한 버전과 완벽하게 일치하는 문서에 항상 곧바로 접근할 수 있다는 뜻이에요!
프로젝트 루트에 있는 AGENTS.md 파일은 에이전트들에게 "코드 작성하기 전에 꼭 이 번들된 문서부터 읽어봐!"라고 말해주는 역할을 합니다. Claude Code, Cursor, GitHub Copilot 등등 대부분의 AI 코딩 에이전트들은 세션을 시작할 때 이 AGENTS.md 파일을 자동으로 읽어들이거든요.
👨🏫 강사의 부연 설명:
node_modules안에 공식 문서 마크다운 파일들이 통째로 들어있다는 게 핵심입니다. 외부 인터넷 검색 없이 로컬 저장소에서 바로 읽어오니까 AI가 코드를 짜주는 속도도 훨씬 빠르고, 내용도 우리 프로젝트 버전에 꼭 맞아서 굉장히 정확해집니다.
시작하기 (Getting started)
새로운 프로젝트 (New projects)
create-next-app 명령어를 사용하면 AGENTS.md와 CLAUDE.md 파일이 자동으로 생성된답니다. 우리가 따로 추가적인 설정을 해줄 건 없어요! 아주 편하죠?
pnpm create next-app@canarynpx create-next-app@canaryyarn create next-app@canarybun create next-app@canary만약 에이전트 관련 파일들이 생성되는 게 싫다면, 명령어 뒤에 --no-agents-md 옵션을 붙여주시면 돼요.
npx create-next-app@canary --no-agents-md💡 강사의 팁: 명령어 끝에
@canary가 붙어있는 거 보이시죠? canary는 정식 배포 전의 최신 테스트 버전(Pre-release)을 의미해요. 이 AI 에이전트 연동 기능이 아주 따끈따끈한 최신 기능이라 아직은 카나리 버전에서 제공되고 있습니다. 개인 포트폴리오를 만들거나 새로운 기술을 빨리 써보고 싶을 때는 아주 좋지만, 현업에서 실제 사용자가 있는 프로덕션 환경에 카나리 버전을 바로 도입하는 건 예상치 못한 버그가 있을 수 있으니 주의하셔야 해요!
기존 프로젝트 (Existing projects)
기존에 작업하던 프로젝트에 적용하려면 현재 Next.js 버전이 v16.2.0-canary.37 이상인지 먼저 확인해주세요. 조건이 맞는다면, 프로젝트 루트 경로에 아래 파일들을 직접 추가해주시면 됩니다.
AGENTS.md 파일에는 에이전트들이 읽고 따르게 될 지시사항이 들어갑니다:
# 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.
CLAUDE.md 파일은 @ 임포트 문법을 사용해서 AGENTS.md의 내용을 그대로 가져와요. 이렇게 하면 파일 내용을 중복으로 작성할 필요 없이, Claude Code를 사용하는 분들도 동일한 AI 지침을 적용받을 수 있답니다.
@AGENTS.mdAGENTS.md 이해하기 (Understanding AGENTS.md)
기본적으로 제공되는 AGENTS.md에는 아주 명확하고 집중된 단 하나의 지시사항만 들어있어요. 바로 "코드를 작성하기 전에 번들된 문서를 먼저 읽어라"라는 것이죠. 이건 의도적으로 아주 짧게(minimal) 작성된 거예요. 주된 목적은 에이전트들이 오래된 과거의 학습 데이터에 의존하는 것을 막고, node_modules/next/dist/docs/에 있는 정확하고 버전이 일치하는 최신 문서를 보도록 방향을 틀어주는(redirect) 것이기 때문입니다.
파일 안을 보시면 와 라는 주석 마커가 있죠? 이 마커들이 바로 Next.js 프레임워크가 자체적으로 관리하는 영역을 구분해주는 역할을 해요. 이 마커 바깥쪽(위나 아래)에는 여러분 프로젝트만의 고유한 커스텀 지시사항을 얼마든지 추가하실 수 있어요. 나중에 Next.js가 업데이트되더라도 이 마커 밖의 내용은 덮어씌워지지 않으니 안심하셔도 됩니다!
👨🏫 강사의 부연 설명: 이 부분 정말 중요합니다. 저 마커 안쪽 코드는 나중에 Next.js 버전이 올라갈 때 자동으로 수정될 수 있으니 건드리지 마세요. 대신 마커 바깥 공간을 적극 활용하세요! 예를 들어 "우리 팀은 컴포넌트를 무조건 화살표 함수로 만들어", "상태 관리는 Zustand를 써줘", "Tailwind CSS 클래스 순서를 맞춰줘" 같은 여러분만의 코딩 컨벤션을 적어두면 AI가 우리 팀의 막내 개발자처럼 스타일을 찰떡같이 맞춰서 코드를 짜주게 됩니다.
번들로 제공되는 이 문서 안에는 App Router와 Pages Router에 대한 가이드, API 참조 문서, 그리고 각종 파일 규칙(file conventions)이 모두 들어있어요. 그래서 AI 에이전트가 라우팅, 데이터 패칭(data fetching), 혹은 다른 어떤 Next.js 관련 기능을 구현해야 할 때, 어설프거나 틀린 예전 지식에 의존하는 대신 여러분 로컬에 있는 번들 문서에서 정확한 최신 API를 찾아보고 코드를 작성할 수 있게 되는 겁니다.
알아두면 좋은 정보: 이렇게 번들된 문서와
AGENTS.md를 함께 썼을 때, 실제 Next.js 작업에서 AI 에이전트의 성능이 얼마나 눈에 띄게 좋아지는지 궁금하시죠? 벤치마크 결과 페이지를 방문해서 꼭 한번 수치를 확인해보세요. 체감이 확 되실 거예요.
다음 단계 (Next Steps)
- Next.js MCP 서버 (Next.js MCP Server)
- 코딩 에이전트들이 여러분의 애플리케이션 상태(state)에 직접 접근할 수 있도록 Next.js MCP 지원을 사용하는 방법을 배워보세요.
💡 강사의 팁: MCP(Model Context Protocol)는 요즘 프론트엔드와 AI 씬을 통틀어 가장 핫한 키워드 중 하나입니다. AI가 단순히 텍스트(코드)만 생성하는 걸 넘어서, 여러분의 로컬 개발 환경, 브라우저 상태 등과 직접 소통하게 해주는 기술이죠. 이 개념까지 잘 익혀두시면 앞으로 다가올 AI 네이티브 개발 시대에 정말 강력한 무기를 갖게 되실 겁니다!
모든 공식 문서에 대한 의미론적인 개요(semantic overview)를 한눈에 보고 싶으시다면, https://nextjs.org/docs/sitemap.md를 참고해주세요.
LLM이나 에이전트가 읽기 편하게 정리된, 사용 가능한 모든 문서의 전체 인덱스(목차)를 확인하시려면 https://nextjs.org/docs/llms.txt를 확인해보시면 됩니다.
