Vercel의 AGENTS.md vs Skills 실험

한 줄 요약

Vercel의 실험은 skill이 쓸모없다는 이야기가 아니다. Next.js 16 API처럼 항상 참조해야 하는 버전별 프레임워크 지식은 skill처럼 필요할 때 불러오게 두기보다, AGENTS.md에 짧은 directive와 압축 문서 index를 넣어 에이전트가 반드시 보게 만드는 편이 더 안정적이었다.

먼저 읽을 결론

Vercel Blog의 AGENTS.md outperforms skills in our agent evals는 Next.js 16 신규 API 지식을 코딩 에이전트에 주입하는 네 가지 방식을 비교했다. 결과는 뚜렷했다.

구성	Pass rate
Baseline, 문서 없음	53%
Skill 기본 동작	53%
Skill + `AGENTS.md`에 명시적 호출 지시	79%
`AGENTS.md`에 압축 docs index 삽입	100%

핵심 차이는 지식의 품질보다 activation 방식이었다. skill은 에이전트가 “지금 이 skill을 불러야 한다”고 판단해야 한다. 반면 AGENTS.md는 매 턴 persistent context에 들어가므로, 문서를 찾아야 하는지 결정하는 단계를 없앤다.

그래서 실무 결론은 이렇게 정리할 수 있다.

지식/작업 유형	추천 위치
항상 적용돼야 하는 레포 규칙	`AGENTS.md`
프레임워크·사내 SDK 문서 위치	`AGENTS.md`의 짧은 directive와 압축 index
긴 문서 본문	별도 docs 디렉터리
마이그레이션·감사·릴리즈 같은 절차	skill
포맷·스타일·기계적 규칙	linter/CI
판단이 필요한 UX·제품 규칙	skill + examples + evals

왜 저장했나

코딩 에이전트를 잘 쓰려면 좋은 지식을 갖고 있는 것만으로는 부족하다. 에이전트가 그 지식을 언제 읽어야 하는지, 어떤 순서로 읽어야 하는지, 읽지 않았을 때 어떻게 실패하는지까지 설계해야 한다.

이 글은 AGENTS.md와 skill을 단순 비교하는 글처럼 보이지만, 실제로는 agent context engineering의 좋은 사례다. “항상 보여야 하는 지식”과 “필요할 때 실행하는 workflow”를 나누는 기준을 꽤 선명하게 보여준다.

정리한 질문

코딩 에이전트에 최신 프레임워크 지식과 프로젝트 규칙을 주입할 때, 어떤 내용은 AGENTS.md에 넣고 어떤 내용은 skill로 분리해야 하는가?

원문 실험의 맥락

Vercel이 다룬 문제는 Next.js 16의 신규 API였다. 'use cache', connection(), forbidden() 같은 API는 모델의 학습 지식에 없거나 충분히 반영되지 않았을 수 있다. 오래된 Next.js 프로젝트에서는 반대로 모델이 최신 API를 잘못 추천할 수도 있다.

Vercel의 목표는 에이전트가 프로젝트의 Next.js 버전에 맞는 문서를 안정적으로 참조하게 만드는 것이었다. 그래서 Next.js docs skill과 AGENTS.md docs index를 만들고 eval suite로 비교했다.

focused eval suite에는 connection(), 'use cache', cacheLife(), cacheTag(), forbidden(), unauthorized(), proxy.ts, async cookies()/headers(), after(), updateTag(), refresh() 같은 Next.js 16 API가 포함됐다. Vercel은 초기 eval suite의 모호한 prompt, test leakage, 구현 세부사항 중심 assertion을 줄이고, 학습 데이터에 없을 가능성이 높은 API와 observable behavior 중심으로 테스트를 다시 잡았다고 설명했다.

중요한 수치는 다음과 같다.

압축된 8KB docs index를 AGENTS.md에 넣은 구성은 100% pass rate를 기록했다.
skill은 명시적으로 호출하라고 지시해도 79%가 한계였다.
skill 기본 동작은 baseline과 같은 53%였다.
skill 기본 구성에서는 eval case의 56%에서 skill이 아예 invoke되지 않았다.
AGENTS.md에 “프로젝트 구조를 먼저 살핀 뒤 nextjs-doc skill을 호출하라”는 식의 지시를 넣자 trigger rate가 95% 이상으로 올랐다.
Vercel은 초기 약 40KB docs injection을 약 8KB index로 압축했다.

세부 지표도 같은 방향이었다.

구성	Build	Lint	Test
Baseline	84%	95%	63%
Skill 기본 동작	84%	89%	58%
Skill + 명시적 지시	95%	100%	84%
`AGENTS.md` docs index	100%	100%	100%

왜 skill이 밀렸나

가장 큰 실패 지점은 retrieval 자체가 아니라 retrieval을 시작하는 라우팅이었다. skill은 에이전트가 먼저 “내 지식이 낡았을 수 있다”, “이 작업은 Next.js 최신 API와 관련이 있다”, “그러니 nextjs-doc skill을 불러야 한다”고 판단해야 한다.

이 판단이 빠지면 문서가 있어도 없는 것과 비슷해진다. Vercel 실험에서 skill 기본 구성이 baseline과 같은 53%에 머문 이유도 여기에 있다. 문서를 못 읽은 것이 아니라, 읽으러 가지 않았다.

명시적 지시를 넣으면 나아졌다. 하지만 여기에도 취약점이 있었다. skill을 먼저 읽으라고 하면 문서 패턴에는 앵커링되지만 프로젝트 맥락을 덜 본다. 프로젝트 구조를 먼저 살핀 뒤 skill을 호출하게 하면 더 나았다. 같은 skill과 같은 문서라도 지시의 순서와 표현에 따라 결과가 흔들린 것이다.

왜 AGENTS.md가 이겼나

AGENTS.md는 에이전트가 문서를 찾아야 하는지 판단하는 단계를 없앤다. 프로젝트 루트의 persistent context로 들어가므로, 에이전트는 처음부터 “이 프로젝트에서는 로컬 docs가 source of truth”라는 전제를 본다.

다만 Vercel이 전체 문서를 AGENTS.md에 넣은 것은 아니다. 핵심은 압축 index였다. 긴 문서 본문은 .next-docs/ 같은 별도 위치에 두고, AGENTS.md에는 어디에 어떤 문서가 있는지 찾을 수 있는 지도만 넣었다. 이 구조가 중요하다. AGENTS.md는 지식 저장소가 아니라 retrieval router에 가깝다.

후속 맥락

Vercel은 이후에도 skill을 버리지 않았다. 2026년 6월 Teaching agents product design at Vercel에서는 AGENTS.md, skill, linter, review loop를 조합한다.

그 구조는 세 부분으로 나뉜다. repository-level AGENTS.md는 언제 skill을 로드할지 알려준다. skill-local AGENTS.md는 load order, validation, governance를 정의한다. SKILL.md는 runtime workflow를 담당한다. 즉 Vercel의 최신 패턴은 AGENTS.md를 skill trigger/router로 쓰고, skill은 깊은 판단 workflow를 맡기는 하이브리드 구조에 가깝다.

Next.js 제품 쪽에서도 이 실험은 이어졌다. Next.js 16.2는 node_modules/next/dist/docs/에 version-matched docs를 plain Markdown으로 번들링하고, AGENTS.md가 해당 문서를 읽으라고 지시하는 흐름을 공식화했다. Next.js 16.3에서는 next dev가 그 pointer를 쓰고 업데이트하는 방향까지 확장됐다.

실무 적용 원칙

AGENTS.md에는 항상 적용해야 하는 짧은 규칙과 문서 위치를 넣는다.
전체 문서를 AGENTS.md에 붙이지 말고, 압축 index나 routing directive만 둔다.
프레임워크, 사내 SDK, 결제 API처럼 자주 쓰이고 틀리면 위험한 지식은 에이전트가 스스로 필요성을 추론하게 두지 않는다.
skill은 사용자가 명시적으로 요청하는 vertical workflow에 둔다. 예를 들어 업그레이드, 마이그레이션, 감사, 릴리즈, 보안 점검 같은 작업이다.
포맷, lint, 타입, import 순서처럼 기계적으로 확인 가능한 규칙은 agent instruction보다 linter/CI로 보낸다.
AGENTS.md와 skill 모두 eval로 검증한다. 좋은 설명처럼 보여도 pass rate가 오르는지는 별개다.

한계와 주의점

이 결과를 “무조건 AGENTS.md가 skill보다 낫다”로 읽으면 안 된다. 실험 대상은 Next.js 16 API처럼 정답 문서가 있고, 모델 학습 지식이 낡았을 가능성이 높고, Build/Lint/Test로 검증하기 쉬운 영역이었다. 이런 조건에서는 persistent docs index가 특히 강하다.

반대로 디자인 리뷰, 복잡한 마이그레이션, 운영 runbook, 보안 감사처럼 절차와 판단, 도구 호출이 섞인 작업은 skill이 더 자연스럽다. Vercel의 product-design 사례도 이 방향이다.

AGENTS.md에 모든 것을 넣는 것도 위험하다. 2026년 arXiv 연구는 AGENTS.md/CLAUDE.md류 설정 파일에서 Lint Leakage, Context Bloat, Skill Leakage 같은 configuration smell이 흔하다고 보고했다. Vercel의 교훈은 “AGENTS.md를 크게 만들라”가 아니라 “항상 보여야 하는 routing information을 작게 넣으라”에 가깝다.

검증이 필요한 주장

Vercel의 pass rate는 Vercel의 내부 eval suite 기준이다. eval case 구성과 난이도를 외부에서 완전히 재현하기는 어렵다.
Next.js 16 API처럼 문서 정답이 분명한 작업에서 나온 결과를 모든 agent workflow로 일반화하면 안 된다.
AGENTS.md docs index가 항상 100%를 보장하는 것은 아니다. 문서 index 품질, 문서 구조, agent harness, 모델의 tool/file-read 행동이 함께 작동해야 한다.
skill trigger 문제는 모델과 harness가 개선되면 줄어들 수 있다.

Source Fidelity Notes

핵심 수치를 보존했다: baseline 53%, skill 기본 53%, explicit skill 79%, AGENTS.md docs index 100%, skill non-invocation 56%, explicit instruction trigger rate 95%+, 40KB에서 8KB로 압축, Build/Lint/Test 세부 지표.
원문 실험의 중심 프레임을 유지했다: skill의 실패라기보다 on-demand retrieval activation과 sequencing 문제다.
Vercel의 후속 product-design 글과 Next.js 16.2/16.3 공식 문서 흐름을 추가해, Vercel이 AGENTS.md와 skill을 대립시키지 않고 조합하는 방향으로 갔다는 맥락을 보존했다.
원문 답변에 있던 일부 설명은 중복을 줄였다. 수치, 실무 원칙, 한계는 별도 섹션에 남겼다.