AI 코딩 에이전트에게 똑똑한 도구를 갖춰주면 똑똑하게 일해줄 것이다. 막연히 그렇게 생각했습니다. Vercel이 공개한 검증 데이터는 그 반대를 보여줍니다. 프로젝트에 두기만 한 평범한 텍스트 파일이, 에이전트가 필요할 때 호출하는 「똑똑한」 Skill (스킬)을 이겼습니다. 그것도 근소한 차이가 아니었습니다.

사실 데이터를 보기 전부터 저도 어렴풋이 같은 것을 느끼고 있었습니다. 그래서 이 결과가 꽤 뼈아프게 다가왔습니다. 무엇이 일어난 것인지, 왜 단순한 쪽이 이겼는지, 그리고 제가 바꾼 습관 하나를 적어보겠습니다.

검증 내용

Vercel이 측정한 것은 에이전트가 얼마나 정확하게 Next.js 16 코드를 작성할 수 있는가입니다. 게다가 모델이 거의 본 적 없는 API들만을 골랐습니다. 학습 데이터의 컷오프(Cutoff) 이후에 나온 것들이기 때문입니다. connection(), 'use cache' 디렉티브, cacheLife() / cacheTag(), forbidden() / unauthorized(), proxy.ts, 비동기 cookies() / headers(), after() 정도입니다. 일부러 새로운 영역으로만 구성하여 암기한 지식이 통하지 않도록 했습니다.

동일한 어려운 테스트를 4가지 조건으로 풀게 했습니다.

이 표는 다시 한번 확인해 주세요. Skill을 전달하며 "필요하면 사용해도 좋아"라고 맡긴 결과는, **아무것도 전달하지 않았을 때와 완전히 동일한 53%**였습니다. 강하게 "사용하라"고 지시해서야 겨우 79%. 그리고 프로젝트 루트에 두기만 한 AGENTS.md가 만점이었습니다.

Skill이 성장하지 못한 이유

Skill은 언뜻 보면 똑똑한 선택지로 보입니다. 평소에는 방해하지 않다가, 필요해 보이는 태스크가 있을 때 에이전트가 스스로 가져옵니다. 효율적으로 들립니다. 문제는 그 "판단하는" 지점에 있습니다.

56%의 케이스에서 Skill은 단 한 번도 호출되지 않았습니다. 문서는 손에 쥐고 있는데, 에이전트가 "지금이야말로 가져와야 할 순간이다"라는 시점을 인식하지 못했습니다. 이는 제가 평소에 맞닥뜨리던 문제와 같습니다. 제대로 된 Skill을 준비해 두었는데, 막상 그 작업을 수행할 때 에이전트가 그것을 그냥 지나쳐 버립니다. 체감상 열 번 중 여섯 번 정도였습니다. 제 설정이 잘못된 것이라고 생각했습니다. 하지만 판단하는 단계 자체가 구멍이었던 것입니다.

게다가 훨씬 더 취약합니다. Vercel은 지시의 말투를 조금 바꾸는 것만으로도 거동이 크게 흔들린다는 것을 발견했습니다.

• **"반드시 Skill을 호출하라"**고 쓰면, 에이전트는 문서에 끌려가 프로젝트 측을 놓쳤습니다. page.tsx는 고칠 수 있었지만, 필수적이었던 next.config.ts의 변경을 통째로 놓쳤습니다.
• **"먼저 프로젝트를 조사한 뒤 Skill을 호출하라"**고 순서를 지정하면, 먼저 상황을 파악한 뒤에 문서를 보러 가서 정답률이 올라갔습니다.

같은 도구라도 문장 하나를 재배열했을 뿐인데 출력이 달라집니다. 이 정도로 말투에 민감한 메커니즘은 실운용에서 신뢰하기 어렵습니다.

단순한 파일이 이긴 이유

AGENTS.md는 "단순한" 쪽입니다. 프로젝트 루트에 둔 텍스트 파일이 매 턴 그냥 그 자리에 있습니다. 가져오는 단계가 없습니다. Vercel 자신의 표현이 바로 핵심입니다.

AGENTS.md라면 에이전트가 "이것을 조사해야 할까?"라고 판단하는 순간 자체가 존재하지 않습니다. 정보는 처음부터 거기에 있습니다.

가져올지 말지를 결정하는 단계가 통째로 사라집니다. 그곳은 Skill이 56% 실패했던 지점이었습니다. 결정하는 순간이 없다면 놓칠 리가 없습니다. 매 턴 문맥(Context)에 포함되어 있으므로 호출 타이밍을 놓칠 일도 없고, "먼저 코드를 봐라"라고 순서를 신경 쓸 필요도 없습니다. 처음부터 코드 옆에 있기 때문입니다.

여기서 효과를 본 것은 AGENTS.md가 특별히 똑똑해서가 아니라, 애초에 "읽을지 말지"를 에이전트에게 맡기지 않았다는 점 하나였습니다. Skill은 호출되지 않으면 없는 것과 마찬가지지만, 루트 파일은 처음부터 눈에 들어와 있습니다. 그 차이가 그대로 결과로 나타난 것으로 보입니다.

간과하기 쉬운 점: 압축하고 있었다

따라 하고 싶다면, 이 부분이 중요합니다. Vercel은 문서 전체를 AGENTS.md에 붙여넣은 것이 아닙니다. 인덱스(Index)로 압축했습니다. 원래 40KB였던 것을 8KB까지, 80%를 깎아냈음에도 점수는 100% 그대로였습니다. 이 파일은 문서 그 자체가 아니라, "어떤 내용이 어떤 문서의, 이 프로젝트 버전과 대응하는가"를 나타내는 짧은 지도입니다. 책 전체를 책상 위에 펼쳐 놓으면 정작 중요한 작업 공간이 사라집니다. 그래서 인덱스에 머무는 것입니다.

시도해 보기 (Next.js)

Next.js라면 한 줄로 설정할 수 있습니다. 버전을 감지하고, 대응하는 문서를 가져와서, 인덱스로 압축하여 AGENTS.md를 써 내려가는 과정까지 자동으로 수행해 줍니다.

npx @next/codemod@canary agents-md

Next.js가 아니더라도 생각하는 방식은 같습니다. 프로젝트 루트에 AGENTS.md를 두고, 산문(Prose)이 아닌 인덱스로써 자신의 규칙을 짧게 작성하세요. 어떤 폴더에 무엇이 있는지, lint와 테스트 명령어, 실제로 사용 중인 패턴 등입니다. 그리고 서두 부근에 에이전트를 자신의 기억으로부터 떼어놓는 한 문장을 넣으세요. "과거의 지식에 의존하기 전에, 프로젝트와 이 문서들을 확인할 것" 정도의 한 문장입니다. 이 작은 한 방이 53점과 100점을 가르는 요소 중 일부가 됩니다.

Skill은 여전히 사용한다, 용도를 좁혔을 뿐

Skill을 버리는 것이 아닙니다. 향하는 곳을 바꿨을 뿐입니다. 에이전트가 매번 필요로 하는 지루한 기초 지식은 AGENTS.md에 둡니다. Skill은 자신이 명시적으로 호출하는 무거운 작업, 즉 "Next.js 버전을 올려줘", "App Router로 마이그레이션해줘"와 같은 작업들을 위해 남겨둡니다. Vercel도 같은 선을 긋고 있습니다. 제가 저질렀던 실수는 일상적인 문맥까지 Skill에 의존하며, 에이전트가 알아서 가져가 주기를 기대했다는 점입니다. 에이전트는 거의 가져오지 않았습니다.

한 가지 걸리는 점

실제로 제 손으로 직접 테스트해 보았을 때 고개를 끄덕일 수 있는 부분이 많았습니다. 다만, 이것이 어디까지 일반화될 수 있을지는 솔직히 아직 잘 모르겠습니다. 이번 테스트는 Next.js 코드 생성이라는, 비교적 유형이 명확한 영역의 이야기입니다. 제가 종사하는 산업 도메인이나 팀의 성격이 바뀐다면 결론도 달라지지 않을까 생각합니다. 예를 들어 전제 지식을 문서화하기 어려운 업무나, 매번 상당히 다른 판단이 필요한 영역이라면 "인덱스를 항상 준비해 두는" 방식이 그대로 효과를 발휘할지는 미지수입니다. 그래서 저는 이 결과를 "정답"이 아니라 "내 환경에서 한 번 확인해 볼 가치가 있는 가설" 정도로 받아들이고 있습니다.

제가 여기서 얻은 교훈

흥미로운 점은 파일 형식이 아니라, 호출되지 않았던 쪽의 사실입니다. 이전에는 에이전트의 자율성을 높이고, 똑똑한 검색이나 사용할 수 있는 도구를 늘리면 출력이 좋아질 것이라고 생각했습니다. 이번 검증을 통해 그 부분을 조금 불신하게 되었습니다. "지금 문서를 보러 가야 하는가?"라는 판단조차 결국 절반 이상의 확률로 틀리는 판단이었던 셈입니다. 결국 제가 바꾼 것은 상당히 수수한 부분이었습니다. 에이전트에게 "필요하면 보러 가"라고 넘겨주는 것을 그만두고, 처음부터 눈에 보이는 곳에 두는 것. 지금은 그 정도면 충분하다고 생각합니다.

참고로, 이 실험과 수치는 모두 Vercel의 것입니다. 원문은 읽어볼 가치가 있습니다: AGENTS.md outperforms skills in our agent evals.

Discussion