AI에게 fetch 로직을 고쳐달라고 했다. 타입도 통과했고, 컴포넌트도 렌더링됐다. 그런데 프로덕션에 올리자마자 빈 페이지가 떴다. AI가 틀린 게 아니다. AI는 파일 안에서 완벽하게 작동했다. 문제는 파일 바깥, 즉 레포 전체의 맥락을 AI가 보지 못했다는 데 있다.
dev.to에 올라온 What AI Still Misses in Production Next.js Apps는 이 불편한 진실을 12가지 구체적인 사례로 풀어낸다. 모노레포 루트 설정 오류, NEXT_PUBLIC_*에 서버 시크릿을 노출하는 실수, output: "export" 정적 빌드에 API 라우트를 추가하는 패턴, 로컬 프록시가 프로덕션에선 존재하지 않는 문제까지. 공통점이 있다. AI는 파일을 고쳤지만, 배포 모델·환경 레이어·서버/클라이언트 경계라는 '시스템 컨텍스트'는 한 번도 확인하지 않았다.
그런데 왜 AI는 이런 것들을 놓칠까. 또 다른 글 Why Your Prompt Is Only 5% of What the Model Sees가 그 구조적 이유를 설명한다. 프로덕션 AI 시스템에서 사용자의 실제 프롬프트가 전체 컨텍스트 윈도우에서 차지하는 비중은 5%에 불과하다. 나머지 95%는 시스템 프롬프트, 검색된 문서, 대화 히스토리, 툴 실행 결과로 채워진다. Cursor가 "Add error handling to this function"이라는 일곱 단어를 받았을 때 실제로 모델이 보는 건 현재 파일, 관련 임포트 타입, 프로젝트 구조, 최근 수정 내역, 터미널 에러 메시지까지 포함한 2,000~5,000 토큰짜리 문서다.
여기서 핵심 통찰이 나온다. Cursor가 프로젝트에 맞는 코드를 잘 쓰는 건 모델이 더 똑똑해서가 아니다. 컨텍스트 구성이 더 정교하기 때문이다. 모델의 가중치는 변하지 않는다. 바뀌는 건 오직 컨텍스트다. 그러므로 AI 코딩 도구가 Next.js 프로덕션에서 반복 실수를 저지를 때, 우리가 먼저 물어야 할 질문은 "이 모델이 충분히 좋은가"가 아니라 "내가 충분한 컨텍스트를 제공했는가"여야 한다.
두 기사를 교차해서 읽으면 실용적인 처방이 보인다. AI에게 Next.js 작업을 요청할 때 놓치지 말아야 할 컨텍스트 레이어는 최소 세 가지다.
첫째, 배포 모델(Deployment Model). output: "export"인지, Node 서버인지, Edge Runtime인지를 명시해야 한다. AI는 로컬 dev 서버 기준으로 API 라우트를 제안하지만, 정적 배포 환경에서 그 라우트는 빌드 후 사라진다. .cursor/rules 혹은 AGENTS.md에 배포 타깃을 한 줄로 고정해두는 것만으로도 이 류의 실수를 차단할 수 있다.
둘째, 환경 변수 레이어(Env Layer). NEXT_PUBLIC_ 접두사의 의미—빌드 타임에 번들에 인라인된다는 사실—를 컨텍스트로 주입해야 한다. 시스템 프롬프트나 프로젝트 룰에 "서버 전용 시크릿은 절대 NEXT_PUBLIC_ 접두사를 사용하지 않는다"는 제약을 명시하면, AI는 그 확률 공간에서 아예 벗어나지 않는다.
셋째, 서버/클라이언트 경계(Server-Client Boundary). "use client" 컴포넌트에서 임포트 가능한 파일과 서버 전용 파일을 명확히 분리한 구조를 컨텍스트로 제공해야 한다. AI가 lib 파일을 리팩토링할 때 이 경계를 모르면, 서버 코드가 클라이언트 번들에 섞이는 사고가 발생한다.
이 접근법은 단순히 "프롬프트를 더 잘 쓰자"는 이야기가 아니다. Why Your Prompt Is Only 5% 기사가 제안하는 '컨텍스트 엔지니어링' 패러다임의 핵심은 사용자의 메시지가 아니라 모델이 보는 전체 입력 시스템을 설계 대상으로 삼는 것이다. 역할, 태스크, 도메인 지식, 포맷, 제약—이 다섯 레이어를 체계적으로 구성할수록 같은 모델이 완전히 다른 결과를 낸다. Next.js 프로젝트의 경우, 이 지식 레이어에 배포 설정, 환경 변수 규칙, 서버/클라이언트 경계가 명시적으로 포함돼야 한다.
시사점은 개발 워크플로우로 직결된다. AI 코딩 도구를 쓰는 팀이라면 지금 당장 세 가지를 점검해볼 만하다. 프로젝트 루트의 .cursorrules 혹은 CLAUDE.md에 배포 환경이 명시돼 있는가. 환경 변수 사용 규칙이 AI가 읽을 수 있는 형태로 문서화돼 있는가. 서버/클라이언트 파일 분리 구조가 디렉토리 레벨에서 강제되고 있는가. 이 세 가지가 없다면, AI는 매번 가장 일반적인 확률 공간에서 답을 꺼내올 것이고, 그 답은 로컬에선 작동하지만 프로덕션에선 깨질 가능성이 높다.
전망은 긍정적이다. 컨텍스트 엔지니어링이 하나의 명확한 패러다임으로 자리 잡으면서, Next.js 프로젝트 템플릿 자체에 AI용 컨텍스트 파일이 기본 포함되는 흐름이 만들어질 것이다. 이미 일부 팀은 AGENTS.md에 프레임워크 버전, 배포 타깃, 환경 변수 규칙, 금지된 패턴을 명시하는 관행을 도입하고 있다. AI가 더 좋아지길 기다리기보다, AI가 보는 세계를 더 정확하게 설계하는 팀이 프로덕션 버그에서 먼저 자유로워진다. 결국 AI의 실력 문제가 아니라, 우리가 제공하는 컨텍스트의 설계 문제다.