▲

AGENTS.md가 에이전트 평가에서 skills보다 우수한 성능을 보임

 (vercel.com)
3P by GN⁺ 14시간전 | ★ favorite | 댓글 2개
  • 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가 이를 가장 안정적으로 구현하는 방법임
▲
channprj 3시간전  [-]

AI 코딩 에이전트는 훈련 데이터가 구버전 API에 기반해 최신 프레임워크를 정확히 다루지 못하는 한계 존재

Context7 을 사용하면 위의 문제는 어느정도 해결이 되더라고요.

https://context7.com

답변달기
▲
GN⁺ 14시간전  [-]
Hacker News 의견들

  • 모델은 AGI가 아님. 단지 텍스트 생성기로, 파일 편집이나 툴 호출 같은 효과를 일으키도록 학습된 것임
    모델이 사용자의 스킬을 “이해”해서 쓰는 게 아니라, 인간이 만든 예시와 사용 로그를 기반으로 한 강화학습(RL) 덕분에 그런 텍스트를 생성하는 것임
    스킬을 항상 쓰지 않는 이유는 아직 그런 사례가 충분히 학습되지 않았기 때문임. RL로 강제하면 오히려 모델이 더 멍청해질 수 있음
    지금은 우리가 스킬 사용 로그를 쌓아 미래 모델이 언제 스킬을 써야 하는지 더 잘 배우게 만드는 중임
    AGENTS.md는 단순히 컨텍스트임. 모델은 태초부터 컨텍스트를 따르도록 훈련되어 왔음

    • AGENTS.md와 스킬의 차이는 결국 컨텍스트에 어떻게 삽입되느냐의 문제임
      스킬의 frontmatter도 결국 컨텍스트에 포함되므로, AGENTS.md가 더 잘 작동한다면 이는 스킬 정보를 추출·주입하는 방식의 차이 때문임
      일부 에이전트는 작은 모델(예: Haiku)을 써서 어떤 스킬 정보를 큰 모델(예: Sonnet, Opus)에 전달할지 결정할 수도 있음
      결국 핵심은 어떤 정보가 “원시 프롬프트”에 들어가느냐의 문제라는 점임
    • AGI는 맞지 않음. 사실상 강화된 자동완성 수준임
      유용하지만 완벽하지 않음. GPT 기술 자체는 이미 성능 정체 구간에 들어선 듯함
      앞으로 개선될 부분은 스킬 같은 보조 시스템임. 하지만 현재 구현된 스킬 기능은 AGENTS.md를 직접 쓰는 것보다 별로임
    • 나도 비슷한 실험을 해봤음. 시스템 프롬프트에서는 관련 스킬을 미리 불러오게 하고, 사용자 프롬프트에서는 필요할 때 불러오게 하는 식으로 테스트 중임
    • RL이 뭐냐는 질문이 있었음
    • “모델은 AGI가 아니다”라는 말에 GNU/Linux 명칭 논쟁을 비유로 던진 유머 댓글이 있었음

  • 평가에서 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) 로 증명하려는 중임. 체감상 성능이 매우 좋음
답변달기