Vercel의 AGENTS.md vs Skills 실험: AI 코딩 에이전트에게 지식을 전달하는 최적의 방법

관련글

AGENTS.md outperforms skills in our agent evals

들어가며

2026년 1월 27일, Vercel이 AI 코딩 에이전트의 성능 평가 결과를 공개하면서 개발자 커뮤니티에 큰 파장을 일으켰습니다. 그들의 실험은 한 가지 놀라운 사실을 드러냈습니다. 코딩 에이전트에게 프레임워크 지식을 전달하는 방법으로 “Skills”보다 “AGENTS.md”가 압도적으로 우수하다는 것입니다. 더 정교하고 복잡해 보이는 Skills 시스템이 단순한 마크다운 파일에 밀린 것입니다.

이 실험은 단순히 두 가지 기술의 우열을 가리는 것을 넘어, AI 에이전트가 어떻게 작동하는지, 그리고 현재 AI 모델의 한계가 무엇인지를 보여주는 중요한 사례입니다. Vercel은 Next.js 16의 새로운 API들에 대한 정확한 코드 생성을 목표로 두 가지 접근법을 비교했고, 그 결과는 많은 개발자들의 예상을 뒤집었습니다.

해결하려던 문제

AI 코딩 에이전트들은 근본적인 한계를 가지고 있습니다. 이들은 훈련 데이터를 기반으로 작동하는데, 이 훈련 데이터는 시간이 지나면서 구식이 되어버립니다. Next.js 16이 도입한 ‘use cache’, connection(), forbidden() 같은 새로운 API들은 현재 AI 모델의 훈련 데이터에 포함되어 있지 않습니다. 결과적으로 에이전트들은 이런 최신 API를 모르기 때문에 잘못된 코드를 생성하거나 예전 방식으로 되돌아가게 됩니다.

반대의 상황도 문제입니다. 개발자가 구버전 Next.js를 사용하고 있는데, AI 모델이 신버전의 API를 제안하면 프로젝트에서 작동하지 않는 코드가 생성됩니다. Vercel은 이 문제를 해결하기 위해 에이전트에게 프로젝트 버전에 맞는 정확한 문서를 제공하는 방법을 찾고자 했습니다.

두 가지 접근 방식

Skills: 필요할 때 불러오는 지식 패키지

Skills는 AI 에이전트를 위한 도메인 지식 패키징의 공개 표준입니다. 하나의 Skill은 프롬프트, 도구, 문서를 하나의 패키지로 묶어서 제공합니다. 작동 원리는 이렇습니다. 에이전트가 프레임워크 관련 작업을 인식하면, 해당 Skill을 호출하고, 그 안에 있는 관련 문서에 접근하여 올바른 코드를 생성합니다.

이 방식은 논리적으로 매우 합리적입니다. 필요한 순간에만 지식을 불러오기 때문에 컨텍스트 오버헤드가 적고, 관심사의 분리가 명확하며, 에이전트가 필요한 것만 로드합니다. 더구나 skills.sh 같은 재사용 가능한 Skills 디렉토리도 존재하여 생태계가 형성되고 있었습니다.

Vercel은 Next.js 문서를 Skill로 패키징했습니다. 에이전트가 Next.js 작업을 만나면 Skill을 호출하고, 버전에 맞는 문서를 읽고, 정확한 코드를 생성할 것이라고 기대했습니다.

AGENTS.md: 항상 존재하는 정적 컨텍스트

AGENTS.md는 프로젝트 루트에 위치하는 마크다운 파일로, 코딩 에이전트에게 지속적인 컨텍스트를 제공합니다. 이 파일에 넣은 내용은 에이전트가 결정을 내릴 필요 없이 모든 턴마다 사용 가능합니다. Claude Code의 경우 CLAUDE.md라는 이름으로 같은 목적으로 사용됩니다.

이 방식은 단순하고 “멍청해” 보입니다. 모든 정보를 항상 컨텍스트에 올려놓는 것이기 때문입니다. 하지만 Vercel은 이 방식을 시도해보기로 했습니다. 그들은 전체 문서를 넣는 대신, 압축된 문서 인덱스를 만들었습니다. 이 인덱스는 에이전트에게 특정 문서 파일이 어디에 있는지 알려주고, 필요할 때 그 파일을 읽을 수 있게 합니다.

실험 설계

Vercel은 신뢰할 수 있는 평가 시스템을 구축하는 데 많은 노력을 기울였습니다. 초기 테스트 스위트는 모호한 프롬프트, 구현 세부사항을 검증하는 테스트, 이미 모델 훈련 데이터에 포함된 API에 초점을 맞추고 있었습니다. 이는 그들이 실제로 측정하고 싶은 것을 제대로 측정하지 못했습니다.

그들은 평가 시스템을 강화했습니다. 테스트 누출을 제거하고, 모순을 해결하고, 관찰 가능한 동작 기반 검증으로 전환했습니다. 가장 중요하게는 모델 훈련 데이터에 없는 Next.js 16 API를 타겟으로 하는 테스트를 추가했습니다.

평가 대상 API는 다음과 같습니다:

• connection(): 동적 렌더링을 위한 함수
• ‘use cache’: 캐싱을 위한 디렉티브
• cacheLife()와 cacheTag(): 캐시 관리 함수
• forbidden()과 unauthorized(): 권한 처리 함수
• proxy.ts: API 프록시 설정
• 비동기 cookies()와 headers(): 요청 정보 접근
• after(), updateTag(), refresh(): 고급 기능들

이후의 모든 결과는 이 강화된 평가 시스템에서 나온 것입니다. 모든 설정은 동일한 테스트로 평가되었고, 모델 변동성을 배제하기 위해 재시도를 수행했습니다.

충격적인 실험 결과

Vercel은 네 가지 설정으로 실험을 진행했습니다:

1. Baseline (문서 없음)
2. Skill (기본 동작)
3. Skill (명시적 지시 포함)
4. AGENTS.md (문서 인덱스 포함)

Skills가 호출조차 안 되는 문제

가장 충격적인 발견은 Skill이 전혀 작동하지 않았다는 것입니다. 평가 사례의 56%에서 Skill이 한 번도 호출되지 않았습니다. 에이전트는 문서에 접근할 수 있었지만 사용하지 않았습니다. Skill을 추가한 것이 baseline과 비교해 전혀 개선을 가져오지 못했습니다.

설정	통과율	Baseline 대비
Baseline (문서 없음)	53%	-
Skill (기본 동작)	53%	+0%p

개선이 전혀 없었습니다. Skill이 존재하고, 에이전트가 사용할 수 있었는데도 에이전트는 사용하지 않기로 선택했습니다. 상세 분석을 보면 Skill이 오히려 일부 지표에서 baseline보다 나빴습니다 (테스트에서 58% vs 63%), 이는 사용되지 않는 Skill이 환경에 노이즈나 혼란을 추가할 수 있음을 시사합니다.

이것은 Vercel만의 문제가 아닙니다. 에이전트가 사용 가능한 도구를 신뢰성 있게 사용하지 않는 것은 현재 모델들의 알려진 한계입니다.

명시적 지시로 개선되지만 취약함

Vercel은 AGENTS.md에 Skill을 사용하라는 명시적 지시를 추가했습니다:

코드를 작성하기 전에, 먼저 프로젝트 구조를 탐색한 후, 
문서를 위해 nextjs-doc skill을 호출하세요.

이것은 호출률을 95% 이상으로 높였고 통과율을 79%로 끌어올렸습니다.

설정	통과율	Baseline 대비
Baseline (문서 없음)	53%	-
Skill (기본 동작)	53%	+0%p
Skill (명시적 지시)	79%	+26%p

확실한 개선입니다. 하지만 Vercel은 지시 문구에 따라 에이전트 동작이 극적으로 달라진다는 것을 발견했습니다.

다양한 문구가 매우 다른 결과를 만들었습니다:

지시	동작	결과
“반드시 skill을 호출하세요”	문서를 먼저 읽고, 문서 패턴에 집착	프로젝트 컨텍스트 놓침
“프로젝트를 먼저 탐색, 그 후 skill 호출”	먼저 멘탈 모델 구축, 문서를 참고로 사용	더 나은 결과

같은 Skill, 같은 문서였지만 미묘한 문구 변경이 결과를 크게 바꿨습니다.

한 평가 사례(‘use cache’ 디렉티브 테스트)에서 “먼저 호출” 방식은 올바른 page.tsx를 작성했지만 필수 next.config.ts 변경을 완전히 놓쳤습니다. “먼저 탐색” 방식은 둘 다 올바르게 처리했습니다.

이런 취약성이 Vercel을 걱정하게 만들었습니다. 작은 문구 변경이 큰 행동 변화를 만든다면, 이 접근법은 프로덕션 사용에는 너무 불안정하다고 느꼈습니다.

AGENTS.md의 압도적 승리

그들은 결정을 완전히 제거하면 어떨까 생각했습니다. 에이전트가 Skill을 호출할지 결정하게 하는 대신, 문서 인덱스를 AGENTS.md에 직접 임베딩했습니다. 전체 문서가 아니라 프로젝트의 Next.js 버전에 맞는 특정 문서 파일이 어디 있는지 알려주는 인덱스였습니다. 에이전트는 필요에 따라 그 파일들을 읽을 수 있고, 구식 훈련 데이터가 아닌 버전에 맞는 정확한 정보를 얻습니다.

핵심 지시사항을 주입된 내용에 포함시켰습니다:

중요: Next.js 작업에 대해서는 pre-training-led reasoning보다 
retrieval-led reasoning을 선호하세요.

이것은 에이전트에게 잠재적으로 구식인 훈련 데이터가 아닌 문서를 참고하라고 말합니다.

결과는 모든 기대를 뛰어넘었습니다:

설정	통과율	Baseline 대비
Baseline (문서 없음)	53%	-
Skill (기본 동작)	53%	+0%p
Skill (명시적 지시)	79%	+26%p
AGENTS.md 문서 인덱스	100%	+47%p

상세 분석에서 AGENTS.md는 Build, Lint, Test 전반에 걸쳐 완벽한 점수를 달성했습니다:

설정	Build	Lint	Test
Baseline	84%	95%	63%
Skill (기본 동작)	84%	89%	58%
Skill (명시적 지시)	95%	100%	84%
AGENTS.md	100%	100%	100%

이것은 예상하지 못한 결과였습니다. “멍청한” 접근법(정적 마크다운 파일)이 더 정교한 Skill 기반 검색을 능가했습니다. 심지어 Skill 트리거를 세밀하게 조정했을 때도 말입니다.

왜 정적 컨텍스트가 온디맨드 검색을 이기는가?

Vercel의 작업 이론은 세 가지 요인으로 귀결됩니다:

1. 결정 지점이 없음

AGENTS.md를 사용하면 에이전트가 “이것을 찾아봐야 할까?”라고 결정할 순간이 없습니다. 정보가 이미 존재합니다. 에이전트는 도구를 호출할지, 언제 호출할지, 어떤 문구로 호출할지 결정할 필요가 없습니다. 인지 부담이 제거됩니다.

2. 일관된 가용성

Skills는 비동기적으로 로드되며 호출될 때만 로드됩니다. AGENTS.md 내용은 모든 턴마다 시스템 프롬프트에 있습니다. 항상 거기 있습니다. 잊혀지거나 건너뛰일 수 없습니다.

3. 순서 문제 없음

Skills는 순서 결정을 만듭니다 (문서를 먼저 읽을까 vs 프로젝트를 먼저 탐색할까). 이런 순서 결정이 결과에 큰 영향을 미칠 수 있다는 것을 봤습니다. 정적 컨텍스트는 이것을 완전히 피합니다. 정보가 항상 존재하므로 순서가 문제되지 않습니다.

컨텍스트 비대화 문제 해결

AGENTS.md에 문서를 임베딩하면 컨텍스트 윈도우를 비대화할 위험이 있습니다. Vercel은 압축으로 이 문제를 해결했습니다.

초기 문서 주입은 약 40KB였습니다. 그들은 100% 통과율을 유지하면서 8KB로 압축했습니다 (80% 감소). 압축된 형식은 파이프로 구분된 구조를 사용하여 문서 인덱스를 최소 공간에 패킹합니다:

[Next.js Docs Index]|root: ./.next-docs
|중요: Next.js 작업에 대해서는 pre-training-led reasoning보다 
retrieval-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.js 문서의 모든 섹션을 커버합니다. 에이전트는 컨텍스트에 전체 내용을 담지 않고도 문서를 어디서 찾을 수 있는지 알고 있습니다. 특정 정보가 필요하면 .next-docs/ 디렉토리에서 관련 파일을 읽습니다.

이것은 영리한 절충안입니다. 전체 문서를 로드하는 오버헤드 없이 문서 인식 혜택을 얻습니다. 에이전트는 존재하는 것을 알고, 어디서 찾을 수 있는지 알고, 필요할 때 가져옵니다.

직접 사용해보기

Vercel은 이 기능을 Next.js 프로젝트를 위해 원커맨드로 만들었습니다:

npx @next/codemod@canary agents-md

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

이 명령은 세 가지를 수행합니다:

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를 타겟으로 하는 평가를 구축하세요. 그것이 문서 접근이 가장 중요한 곳입니다.

검색을 위해 설계하세요. 에이전트가 모든 것을 미리 필요로 하기보다는 특정 파일을 찾고 읽을 수 있도록 문서를 구조화하세요.

목표는 에이전트를 pre-training-led reasoning에서 retrieval-led reasoning으로 전환하는 것입니다. AGENTS.md가 이를 실현하는 가장 신뢰할 수 있는 방법으로 밝혀졌습니다.

더 깊은 함의

현재 AI 모델의 한계

이 실험은 현재 AI 모델의 근본적인 한계를 드러냅니다. 에이전트들은 언제 도구를 사용해야 하는지 신뢰성 있게 결정하는 데 어려움을 겪습니다. 도구가 사용 가능하고, 문서화되어 있고, 명백히 관련이 있어도 에이전트는 그것을 사용하지 않기로 선택할 수 있습니다.

이것은 현재 언어 모델이 작동하는 방식에서 비롯됩니다. 도구 사용 행동은 인간이 생성한 예제와 사용 추적으로 강화 학습을 통해 훈련됩니다. Skills는 새로운 것이므로 그런 행동을 보여주는 훈련 샘플이 충분하지 않습니다. 모델은 Skills를 “이해”하지 못하고 있습니다.

단순함의 승리

더 정교한 시스템이 항상 더 나은 것은 아닙니다. Skills는 엘레강트한 추상화이고, 깨끗한 관심사 분리를 제공하며, 논리적으로 매우 합리적입니다. 하지만 에이전트가 신뢰성 있게 사용하지 못하면 쓸모가 없습니다.

AGENTS.md는 “멍청”해 보입니다. 정보를 파일에 넣고 항상 거기 있게 하는 것입니다. 하지만 이것이 작동합니다. 왜냐하면 결정을 제거하기 때문입니다. 에이전트가 올바른 선택을 할 것이라고 믿는 대신, 그 선택을 완전히 제거합니다.

도구 설계의 교훈

AI 에이전트를 위한 도구를 설계할 때:

• 기본값을 항상 온(always-on)으로 만드세요. 에이전트가 활성화를 기억하게 하지 마세요.
• 순서 의존성을 피하세요. 순서가 중요하면 에이전트는 틀릴 것입니다.
• 컨텍스트에서 쉽게 사용 가능하게 만드세요. 컨텍스트에 있으면 에이전트는 그것을 사용할 것입니다. 그렇지 않으면 잊어버릴 수 있습니다.

개발자 워크플로우에 미치는 영향

이것이 개발자들에게 의미하는 바는 명확합니다. Next.js나 다른 프레임워크를 사용하여 AI 에이전트로 작업한다면:

1. 프로젝트에 AGENTS.md를 추가하세요. Next.js의 경우 npx @next/codemod@canary agents-md를 실행하세요.
2. Skills를 버리지 마세요. 복잡한 마이그레이션이나 구조 조정 같은 특정 작업에는 여전히 유용합니다.
3. 둘을 함께 사용하세요. AGENTS.md는 일반 지식을 제공하고, Skills는 특정 작업을 처리합니다.

미래 전망

이 실험은 스냅샷입니다. 현재 모델(2026년 1월 기준)에서 작동하는 것입니다. 미래의 모델은 도구 사용을 더 잘할 수 있고, Skills가 더 신뢰성 있게 작동할 수 있습니다.

하지만 현재로서는 데이터가 명확합니다. AI 코딩 에이전트에게 프레임워크 지식을 제공하려면 AGENTS.md를 사용하세요. 압축된 문서 인덱스를 만들고, 프로젝트 루트에 놓고, 에이전트가 할 일을 하게 두세요.

결과가 스스로 말해줍니다: 53%에서 100% 통과율로. 복잡한 도구 호출 없이. 순서 문제 없이. 그냥 작동합니다.

결론

Vercel의 실험은 AI 에이전트와 작업하는 방법에 대한 가치 있는 교훈을 제공합니다. 가장 우아한 솔루션이 항상 가장 효과적인 것은 아닙니다. 때로는 가장 단순한 접근법이 승리합니다.

AGENTS.md vs Skills 논쟁은 더 넓은 질문의 일부입니다: AI 에이전트를 위한 인터페이스를 어떻게 설계하는가? 답은 에이전트가 신뢰성 있게 할 수 없는 결정을 제거하고, 기본값을 항상 온으로 만들고, 컨텍스트에서 정보를 쉽게 사용 가능하게 만드는 것입니다.

당신이 프레임워크 제작자이든, 앱 개발자이든, AI 도구를 구축하는 사람이든, 이 교훈은 적용됩니다: 단순함이 이깁니다. 결정을 제거하세요. 정보를 사용 가능하게 만드세요. 그리고 결과를 측정하세요.

Vercel은 측정했고, 결과는 명확했습니다. AGENTS.md가 승자입니다.

---

참고 자료:

• Vercel Blog: “AGENTS.md outperforms skills in our agent evals” (2026년 1월 27일)
• GitHub: vercel-labs/agent-skills
• Agent Skills 명세: https://skills.sh
• Next.js 코드모드: @next/codemod@canary

작성 일자: 2026-01-31