2026.02.05 / JUN.NXP
이번 포스트는 Vercel이 작성한 AGENTS.md outperforms skills in our agent evals 포스트 리뷰 후기이며, AI 코딩 에이전트 최적화를 위한 기술 통합 전략으로 AGENTS.md를 이용한 검색 중심 추론의 구현 방법에 대해 알아봅니다.
Vercel | AGENTS.md outperforms skills in our agent evals
https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals
1. 서론: 현대 소프트웨어 개발에서 AI 에이전트의 역할과 한계
현대 소프트웨어 개발 워크플로우에서 AI 코딩 에이전트는 생산성 가속을 위한 핵심 아키텍처 구성 요소로 자리 잡았습니다. 그러나 시스템 아키텍트의 관점에서 볼 때, 에이전트의 실질적인 효용성은 모델의 파라미터 규모나 벤치마크 점수가 아닌 ‘프로젝트 컨텍스트의 가용성’에 의해 결정됩니다. 현재 대규모 언어 모델(LLM) 기반 에이전트가 직면한 가장 심각한 전략적 장애물은 지식의 파편화와 이로 인해 발생하는 ‘컨텍스트 엔트로피(Contextual Entropy)’입니다.
본 문서는 에이전트가 보유한 지능을 실제 프로덕션 수준의 코드 생성 성능으로 전환하는 데 있어 가장 큰 걸림돌인 ‘지식 컷오프 부채(Knowledge-cutoff Debt)’를 분석합니다. 우리는 단순히 새로운 도구를 도입하는 수준을 넘어, 에이전트의 추론 프로세스를 결정론적(Deterministic) 구조로 정박시킬 수 있는 전략적 표준으로서 AGENTS.md 기반의 수동적 컨텍스트 제공 방식을 제안합니다.
2. 프레임워크 가시성 문제: 최신 API와 학습 데이터의 괴리
AI 모델의 사전 학습 데이터 컷오프는 기술 스택이 진화할수록 심각한 기술적 부채를 야기합니다. 에이전트는 자신이 학습한 시점의 지식을 바탕으로 추론을 시도하지만, 이는 최신 프레임워크의 아키텍처 표준과 충돌하며 시스템의 안정성을 저해합니다.
Vercel의 최신 사례를 보면, Next.js 16에서 도입된 use cache 지시어, connection(), forbidden(), cacheLife()와 같은 신규 API는 현재 상용 모델들의 학습 데이터에 존재하지 않습니다. 이러한 지식 공백 상황에서 에이전트는 다음과 같은 치명적인 오류를 범합니다.
- 비결정적 코드 생성: 존재하지 않는 레거시 API를 제안하거나, 최신 기능을 구현하기 위해 불필요하게 복잡하고 성능이 낮은 우회 로직을 설계합니다.
- 과거 패턴으로의 회귀: 프레임워크가 지향하는 최신 최적화 경로 대신, 이미 감가상각된(Deprecated) 구식 코딩 패턴을 적용하여 유지보수 비용을 폭증시킵니다.
이러한 문제는 단순한 정보 부족의 문제가 아니라, 에이전트가 생성하는 코드의 신뢰성 자체를 붕괴시키는 전략적 리스크입니다. 이를 해결하기 위해 아키텍트들은 도구 호출(Tool Calling)에 의존하는 ‘능동적 스킬(Skills)’과 상시 노출형 인덱스인 ‘수동적 컨텍스트(AGENTS.md)’ 중 하나를 선택해야 하는 기로에 서 있습니다.
3. 통합 방법론 비교 분석: 능동적 스킬(SKILL) vs. 수동적 컨텍스트(AGENTS.md)
에이전트의 지식 보강을 위한 두 패러다임은 설계 철학에서 극명한 차이를 보입니다.
능동적 스킬 (Skills): 확률적 의사결정의 취약성
스킬은 온디맨드 호출 방식으로, 에이전트가 필요 시 특정 도구나 문서를 로드하는 ‘관심사의 분리’ 모델을 지향합니다. 이론적으로는 효율적이지만, 실제 워크플로우에서는 에이전트가 “언제 정보를 찾아야 하는가”를 판단해야 하는 확률적 결정 지점(Stochastic Decision Point)이 병목이 됩니다. 특히 소스 데이터에 따르면 “You MUST invoke the skill”과 같은 강제적 명령은 에이전트가 프로젝트 전체 컨텍스트를 무시하고 문서 패턴에만 매몰되게 만드는 등 워딩의 미세한 차이에 따라 결과의 파편화(Fragility)가 심각하게 발생하는 것으로 나타났습니다.
수동적 컨텍스트 (AGENTS.md): 결정론적 인덱싱
AGENTS.md(또는 Claude Code의 CLAUDE.md)는 프로젝트 루트에 상주하며 에이전트의 모든 턴에 지속적인 컨텍스트를 주입합니다. 이는 에이전트의 의사결정 프로세스에서 “정보를 찾을지 말지”에 대한 불확실성을 완전히 제거합니다. 에이전트는 행동을 시작하기 전, 이미 가시 범위 내에 존재하는 표준 가이드라인에 따라 사고 체계를 정렬할 수 있습니다.
4. 성능 평가 데이터 기반의 의사결정 정당화: 신뢰성 갭의 완화
Vercel이 실시한 하드닝(Hardened) 평가 스위트 결과는 확률적 워크플로우에서 발생하는 신뢰성 결함(Reliability Gap)을 명확히 보여줍니다.
| 구성 (Configuration) | 통과율 (Pass Rate) | 상세 지표 (Build/Lint/Test) | 분석 결과 |
| Baseline (No Docs) | 53% | 84% / 95% / 63% | 학습 데이터 컷오프의 한계 명확 |
| Skill (Default Behavior) | 53% | 84% / 89% / 58% | 노이즈 주입 효과: 미사용 스킬로 인해 성능 저하 발생 |
| Skill w/ Instructions | 79% | 95% / 100% / 84% | 지시어 최적화 시 개선되나 100% 도달 실패 |
| AGENTS.md (Index) | 100% | 100% / 100% / 100% | 결정 지점 제거를 통한 완벽한 통과 |
데이터 분석 결과, 기본 스킬 구성의 경우 56%의 케이스에서 스킬이 호출조차 되지 않았습니다. 더욱 주목할 점은 스킬을 보유하고도 사용하지 않을 경우, 오히려 테스트 통과율이 Baseline(63%)보다 낮은 58%로 하락했다는 것입니다. 이는 환경 내의 정제되지 않은 도구가 에이전트에게 ‘노이즈’로 작용하여 추론의 정확도를 저해할 수 있음을 시사합니다. 반면 AGENTS.md는 에이전트의 의사결정 트리에서 실패 가능성을 원천 차단하며 성능 우위를 확보했습니다.
5. 검색 중심 추론(Retrieval-Led Reasoning) 체계의 구축
성능 극대화의 핵심은 ‘사전 학습 중심 추론’에서 ‘검색 중심 추론’으로의 패러다임 전환입니다. AGENTS.md 내에 삽입되는 다음 명령문은 에이전트의 확률적 사고 프로세스를 제어하는 핵심 앵커(Anchor) 역할을 합니다.
“IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks.”
이 지시어는 에이전트가 자신의 내부 기억(확률적 가중치)에 의존하기 전에, 반드시 외부 인덱스를 먼저 참조하도록 강제합니다. 이는 프레임워크 버전별 정확도를 보장하는 유일한 결정론적 방법입니다. 에이전트는 이 명령을 통해 자신의 지식이 오래되었을 가능성을 인지하고, 제공된 지도를 바탕으로 최신 표준을 탐색하는 프로세스를 우선순위에 두게 됩니다.
6. 컨텍스트 최적화: 압축된 문서 인덱스 및 “Map-and-File” 패턴
대규모 컨텍스트 주입 시 우려되는 토큰 팽창(Context Bloat)을 해결하기 위해, 본 전략은 ‘압축된 문서 인덱스’ 구조를 채택합니다.
- 압축 기술 및 구조: 40KB에 달하는 전체 문서를 직접 주입하는 대신, 파이프 구분 기호(
|) 기반의 인덱스 구조를 통해 8KB로 80% 이상 압축합니다. 이는 에이전트에게 전체 지식을 강요하는 것이 아니라, 특정 정보가 담긴 파일의 위치를 알려주는 ‘지도’ 역할을 수행합니다. - Map-and-File 전략: 에이전트는
AGENTS.md에서 인덱스(Map)를 확인한 후, 실제 상세 정보가 필요할 때만.next-docs/디렉토리에 로컬로 저장된 특정.mdx파일(File)을 읽어 들입니다. 이 방식은 탐색 속도와 컨텍스트 효율성을 동시에 극대화합니다. - 구현 자동화:
npx @next/codemod@canary agents-md명령어를 통해 프로젝트 버전을 감지하고, 해당 버전에 맞는 문서를.next-docs/에 로컬 캐싱하며, 최적화된 인덱스를AGENTS.md에 자동으로 삽입하는 워크플로우를 구축할 수 있습니다.
7. 결론: 차세대 프레임워크 표준으로서의 수동적 컨텍스트
AI 코딩 에이전트의 최적화 전략은 에이전트의 자율적 지능에 의존하는 스토카스틱(Stochastic) 모델에서, 명확한 가이드를 제공하는 결정론적(Deterministic) 모델로 진화해야 합니다.
- 공격적인 압축 및 인덱싱: 전체 문서 대신 에이전트가 필요한 정보의 위치를 신속히 파악할 수 있는 고밀도 인덱스를 제공하십시오.
- 검색 중심 추론의 강제: 모델의 사전 학습 데이터보다 검색된 실시간 컨텍스트를 우선시하도록 에이전트의 사고 체계를 정렬하십시오.
- 이원화된 보완 관계: 능동적 스킬(Skills)은 마이그레이션이나 업데이트와 같은 ‘수직적 액션’에,
AGENTS.md는 프레임워크 표준과 같은 ‘수평적 지식 기반’에 배치하십시오.
결국 AI 에이전트가 최신 표준에 부합하는 코드를 생성하게 만드는 최단 경로는 에이전트의 의사결정 부담을 줄여주는 ‘수동적 컨텍스트의 표준화’에 있습니다. 시스템 아키텍트들은 이러한 구조적 접근을 통해 AI 협업의 신뢰성을 확보하고 소프트웨어 품질의 상향 평준화를 달성해야 합니다.
