이 글은 코딩 에이전트에게 프레임워크별 지식을 가르치기 위한 두 가지 접근 방식, 즉 스킬과 AGENTS.md를 비교한 연구 결과를 요약합니다. Next.js 16 API에 중점을 둔 평가를 통해, 연구진은 AGENTS.md에 직접 포함된 압축된 8KB 문서 인덱스가 100%의 통과율을 달성하며 스킬보다 훨씬 우수한 성능을 보였다는 예상치 못한 결과를 발견했습니다. 이 결과는 에이전트가 능동적으로 정보를 검색하는 것보다 수동적인 맥락(Passive Context)을 활용하는 것이 더 효과적일 수 있음을 시사합니다.

1. 해결하고자 했던 문제 💡

AI 코딩 에이전트들은 학습 데이터가 구식이 되는 문제에 직면하고 있어요. 특히 2026년 현재, Next.js 16에 새로 도입된 'use cache', connection(), forbidden() 같은 API들은 기존 모델 학습 데이터에 포함되어 있지 않아 에이전트가 잘못된 코드를 생성하거나 이전 패턴으로 돌아가는 경우가 많았죠. 반대로, 오래된 Next.js 버전을 사용하는 프로젝트에서는 모델이 최신 API를 제안하는 문제도 있었어요. Vercel 팀은 이런 문제를 해결하기 위해 에이전트에게 버전에 맞는 문서를 제공하고자 했습니다.

2. 프레임워크 지식을 가르치기 위한 두 가지 접근 방식 🧑‍🏫

Vercel 팀은 에이전트에게 프레임워크 지식을 가르치기 위해 두 가지 방식을 테스트했어요.

• 스킬 (Skills): 이는 에이전트가 필요할 때 호출할 수 있는 도메인 지식 패키지의 오픈 표준이에요. 에이전트가 프레임워크 관련 도움이 필요하다고 판단하면 스킬을 호출하여 관련 문서에 접근하는 방식이죠. 에이전트가 필요한 정보만 적재하기 때문에 관심사 분리가 명확하고 컨텍스트 오버헤드를 최소화할 수 있을 것이라고 예상했습니다.
• AGENTS.md: 이는 프로젝트 루트에 있는 마크다운 파일로, 코딩 에이전트에게 지속적인 컨텍스트를 제공합니다. 이 파일에 담긴 내용은 에이전트가 매 턴마다 사용할 수 있으며, 에이전트가 직접 정보를 로드할지 결정할 필요가 없다는 특징이 있습니다. Claude Code도 유사한 목적으로 CLAUDE.md를 사용하고 있어요.

Vercel 팀은 Next.js 문서 스킬과 AGENTS.md 문서 인덱스를 만들고, 어떤 방식이 더 나은 성능을 보이는지 평가했습니다.

3. 스킬에 대한 초기 기대와 실망스러운 결과 📉

처음에는 스킬이 문제 해결에 적합하다고 생각했어요. 프레임워크 문서를 스킬로 패키징하면 에이전트가 Next.js 작업 시 스킬을 호출하고, 버전이 일치하는 문서를 읽어 정확한 코드를 생성할 것이라고 기대했죠. 이는 깔끔한 관심사 분리와 최소한의 컨텍스트 오버헤드를 제공하며, 에이전트가 필요한 것만 로드할 것이라고 보았습니다.

하지만 평가를 진행한 결과, 기대와는 달랐습니다.

3.1. 스킬이 안정적으로 트리거되지 않았어요 🙅‍♀️

평가 사례의 56%에서 스킬은 전혀 호출되지 않았어요. 에이전트가 문서에 접근할 수 있었지만 사용하지 않은 거죠. 스킬을 추가해도 기준선(문서 없음)과 비교하여 아무런 개선도 없었습니다.

심지어 어떤 경우에는 테스트 지표에서 기준선보다 낮은 성능을 보이기도 했는데, 이는 사용되지 않는 스킬이 환경에 노이즈나 방해를 줄 수 있음을 시사했습니다. 에이전트가 사용 가능한 도구를 안정적으로 사용하지 못하는 것은 현재 모델의 알려진 한계이기도 하다고 해요.

3.2. 명시적인 지시가 도움이 되었지만, 문구는 취약했어요 💬

팀은 AGENTS.md에 에이전트에게 스킬을 사용하도록 명시적인 지시를 추가해 보았습니다.

Before writing code, first explore the project structure, then invoke the nextjs-doc skill for documentation. (코드를 작성하기 전에 먼저 프로젝트 구조를 탐색하고, 그 다음 nextjs-doc 스킬을 호출하여 문서를 확인하세요.)

이 지시 덕분에 스킬 호출율은 95% 이상으로 향상되었고, 통과율도 79%로 크게 올랐습니다.

하지만 여기서 예상치 못한 문제에 부딪혔는데, 지시 문구의 미묘한 차이가 에이전트의 행동에 엄청난 영향을 미친다는 것을 발견했어요.

• "You MUST invoke the skill" (스킬을 반드시 호출해야 한다) → 문서를 먼저 읽고 문서 패턴에 집중하여 프로젝트 컨텍스트를 놓침.
• "Explore project first, then invoke skill" (프로젝트를 먼저 탐색한 다음 스킬을 호출한다) → 먼저 정신 모델을 구축한 후 문서를 참조하여 더 나은 결과를 얻음.

똑같은 스킬과 문서인데도, 작은 단어 변경으로 결과가 달라지는 취약성은 생산 환경에서 사용하기 어렵다고 판단했어요.

4. 신뢰할 수 있는 평가 구축하기 💪

결론을 내리기 전에, Vercel 팀은 신뢰할 수 있는 평가 도구가 필요하다고 느꼈어요. 초기 테스트 스위트는 모호한 프롬프트, 구현 세부 사항을 검증하는 테스트, 그리고 이미 모델 학습 데이터에 있는 API에 대한 집중 등 여러 문제점이 있었죠. 이들은 실제로 중요하게 생각하는 것을 측정하고 있지 않았던 것입니다.

팀은 테스트 유출을 제거하고, 모순을 해결하며, 행동 기반 어설션(behavior-based assertions)으로 전환하여 평가 스위트를 강화했습니다. 가장 중요하게, 모델 학습 데이터에 없는 Next.js 16 API를 대상으로 하는 테스트를 추가했어요.

새로 추가된 평가 스위트의 API들:

• 동적 렌더링을 위한 connection()
• 'use cache' 지시어
• cacheLife() 및 cacheTag()
• forbidden() 및 unauthorized()
• API 프록싱을 위한 proxy.ts
• 비동기 cookies() 및 headers()
• after(), updateTag(), refresh()

모든 후속 결과는 이 강화된 평가 스위트에서 나온 것이며, 모든 구성은 모델의 편차를 배제하기 위해 재시도를 포함하여 동일한 테스트에 따라 평가되었습니다.

5. 예상치 못한 결과: AGENTS.md의 승리 🏆

Vercel 팀은 에이전트가 스킬 호출 여부를 결정할 필요 없이, 문서 인덱스를 AGENTS.md에 직접 포함시키는 아이디어를 떠올렸어요. 전체 문서가 아니라 프로젝트의 Next.js 버전에 맞는 특정 문서 파일을 찾을 수 있는 인덱스만 포함하는 거죠. 에이전트는 필요에 따라 해당 파일을 읽어 버전별 정확한 정보를 얻을 수 있습니다.

삽입된 내용에 핵심 지시를 추가했습니다.

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks. (중요: 모든 Next.js 작업에 대해 사전 학습 기반 추론보다 검색 기반 추론을 선호하십시오.)

이 지시는 에이전트에게 잠재적으로 오래된 학습 데이터에 의존하는 대신 문서를 참조하도록 지시하는 것입니다.

5.1. 결과는 우리를 놀라게 했습니다! 😲

강화된 평가 스위트를 모든 네 가지 구성에 걸쳐 실행했을 때, 결과는 놀라웠습니다.

Vercel 팀은 "바보 같은" 접근 방식(정적 마크다운 파일)이 스킬 기반 검색보다 훨씬 뛰어난 성능을 보이는 것에 놀랐습니다.

최종 통과율:

세부 분석에서도 AGENTS.md는 빌드, 린트, 테스트 전반에 걸쳐 완벽한 점수를 달성했습니다.

5.2. 왜 수동적 컨텍스트가 능동적 검색을 이기는가? 🤔

Vercel 팀은 세 가지 요인으로 그 이유를 설명했습니다.

1. 결정 지점 없음: AGENTS.md를 사용하면 에이전트가 "이것을 찾아봐야 할까?"라고 결정할 필요가 없어요. 정보가 이미 존재하니까요.
2. 일관된 가용성: 스킬은 비동기적으로, 그리고 호출될 때만 로드되지만, AGENTS.md 내용은 매 턴마다 시스템 프롬프트에 포함됩니다.
3. 순서 문제 없음: 스킬은 (문서를 먼저 읽을지, 프로젝트를 먼저 탐색할지 등) 시퀀싱 결정을 필요로 하지만, 수동적 컨텍스트는 이를 완전히 피합니다.

6. 컨텍스트 비대화 문제 해결 📚

AGENTS.md에 문서를 삽입하면 컨텍스트 창이 비대해질 위험이 있습니다. Vercel 팀은 압축을 통해 이 문제를 해결했어요.

초기 문서 삽입 크기는 약 40KB였지만, 이를 8KB로 압축(80% 감소)하면서도 100% 통과율을 유지했습니다. 압축된 형식은 파이프(|)로 구분된 구조를 사용하여 문서 인덱스를 최소한의 공간에 담았습니다.

[Next.js Docs Index]|root: ./.next-docs|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning|01-app/01-getting-started:{01-installation.mdx,02-project-structure.mdx,...}|01-app/02-building-your-application/01-routing:{01-defining-routes.mdx,...}

에이전트는 모든 내용을 컨텍스트에 담지 않고도 문서 위치를 알 수 있으며, 특정 정보가 필요할 때 .next-docs/ 디렉토리에서 관련 파일을 읽습니다.

7. 직접 사용해 보세요! 🚀

Next.js 프로젝트에서 이 기능을 직접 사용해 볼 수 있습니다. 다음 명령어를 실행하면 됩니다.

npx @next/codemod@canary agents-md

이 기능은 공식 @next/codemod 패키지의 일부입니다.

이 명령어는 세 가지 작업을 수행합니다.

1. 사용 중인 Next.js 버전을 감지합니다.
2. 해당 버전에 맞는 문서를 .next-docs/로 다운로드합니다.
3. 압축된 인덱스를 AGENTS.md 파일에 삽입합니다.

Cursor나 다른 도구처럼 AGENTS.md를 존중하는 에이전트를 사용한다면, 이와 동일한 방식으로 활용할 수 있어요.

8. 프레임워크 개발자에게 주는 시사점 ✨

스킬이 쓸모없는 것은 아닙니다. AGENTS.md 접근 방식은 모든 작업에서 에이전트가 Next.js와 상호 작용하는 방식에 광범위하고 수평적인 개선을 제공합니다. 반면에 스킬은 "Next.js 버전 업그레이드", "앱 라우터로 마이그레이션", 또는 프레임워크 모범 사례 적용과 같이 사용자가 명시적으로 트리거하는 수직적이고 액션 중심적인 워크플로우에 더 잘 작동합니다. 두 접근 방식은 서로 보완적이라고 볼 수 있어요.

하지만 일반적인 프레임워크 지식에 대해서는 현재 수동적 컨텍스트가 온디맨드 검색보다 우수한 성능을 보입니다. 프레임워크를 관리하고 코딩 에이전트가 올바른 코드를 생성하기를 원한다면, 사용자가 자신의 프로젝트에 추가할 수 있는 AGENTS.md 스니펫을 제공하는 것을 고려해 보세요.

실용적인 권장 사항:

• 스킬 개선을 기다리지 마세요. 모델이 도구 사용에 더 능숙해지면 격차가 좁아질 수도 있지만, 지금 당장 결과가 중요합니다.
• 적극적으로 압축하세요. 전체 문서를 컨텍스트에 담을 필요는 없습니다. 검색 가능한 파일을 가리키는 인덱스만으로도 충분합니다.
• 평가로 테스트하세요. 학습 데이터에 없는 API를 대상으로 하는 평가를 구축하세요. 문서 접근이 가장 중요한 부분입니다.
• 검색을 위해 설계하세요. 에이전트가 모든 것을 미리 알아야 하는 대신, 특정 파일을 찾고 읽을 수 있도록 문서를 구성하세요.

목표는 에이전트가 사전 학습 기반 추론에서 검색 기반 추론으로 전환하도록 하는 것입니다. AGENTS.md는 현재 이 목표를 가장 안정적으로 달성하는 방법으로 밝혀졌습니다.

이 연구와 평가는 Jude Gao가 수행했습니다. CLI는 npx @next/codemod@canary agents-md에서 사용할 수 있습니다.

결론 🎯

Vercel의 연구 결과는 코딩 에이전트에게 프레임워크 지식을 제공하는 데 있어 AGENTS.md와 같은 수동적 컨텍스트 방식이 '스킬'과 같은 능동적 검색 방식보다 현재 모델에서는 훨씬 효과적임을 분명히 보여주었습니다. 이는 에이전트가 정보 검색 여부를 결정하는 과정 없이 항상 관련 지식을 즉시 활용할 수 있게 함으로써, 특히 최신 API나 특정 프로젝트 버전에 맞는 정보에 대한 접근성을 크게 향상시켰습니다. 프레임워크 개발자들은 이러한 결과를 바탕으로 에이전트의 효율성을 높일 수 있는 문서 제공 방식에 대한 접근 방식을 재고해야 할 것입니다.