우리는 코드 작성 에이전트에 프레임워크별 지식을 가르치는 데 최적의 해결책이 될 것이라고 예상했습니다. Next.js 16 API 에 초점을 맞춘 평가를 구축한 후, 예상치 못한 사실을 발견했습니다. 'skills'는 8KB 크기의 압축된 문서 인덱스를 직접 포함시켰음에도 불구하고 100% 의 통과율을 달성한 반면, 에이전트가 이를 사용하도록 명시적인 지시를 내렸더라도 'skills'의 최대 통과율은 79% 에 그쳤습니다. 이러한 지시 없이 사용할 경우, 'skills'는 문서를 전혀 제공하지 않은 상태와 성능 차이가 없었습니다.

AGENTS.md

우리가 시도한 것, 배운 점, 그리고 독자님의 Next.js 프로젝트에 이를 설정하는 방법을 소개합니다.

AI 코드 작성 에이전트는 최신 모델 학습 데이터에 포함되지 않는 , , 등 API 를 사용하는 경우 훈련 데이터가 빠르게陳舊해집니다. 에이전트가 이러한 API 를 모르면 잘못된 코드를 생성하거나 이전 패턴으로 회귀합니다. 반면, Next.js 16 의 'use cache' 및 connection(), forbidden()와 같은 새로운 기능이 도입된 반면, 사용자가 구버전을 실행하고 모델이 프로젝트에 아직 존재하지 않는 최신 API 를 제안하는 경우도 발생할 수 있습니다.

우리는 에이전트에게 버전 매칭된 문서에 대한 접근 권한을 부여함으로써 이 문제를 해결하고자 했습니다. 결과에 들어가기 전에 우리가 테스트한 두 가지 접근 방식에 대해 간략히 설명하겠습니다.

우리는 Next.js 문서 'skills'와 AGENTS.md 인덱스를 구축한 후, 이를 평가スイ트를 통해 실행하여 어떤 것이 더 나은 성능을 보이는지 확인했습니다.

AGENTS.md

'Skills'는 올바른 추상화처럼 보였습니다. 프레임워크 문서를 skill 로 패키징하고, 에이전트가 Next.js 작업 수행 시 이를 호출하면 올바른 코드가 생성됩니다. 관심사의 명확한 분리, 최소 컨텍스트 오버헤드, 그리고 에이전트가 필요한 것만 로드하는 장점이 있습니다. 또한 재사용 가능한 skills 의 라이브러리가 성장하고 있으며, 에서 확인할 수 있습니다.

skills.sh

우리는 에이전트가 Next.js 작업을 만나면 skill 을 호출하고 버전 매칭된 문서를 읽은 후 올바른 코드를 생성할 것이라고 예상했습니다. 그런 다음 평가를 실행했습니다.

평가 사례의 56% 에서는 skill 이 한 번도 호출되지 않았습니다. 에이전트는 문서에 접근 권한이 있었지만 이를 사용하지 않았습니다. skill 을 추가해도 베이스라인 대비 개선 효과가 전혀 없었습니다: 제로 개선 효과입니다. skill 은 존재했고, 에이전트가 사용할 수 있었으나, 에이전트는 이를 선택하지 않았습니다.

세부적인 빌드/린트/테스트 분석 결과, 일부 지표에서 skill 이 베이스라인보다 오히려 더 낮은 성능을 보였습니다(테스트 항목 기준 58% 대 63%) 이는 환경에 사용되지 않는 skill 이 소음이나 방해 요인을 유발할 수 있음을 시사합니다.

이러한 현상은 우리 설정에만 국한된 것이 아닙니다. 에이전트가 이용 가능한 도구를 신뢰성 있게 사용하지 못하는 것은 현재 모델들의 한계입니다.

우리는 에이전트가 skill 을 사용하도록 명시적인 지시를 추가하여 이를 시도했습니다.

AGENTS.md

이는 호출률을 95% 이상으로 높이고 통과율을 79% 로 끌어올렸습니다. 상당한 개선 효과였습니다. 그러나 지시문의 문장 구성이 에이전트 행동에 미치는 영향에 대해 예상치 못한 사실을 발견했습니다.

동일한 skill, 동일한 문서임에도 불구하고 미세한 문장 구성 변화에 따라 결과가 극명하게 달랐습니다.

하나의 평가 (지시 테스트) 에서 '먼저 호출' 접근 방식은 올바른 코드를 작성했지만 필요한 변경 사항을 완전히 놓쳤습니다. 반면 '먼저 탐색' 접근 방식은 두 가지 모두를 성공했습니다.

'use cache', page.tsx, next.config.ts와 같은 요소들

이러한 취약성에 대해 우리는 우려를 표명합니다. 작은 문장 구성의 수정만으로도 큰 차이가 발생한다면...