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

• 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가 이를 가장 안정적으로 구현하는 방법임