# AGENTS.md가 에이전트 평가에서 skills보다 우수한 성능을 보임 > Clean Markdown view of GeekNews topic #26262. Use the original source for factual precision when an external source URL is present. ## Metadata - GeekNews HTML: [https://news.hada.io/topic?id=26262](https://news.hada.io/topic?id=26262) - GeekNews Markdown: [https://news.hada.io/topic/26262.md](https://news.hada.io/topic/26262.md) - Type: GN+ - Author: [neo](https://news.hada.io/@neo) - Published: 2026-01-31T01:33:17+09:00 - Updated: 2026-01-31T01:33:17+09:00 - Original source: [vercel.com](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) - Points: 15 - Comments: 4 ## Summary Next.js 16 API 평가에서 **`AGENTS.md` 인덱스 방식**이 skills 기반 접근보다 월등히 높은 정확도를 보였습니다. 에이전트가 능동적으로 skill을 호출하는 대신, 프로젝트 루트의 `AGENTS.md`에 버전 일치 문서 인덱스를 항상 포함하도록 하자 모든 테스트(Build·Lint·Test)에서 100% 통과율을 기록했습니다. 결정 지점 제거와 지속적 가용성이 안정성을 높였으며, 프레임워크 유지보수자는 이 방식을 통해 코드 생성의 버전 불일치 문제를 실질적으로 줄일 수 있습니다. ## Topic Body - **Next.js 16 API**를 대상으로 한 평가에서, 프로젝트 루트에 포함된 **`AGENTS.md` 문서 인덱스**가 skills 기반 접근보다 높은 정확도를 기록 - skills는 에이전트가 필요 시 호출하는 **도메인 지식 패키지** 형태지만, 호출이 불안정해 **기본 설정에서는 53% 통과율**에 그침 - 반면, **8KB로 압축된 `AGENTS.md` 인덱스**는 모든 테스트(Build, Lint, Test)에서 **100% 통과율**을 달성 - 이 방식은 **결정 지점 제거·항상 가용성·순서 문제 해소**로 인해 능동적 호출보다 안정적인 결과를 보임 - 프레임워크 유지보수자는 **버전 일치 문서 인덱스를 AGENTS.md에 포함**해 코드 생성 정확도를 높일 수 있음 --- ### 문제 배경 - AI 코딩 에이전트는 **훈련 데이터가 구버전 API에 기반**해 최신 프레임워크를 정확히 다루지 못하는 한계 존재 - Next.js 16의 `'use cache'`, `connection()`, `forbidden()` 등은 기존 모델 학습 데이터에 없음 - 반대로 구버전 프로젝트에서는 모델이 **존재하지 않는 최신 API를 제안**하는 문제도 발생 - 이를 해결하기 위해 **버전 일치 문서 접근 방식**을 실험 ### 두 가지 접근법 - **Skills**: 프롬프트·도구·문서를 묶은 **오픈 표준 패키지**, 필요 시 에이전트가 호출해 사용 - **`AGENTS.md`** : 프로젝트 루트에 위치한 **지속적 컨텍스트 파일**, 모든 대화 턴에서 항상 참조 가능 - 동일한 Next.js 문서를 기반으로 두 방식을 비교 평가 ### Skills 접근의 한계 - 평가 결과, **56%의 테스트에서 skill이 호출되지 않음**, 기본 통과율은 **53%로 개선 없음** - 일부 항목에서는 오히려 **기준선보다 낮은 점수(예: 테스트 58% vs 63%)** 기록 - 이는 현재 모델이 **도구 사용을 안정적으로 수행하지 못하는 한계**로 지적됨 ### 명시적 지시 추가 실험 - `AGENTS.md`에 “코드 작성 전 skill을 호출하라”는 **명시적 지시문**을 추가하자 **통과율이 79%로 상승** - 그러나 **지시문 표현의 미세한 차이**가 결과에 큰 영향을 미침 - “먼저 skill을 호출하라” → 문서 패턴에 고착, 프로젝트 맥락 누락 - “프로젝트를 탐색한 후 skill을 호출하라” → 더 나은 결과 - 이러한 **언어적 취약성**으로 인해 실사용 신뢰성이 낮음 ### 신뢰 가능한 평가 구축 - 초기 테스트는 모호한 프롬프트와 중복 검증 문제로 신뢰도 부족 - 이를 개선해 **행동 기반 검증**과 **Next.js 16 비학습 API 중심 테스트**로 강화 - 주요 테스트 API: `connection()`, `'use cache'`, `cacheLife()`, `forbidden()`, `proxy.ts`, `cookies()`, `headers()`, `after()`, `refresh()` 등 ### AGENTS.md 접근의 실험 - 에이전트의 선택 과정을 제거하고, **문서 인덱스를 직접 AGENTS.md에 삽입** - 인덱스는 전체 문서가 아닌 **버전별 문서 경로 목록**으로 구성 - 추가 지시문: `IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks.` - 모델이 **기존 학습 데이터 대신 문서 기반 추론**을 우선하도록 유도 ### 평가 결과 - **AGENTS.md 인덱스 삽입 시 100% 통과율** 달성 - Build, Lint, Test 모두 완벽한 결과 - 비교 통계: - Baseline 53%, Skill 기본 53%, Skill+지시문 79%, **AGENTS.md 100%** - **수동 컨텍스트 방식이 능동 호출보다 우수**한 이유 1. 결정 지점 없음 — 항상 정보가 존재 2. 일관된 가용성 — 매 턴마다 시스템 프롬프트에 포함 3. 순서 문제 제거 — 문서 탐색 순서에 의존하지 않음 ### 컨텍스트 용량 문제 해결 - 초기 인덱스는 40KB였으나 **압축을 통해 8KB로 축소(80% 감소)** - 파이프(`|`) 구분 구조로 **문서 경로와 파일명을 최소 공간에 저장** - 에이전트는 `.next-docs/` 디렉터리에서 필요한 파일만 읽어 **정확한 버전 정보 활용** ### 적용 방법 - 명령어 한 줄로 설정 가능 ``` npx @next/codemod@canary agents-md ``` - 이 명령은 1. Next.js 버전 감지 2. 해당 버전 문서를 `.next-docs/`에 다운로드 3. 압축 인덱스를 `AGENTS.md`에 삽입 - Cursor 등 **AGENTS.md를 인식하는 에이전트**에서 동일하게 작동 ### 프레임워크 개발자에게의 시사점 - **Skills는 여전히 유용**하나, 일반적 코드 생성 정확도 향상에는 **AGENTS.md 방식이 더 효과적** - Skills는 “버전 업그레이드”, “App Router 마이그레이션” 등 **특정 작업 중심 워크플로우**에 적합 - 권장 사항: - skills 개선을 기다리지 말고 **즉시 AGENTS.md 활용** - **문서 인덱스만 포함**해 컨텍스트를 최소화 - **훈련 데이터에 없는 API 중심 평가**로 검증 - 문서를 **세분화된 검색 구조**로 설계 - 목표는 **사전 학습 중심 추론에서 검색 기반 추론으로의 전환**, `AGENTS.md`가 이를 가장 안정적으로 구현하는 방법임 ## Comments ### Comment 50342 - Author: channprj - Created: 2026-01-31T12:30:58+09:00 - Points: 1 > AI 코딩 에이전트는 훈련 데이터가 구버전 API에 기반해 최신 프레임워크를 정확히 다루지 못하는 한계 존재 Context7 을 사용하면 위의 문제는 어느정도 해결이 되더라고요. https://context7.com ### Comment 50565 - Author: slowandsnow - Created: 2026-02-04T07:56:40+09:00 - Points: 1 - Parent comment: 50342 - Depth: 1 context7이 비효율적이서 위의 두 방법을 쓰는겁니다... ### Comment 50627 - Author: channprj - Created: 2026-02-05T00:24:48+09:00 - Points: 1 - Parent comment: 50565 - Depth: 2 무엇을 말씀하고 싶으신지는 알겠습니다만, 그렇다고 매번 AGENTS.md 또는 Skills 에 현재 사용중인 모든 프레임워크/라이브러리의 최신 문서 링크를 하나하나 정리해서 넣어주는 것보단 context7 을 보조적으로 쓰는 게 그리 나쁜 선택은 아닌 것 같아요. 또한 Geeknews 와 Vercel 본문 둘 다 context7 언급이 없습니다. 선생님께서 반걸음 정도 내용을 앞서 해석하신 것 같아 답글을 남겨봅니다. (참고로 말씀드리자면 잘 작성한 Skills, AGENTS.md 로 토큰 절감이 가능한 것은 익히 알려진 사실이며 저 또한 잘 알고 있습니다.) ### Comment 50309 - Author: neo - Created: 2026-01-31T01:33:17+09:00 - Points: 1 ###### [Hacker News 의견들](https://news.ycombinator.com/item?id=46809708) - 모델은 AGI가 아님. 단지 **텍스트 생성기**로, 파일 편집이나 툴 호출 같은 효과를 일으키도록 학습된 것임 모델이 사용자의 스킬을 “이해”해서 쓰는 게 아니라, 인간이 만든 예시와 사용 로그를 기반으로 한 **강화학습(RL)** 덕분에 그런 텍스트를 생성하는 것임 스킬을 항상 쓰지 않는 이유는 아직 그런 사례가 충분히 학습되지 않았기 때문임. RL로 강제하면 오히려 모델이 더 멍청해질 수 있음 지금은 우리가 스킬 사용 로그를 쌓아 미래 모델이 언제 스킬을 써야 하는지 더 잘 배우게 만드는 중임 AGENTS.md는 단순히 **컨텍스트**임. 모델은 태초부터 컨텍스트를 따르도록 훈련되어 왔음 - AGENTS.md와 스킬의 차이는 결국 **컨텍스트에 어떻게 삽입되느냐**의 문제임 스킬의 frontmatter도 결국 컨텍스트에 포함되므로, AGENTS.md가 더 잘 작동한다면 이는 스킬 정보를 추출·주입하는 방식의 차이 때문임 일부 에이전트는 작은 모델(예: Haiku)을 써서 어떤 스킬 정보를 큰 모델(예: Sonnet, Opus)에 전달할지 결정할 수도 있음 결국 핵심은 어떤 정보가 “원시 프롬프트”에 들어가느냐의 문제라는 점임 - AGI는 맞지 않음. 사실상 **강화된 자동완성** 수준임 유용하지만 완벽하지 않음. GPT 기술 자체는 이미 **성능 정체 구간**에 들어선 듯함 앞으로 개선될 부분은 스킬 같은 보조 시스템임. 하지만 현재 구현된 스킬 기능은 AGENTS.md를 직접 쓰는 것보다 별로임 - 나도 비슷한 실험을 해봤음. 시스템 프롬프트에서는 관련 스킬을 미리 불러오게 하고, 사용자 프롬프트에서는 필요할 때 불러오게 하는 식으로 테스트 중임 - RL이 뭐냐는 질문이 있었음 - “모델은 AGI가 아니다”라는 말에 [GNU/Linux 명칭 논쟁](https://en.wikipedia.org/wiki/GNU/Linux_naming_controversy)을 비유로 던진 유머 댓글이 있었음 - 평가에서 56%의 경우 스킬이 한 번도 호출되지 않았다는 결과가 있었음. 문서를 갖고 있었지만 사용하지 않았다는 뜻임. “튜링 테스트는 통과했네…”라는 농담이 붙음 - “AI도 **RTFM**(매뉴얼 안 읽음)”이라는 재치 있는 반응이 있었음 - 나도 웃었지만, 진지하게 말하자면 인간도 신뢰할 수 없는 경우가 많음 차이라면 AI는 **자존심 없이 수정 지시를 받아들임** 아직 시니어 개발자 수준은 아니지만, 주니어보다는 지시를 잘 따르는 편임 - 핵심 발견은 문서 포인터의 **압축(compression)** 이 효과적이라는 점임 인간이 읽기엔 어렵지만 LLM에게는 직접적이고 효율적인 참조 구조임 앞으로는 agents.md/claude.md/skills.md 같은 휴리스틱 대신, 항상 로드되는 **압축 인덱스 포맷**이 표준화될 가능성이 큼 API 테스트 스위트를 LLM 코드 성능 검증에 재활용할 수도 있음 LLM 도입이 커질수록, 라이브러리와 API도 이에 맞춰 진화해야 함 - 또 하나의 교훈은 “**프로젝트를 먼저 탐색한 뒤 스킬을 호출**”하는 게 “무조건 스킬을 써라”보다 낫다는 점임 Antigravity(=GEMINI.md 기반)에서 AGENTS.md 규칙을 따르도록 했지만 무시됨 대신 “프로젝트에 AGENTS.md가 있는지 확인하라”는 프롬프트는 항상 작동했음 예전 “let’s think step by step”이 체인 오브 쏘트를 유도하던 시절처럼 신기한 현상임 - “압축”이라지만 사실상 **minify** 수준 아니냐는 반응도 있었음 - 파이프 대신 줄바꿈을 썼으면 더 읽기 쉬웠을 거라는 의견도 있었음 - AGENTS.md를 시스템 프롬프트에 직접 포함하면 항상 컨텍스트에 들어감 하지만 모든 스킬을 매번 포함하는 건 낭비임. 그래서 **Anthropic의 advanced tool use**처럼 필요한 순간에만 불러오는 접근이 필요함 결국 **컨텍스트와 비용의 균형** 문제임. 여유가 있다면 AGENTS.md에 압축해 넣는 게 효율적임 - 스킬도 결국 컨텍스트 안에서 선언됨. 단순히 AGENTS.md에 압축해 넣는 게 더 잘 작동하는 듯함 - Vercel이 스킬과 컨텍스트 설정을 혼동한 것 같음. 두 개는 전혀 다른 목적을 가지므로 **둘 다 함께 써야 함** - **RLM 접근법**이 잘 작동하는 이유도 여기에 있음. 필요한 정보만 컨텍스트에 넣고, 나머지는 환경에 남겨두는 구조임 이런 **자기 컨텍스트 관리형 에이전트**는 올해 크게 발전할 것 같음 - 결국 둘 다 필요함. 일부는 강제로 컨텍스트에 넣고(index/sparknotes), 일부는 탐색·검색 기반으로 동적으로 추가해야 함 - 개인 사용자는 시스템 프롬프트만 수정하면 되지만, 팀 단위에서는 코드 스타일 같은 표준을 위해 스킬을 써야 함 **Claude의 스킬 준수율이 낮음** - 나도 비슷한 영역에서 작업 중임. **프로젝트 스캐폴딩 구조**가 Claude Code/Opencode 결과에 어떤 영향을 주는지 평가하려 함 하지만 Vercel의 테스트 방식이 명확하지 않아 비교가 어려움 - AGENTS.md는 스킬과 완전히 다른 게 아니라, **스킬의 단순화된 형태**임 핵심은 스킬 설계 품질, 즉 AI가 올바른 정보를 찾기까지 거치는 **단계 수를 최소화**하는 것임 단계가 적을수록 오류 누적이 줄어듦 - 나도 두 가지로 나눠 관리함 1) 규칙 기반으로 시스템 프롬프트에 강제 삽입되는 것 2) 에이전트가 필요할 때 탐색하는 것 그리고 토큰 낭비를 줄이기 위해 큰 파일은 시스템 프롬프트에만 한 번 넣음 - 블로그에서 프롬프트 엔지니어링 비교할 때마다 궁금한 점은, **한 번만 실행했는지 여러 번 반복했는지**임 LLM은 같은 입력에도 결과가 일정하지 않음 - 이런 비결정적 결과를 과학처럼 발표하는 게 답답함 대부분 **일화 수준의 데이터**를 과학처럼 포장하는 느낌임 - 나도 항상 여러 번 반복 실행해 신뢰 구간을 계산함 하지만 정성껏 벤치마크하면 조회수는 적고, 대충 하면 블로그 트래픽이 9배 늘어남 **왜곡된 인센티브 구조**가 문제임 - AGENTS.md보다 더 나은 방법도 있음 `.context` 폴더를 만들어 프로젝트 관련 문서(README, 의존성 문서 등)를 심볼릭 링크로 넣고, 항상 컨텍스트에 로드되게 하는 것임 이렇게 하면 LLM이 처음부터 필요한 정보를 다 갖게 되어 **성능 향상과 비용 절감**이 가능함 - 하지만 의존성 문서는 큰 차이를 만들지 않음. 대신 **소스 코드 자체**를 `_vendor` 폴더에 넣는 게 훨씬 유용함 LLM이 직접 코드를 분석해 동작을 이해할 수 있음 - 모든 문서를 매번 로드하는 건 비효율적임. 차라리 Claude.md나 Agents.md에 위치만 명시하고 필요할 때 읽게 하는 게 낫다는 의견도 있었음 - 컨텍스트를 불필요하게 부풀리면 안 됨. 대신 **문서 인덱스만 압축해 넣는 방식**이 더 효율적임 - 큰 파일을 매번 넣는 건 **토큰 낭비**임. Claude Code 블로그에서도 같은 경고가 있었음 - 나의 커스텀 에이전트를 만들며 얻은 경험임 1) Claude Code의 추출 지침을 참고함 2) AGENTS.md를 **목차와 요약(sparknotes)** 용으로 자동 로드함 3) 주제별 마크다운 파일을 스킬로 관리함 4) MCP와 스킬은 개념적으로 비슷하므로 좋은 툴을 만드는 게 핵심임 5) 계속 실험하고 즐기며 개선 중임 read/write_file을 상태에 넣고 시스템 프롬프트에 표시하도록 바꿨더니 훨씬 잘 작동함 지금은 이를 **정량 평가(evals)** 로 증명하려는 중임. 체감상 성능이 매우 좋음