Vercel 실험의 결과는 무엇이었나
Vercel은 AI에게 최신 지식을 주는 두 방식을 같은 시험지로 겨루게 했습니다. 하나는 필요할 때 꺼내 보는 전문 매뉴얼 묶음인 Skill, 다른 하나는 프로젝트 폴더에 늘 펼쳐진 텍스트 한 장 AGENTS.md입니다. 문제는 일부러 어렵게, 학습 시점 이후에 나온 최신 기능만으로 냈습니다.
점수가 모든 걸 말해 줍니다. 아무 지원 없는 맨몸이 53점, Skill을 주고 알아서 쓰라고 두었더니 똑같은 53점, 반드시 쓰라고 강하게 지시하자 79점, 그리고 AGENTS.md는 100점이었습니다. 빌드도 검사도 테스트도 전부 만점이었습니다. 정교한 방식이 투박한 방식에 진 것입니다.
Skill은 왜 졌는가
첫째, AI가 매뉴얼을 꺼내 보지 않았습니다. 매뉴얼이 있는 걸 알면서도 열 번 중 여섯 번은 그냥 지나쳤습니다. 있는 줄 알지만 옛날에 외운 지식으로 일해 버리니 틀립니다.
둘째, Skill은 지나치게 예민했습니다. '매뉴얼부터 봐라'와 '프로젝트 먼저 보고 매뉴얼 봐라'처럼 단어 순서만 바꿔도 점수가 출렁였습니다. 지시를 아주 정확히 하지 않으면 언제 어긋날지 모른다는 뜻입니다.
AGENTS.md는 왜 이겼는가
이유는 의외로 단순합니다. AI에게 선택을 안 시킨 것입니다. Skill은 매 순간 지금 꺼낼지 말지 고민해야 하고, 그 고민하는 지점이 바로 실수가 터지는 자리입니다. AGENTS.md는 이미 눈앞에 있으니 꺼낼지 말지, 언제 볼지, 어떤 순서로 볼지 고민할 필요가 없습니다.
선택을 시키면 틀리고, 선택을 안 시키면 안 틀립니다. 우리는 더 똑똑한 도구를 붙이면 나아질 거라 믿지만, 도구가 똑똑할수록 그걸 쓸지 말지 재다가 삐끗합니다. 차라리 정보를 눈앞에 상시로 펼쳐 두는 편이 낫습니다.
그럼 Skill은 언제 쓰는가
Skill이 죽은 것은 아닙니다. 프로젝트를 통째로 새 버전으로 이관하거나 전체 구조를 바꾸는 것처럼, 내가 시점을 정해 지금 이걸 하라고 직접 부르는 큰 작업에는 Skill이 제격입니다.
정리하면 둘 중 하나만 쓰는 게 아닙니다. 늘 필요한 기본 지식은 AGENTS.md로 항상 펼쳐 두고, 특별한 큰 작업은 그때그때 Skill로 부르는 분업이 정답입니다.
실무에 어떻게 적용하는가
프로젝트 맨 위 폴더에 AGENTS.md를 하나 만들고, AI가 꼭 알아야 할 규칙을 길게 쓰지 말고 목차처럼 핵심만 짧게 적습니다. Vercel은 실제로 문서를 40k에서 8k로, 80%나 압축했는데도 점수는 그대로 100점이었습니다. 전체 대신 목차만 남긴 것이 오히려 더 깔끔했습니다.
그리고 문서 맨 위에 이 한 줄을 꼭 넣습니다. 외운 지식 말고 이 문서를 먼저 보고 판단하라. AI는 자꾸 옛 기억으로 일하려 하는데, 이 한 문장이 그걸 막아 줍니다. 100점과 53점을 가른 것이 바로 이 한 줄입니다.