왜 스킬이 졌을까 — Vercel 실험으로 본 Skills vs AGENTS.md

01핵심 개요

02실험 설계 — 4가지 조건, 가장 어려운 시험

AI가 한 번도 본 적 없는 Next.js 16 신기능으로만 시험지를 구성하고 4가지 조건을 비교:

Vercel은 보고서에 "멍청한 방식이 정교한 방식을 이겼다"고 적었다.

03왜 Skills가 졌나

첫째, AI가 매뉴얼을 그냥 안 꺼내 본다 — 10번 중 약 6번을 존재를 알면서도 안 펼치고 자기 옛 기억으로 일해버린다. 둘째, 지시 문구에 지나치게 민감하다 — "무조건 매뉴얼부터 봐"라고 하면 프로젝트는 안 보고, "프로젝트 먼저 보고 매뉴얼 봐"라고 단어 순서만 바꾸면 제대로 동작. 즉 정확히 지시하지 않으면 언제 삐끗할지 모른다.

04왜 AGENTS.md가 이겼나

① 고민할 순간이 없다 — 매뉴얼을 볼지 말지 결정하는 그 순간이 실수 지점인데, 메모지는 이미 눈앞에 있어 결정이 불필요. ② 항상 모든 순간 거기 있다 — 부르는 타이밍을 놓칠 수 없다. ③ 순서 고민이 없다 — 자연스럽게 코드와 함께 본다. 결국 비결은 'AI에게 선택을 안 시킨 것'.

05핵심 교훈 — 똑똑함보다 '헷갈릴 틈 없애기'

도구가 똑똑할수록 AI는 '쓸지 말지' 고민하다 삐끗한다. 능동적으로 찾아 쓰게 하지 말고, 가만히 있어도 보이게 정보를 눈앞에 펼쳐 주는 것이 현재 AI를 다루는 핵심.

06영리한 보완 — 80% 압축

문서가 너무 길면(책 한 권을 책상에 펼친 격) 오히려 헷갈린다. Vercel은 전체 내용 대신 '목차만' 넣어 분량을 약 40k→8k로 80% 줄였는데도 점수는 그대로 100점. 핵심만 남기니 더 깔끔해졌다.

07Skills가 빛나는 경우 — 역할 분담

Skills가 쓸모없는 건 아니다. '내가 시점을 정해 직접 부르는 특별한 큰 작업'(예: 프로젝트 전체를 3버전으로 마이그레이션)에 적합. 정리하면: 평소 기본 지식은 AGENTS.md로 항상 펼쳐 두고, 특별한 대형 작업은 Skills로 명시 호출 — 둘을 나눠 쓰는 것이 정답.

08실전 적용법

Next.js 사용자는 터미널에 한 줄(npx next codemod ... AGENTS.md 류)이면 ① 프로젝트 버전 확인 ② 맞는 문서 다운로드 ③ 목차 압축 후 AGENTS.md에 자동 삽입까지 처리. Next.js를 안 써도 원리는 동일: 프로젝트 최상위에 AGENTS.md를 만들고 규칙(색상·폰트·폴더 구조)을 목차처럼 짧게 적되, 문서 맨 위에 "외운 지식 말고 이 문서를 먼저 보고 판단해" 한 줄을 반드시 넣는다 — 이 한 줄이 100점과 53점을 가른다.

09시사점

이 실험은 단순한 파일 형식 비교가 아니라 'AI를 어떻게 다룰 것인가'의 본질을 보여준다. 똑똑한 자동화(능동적 도구 호출)에 의존하기보다, 선택지를 줄이고 컨텍스트를 항상 노출하는 결정론적 설계가 더 신뢰성 있다는 교훈. 자동은 될 때도 안 될 때도 있지만 수동·상시 노출은 100%에 가깝다.

10용어 사전