AGENTS.md 문서 색인이 스킬보다 효과적인 구성
Next.js 문서 지식을 에이전트에 전달할 때 스킬보다 AGENTS.md에 넣은 압축 색인이 더 높은 성능을 보였습니다.
교안에 영향
기존의 Skills 안내만으로는 Next.js 문서 지식 전달이 충분하지 않아, AGENTS.md 문서 색인을 함께 안내해야 할 수 있습니다.
요약
- Skills와 AGENTS.md를 비교한 결과, Next.js 16 API 평가에서 AGENTS.md 문서 색인이 더 높은 통과율을 보였습니다. - 기본 동작의 Skills는 충분히 자주 호출되지 않았고, 명시적 지시를 넣어도 문구에 따라 결과가 크게 달라졌습니다. - AGENTS.md에 압축된 docs index를 넣는 방식은 Build, Lint, Test에서 모두 더 안정적인 결과를 냈습니다. - `npx @next/codemod@canary agents-md`로 버전에 맞는 문서를 내려받고 AGENTS.md를 주입할 수 있습니다.
바뀐 것
기타
- Skills와 AGENTS.md를 비교한 평가에서 AGENTS.md 문서 색인이 Skills보다 더 나은 결과를 보였습니다.
- Skills는 기본 동작에서 56%의 평가 사례에서 호출되지 않았고, 기준 성능도 개선하지 못했습니다.
- AGENTS.md에 명시적 지시를 넣으면 호출률이 95% 이상으로 올라가고 통과율도 79%까지 개선됐습니다.
- 지시 문구에 따라 에이전트의 동작이 크게 달라져, 먼저 탐색한 뒤 skill을 쓰는 방식이 더 나은 결과를 보였습니다.
- 평가용 테스트를 정리해 모호한 프롬프트와 테스트 누수를 줄이고, 모델 학습에 없는 Next.js 16 API를 중심으로 다시 구성했습니다.
- AGENTS.md에 전체 문서 대신 압축된 docs index를 넣는 방식이 도입됐고, 약 40KB였던 주입 내용을 8KB로 줄이면서도 100% 통과율을 유지했습니다.
- `npx @next/codemod@canary agents-md` 명령으로 현재 프로젝트의 Next.js 버전을 감지해 맞는 문서를 내려받고 AGENTS.md를 주입할 수 있게 했습니다.
- Skills는 사용자가 직접 트리거하는 업그레이드나 마이그레이션 같은 작업에, AGENTS.md 방식은 일반적인 프레임워크 지식 전달에 더 적합하다고 정리했습니다.