AI 코딩 에이전트에게 최신 프레임워크 API를 가르치는 가장 좋은 방법은 무엇일까요? Vercel 팀은 “똑똑한” 방법과 “단순한” 방법을 비교했고, 예상을 뒤엎는 결과를 발견했습니다.

Vercel이 Next.js 16에서 AI 코딩 에이전트 성능 평가 결과를 발표했습니다. Skills라는 정교한 도구 시스템보다 AGENTS.md라는 단순한 파일 하나가 압도적으로 우수했습니다(53% → 100%). 에이전트가 제공된 도구를 사용하지 않는 현상과 지시문 문구 하나가 성능을 좌우하는 현실이 핵심입니다.

출처: AGENTS.md outperforms skills in our agent evals – Vercel

문제: AI는 최신 API를 모른다

AI 코딩 에이전트의 학습 데이터는 점점 낡아갑니다. Next.js 16에 새로 나온 'use cache', connection() 같은 API는 현재 모델이 학습한 적이 없죠. 그러면 에이전트는 잘못된 코드를 만들거나 옛날 방식으로 되돌아갑니다.

반대 상황도 문제입니다. 오래된 Next.js를 쓰는데 모델이 최신 API를 제안하면 작동하지 않습니다. Vercel은 프로젝트 버전에 맞는 문서를 에이전트에게 주는 방법을 찾고 싶었습니다.

두 가지 접근법

실험에 사용된 두 방법입니다.

Skills는 도메인 지식을 패키징하는 오픈 스탠다드입니다. 프롬프트, 도구, 문서를 묶어서 에이전트가 필요할 때 호출하게 만듭니다. 에이전트가 프레임워크 지식이 필요하다고 판단하면 스킬을 불러와 문서를 봅니다.

AGENTS.md는 프로젝트 루트에 두는 마크다운 파일입니다. 여기 적은 내용은 에이전트가 매번 자동으로 읽습니다. 별도 결정이 필요 없죠. Claude Code는 CLAUDE.md를 같은 용도로 씁니다.

Vercel은 Next.js 문서를 두 방식으로 만들어 어느 쪽이 나은지 평가했습니다.

Skills의 예상 밖 실패

Skills가 더 세련돼 보였습니다. 프레임워크 문서를 스킬로 만들면 에이전트가 Next.js 작업 시 호출해서 올바른 코드를 만들 것 같았죠. 깔끔한 분리, 최소 컨텍스트, 필요한 것만 로드.

그런데 평가 결과가 충격적이었습니다.

56% 케이스에서 스킬이 한 번도 호출되지 않았습니다. 에이전트가 문서에 접근할 수 있었는데도 안 썼습니다. 스킬 추가가 기본 성능과 동일했죠.

제로 개선. 스킬이 존재하고 쓸 수 있었는데, 쓰지 않았습니다. 상세 분석에서는 일부 지표가 오히려 나빠졌습니다(테스트 58% vs 기본 63%). 안 쓰는 스킬이 노이즈가 될 수 있다는 뜻이죠.

이건 이 실험만의 문제가 아닙니다. 에이전트가 사용 가능한 도구를 제대로 못 쓰는 건 현재 모델의 알려진 한계입니다.

명시적 지시의 효과와 한계

그래서 AGENTS.md에 명시적 지시를 추가했습니다. “코드 쓰기 전에 프로젝트 구조를 먼저 보고, 그 다음 nextjs-doc 스킬을 호출하세요.”

호출률이 95% 이상으로 올라갔고 통과율도 79%로 개선됐습니다.

확실한 개선이었습니다. 하지만 지시문 문구가 에이전트 행동에 미치는 영향이 예상 밖이었습니다.

같은 스킬, 같은 문서인데 문구만 바꿨더니 결과가 극적으로 달라졌습니다:

한 평가에서 “먼저 호출” 방식은 page.tsx는 맞췄지만 필수인 next.config.ts 변경을 완전히 놓쳤습니다. “먼저 탐색” 방식은 둘 다 맞췄죠.

작은 문구 차이가 큰 행동 변화를 만든다면 프로덕션에서 쓰기엔 불안정합니다.

AGENTS.md의 압도적 승리

다른 접근을 시도했습니다. 에이전트의 결정 자체를 없애는 겁니다.

스킬 호출을 바라는 대신 문서 인덱스를 AGENTS.md에 직접 넣었습니다. 전체 문서가 아니라 “프로젝트 Next.js 버전과 일치하는 문서 파일이 어디 있는지” 알려주는 인덱스만요. 에이전트는 필요할 때 그 파일을 읽어서 정확한 버전 정보를 얻습니다.

여기에 중요한 지시 하나를 추가했습니다.

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks.

이 지시는 에이전트에게 “오래된 학습 데이터 말고 문서를 참고하라”고 말합니다.

결과는 놀라웠습니다.

Build, Lint, Test 모두 완벽한 점수입니다.

예상과 정반대였습니다. 단순한 정적 파일이 정교한 스킬 기반 검색을 압도했습니다.

왜 수동적 컨텍스트가 이기나

Vercel의 가설은 세 가지입니다.

1. 결정 지점 없음. AGENTS.md는 에이전트가 “이걸 찾아볼까?” 고민할 순간이 없습니다. 정보가 이미 있으니까요.
2. 일관된 가용성. 스킬은 비동기로 로드되고 호출 시에만 작동합니다. AGENTS.md 내용은 매번 시스템 프롬프트에 들어갑니다.
3. 순서 문제 없음. 스킬은 순서 결정을 만듭니다(문서 먼저 vs 프로젝트 먼저). 수동적 컨텍스트는 이걸 피합니다.

컨텍스트 비대화는 어떻게 해결했나

AGENTS.md에 문서를 넣으면 컨텍스트 윈도우가 비대해질 위험이 있습니다. Vercel은 압축으로 해결했습니다.

초기 40KB 문서를 8KB로 압축했습니다(80% 감소). 100% 통과율은 그대로 유지됐죠. 압축 포맷은 파이프로 구분된 구조입니다:

[Next.js Docs Index]|root: ./.next-docs|IMPORTANT: Prefer retrieval-led reasoning...|01-app/01-getting-started:{01-installation.mdx,02-project-structure.mdx,...}

에이전트는 전체 내용 없이도 문서 위치를 압니다. 필요하면 .next-docs/에서 파일을 읽습니다.

지금 바로 써보세요

명령어 하나로 Next.js 프로젝트에 설정할 수 있습니다:

npx @next/codemod@canary agents-md

이 명령어는 세 가지를 합니다:

1. Next.js 버전 감지
2. 일치하는 문서를 .next-docs/에 다운로드
3. 압축된 인덱스를 AGENTS.md에 주입

Cursor나 다른 AGENTS.md 지원 에이전트를 쓰면 바로 작동합니다.

Skills는 쓸모없나요?

아닙니다. AGENTS.md는 모든 작업에서 에이전트가 Next.js와 작동하는 방식을 수평적으로 개선합니다. Skills는 사용자가 명시적으로 트리거하는 특정 워크플로우에 더 적합합니다. “Next.js 버전 업그레이드”, “App Router로 마이그레이션” 같은 작업 말이죠. 두 접근법은 서로 보완합니다.

다만 일반적인 프레임워크 지식에는 현재 수동적 컨텍스트가 온디맨드 검색보다 우수합니다. 프레임워크를 만드는 분이라면 사용자가 프로젝트에 추가할 AGENTS.md 스니펫 제공을 고려해보세요.

실용적 조언:

• Skills 개선을 기다리지 마세요. 모델이 나아지면 격차가 줄어들 수 있지만, 지금 결과가 중요합니다.
• 적극적으로 압축하세요. 전체 문서가 필요 없습니다. 검색 가능한 파일 위치를 가리키는 인덱스면 됩니다.
• 평가로 테스트하세요. 학습 데이터에 없는 API를 대상으로 평가를 만드세요.
• 검색을 위한 설계를 하세요. 에이전트가 특정 파일을 찾고 읽을 수 있게 문서를 구조화하세요.

목표는 에이전트를 사전 학습 기반 추론에서 검색 기반 추론으로 전환하는 겁니다. AGENTS.md가 가장 신뢰할 수 있는 방법입니다.