AI 코딩 에이전트는 학습 데이터에 의존하는데, 이 데이터는 시간이 지나면 낡아집니다. Next.js 16에 도입된 'use cache', connection(), forbidden() 같은 API는 현재 모델의 학습 데이터에 포함되어 있지 않습니다. 에이전트가 이런 API를 모르면 잘못된 코드를 생성하거나 이전 버전의 패턴으로 되돌아갑니다.

반대 상황도 마찬가지입니다. 구버전 Next.js를 쓰고 있는데 모델이 아직 프로젝트에 존재하지 않는 최신 API를 제안하는 경우죠. 이 문제를 해결하기 위해, 에이전트가 프로젝트의 Next.js 버전에 맞는 문서에 접근할 수 있도록 만들고 싶었습니다.

에이전트에게 프레임워크 지식을 전달하는 두 가지 방법

결과를 살펴보기 전에, 테스트한 두 가지 접근법을 간단히 설명하겠습니다.

• 스킬은 코딩 에이전트가 활용할 수 있는 도메인 지식을 패키징하는 오픈 표준입니다. 스킬은 프롬프트, 도구, 문서를 하나로 묶어 에이전트가 필요할 때 호출할 수 있게 해줍니다. 에이전트가 프레임워크 관련 도움이 필요한 상황을 인식하면 스킬을 호출하고, 해당 문서에 접근하는 구조입니다.

• AGENTS.md는 프로젝트 루트에 위치하는 마크다운 파일로, 코딩 에이전트에게 지속적인 컨텍스트를 제공합니다. AGENTS.md에 작성한 내용은 에이전트가 별도로 로드를 결정할 필요 없이 매 턴마다 자동으로 참조됩니다. Claude Code에서는 CLAUDE.md가 같은 역할을 합니다.

Next.js 문서 스킬과 AGENTS.md 문서 인덱스를 각각 만든 뒤, 평가 스위트를 돌려 어느 쪽이 더 나은 성능을 보이는지 비교했습니다.

처음에는 스킬에 기대를 걸었습니다

스킬은 적절한 추상화처럼 보였습니다. 프레임워크 문서를 스킬로 패키징하고, 에이전트가 Next.js 작업 시 이를 호출하면 올바른 코드가 나온다—관심사 분리도 깔끔하고, 컨텍스트 부담도 적고, 필요한 것만 로드하니까요. 재사용 가능한 스킬을 모아둔 디렉토리도 skills.sh에서 점점 늘어나고 있었습니다.

에이전트가 Next.js 작업을 만나면 스킬을 호출하고, 버전에 맞는 문서를 읽어 올바른 코드를 생성할 거라 예상했습니다.

그런 다음 평가를 돌렸습니다.

스킬이 안정적으로 호출되지 않았습니다

평가 케이스의 56%에서 스킬이 한 번도 호출되지 않았습니다. 에이전트가 문서에 접근할 수 있었는데도 사용하지 않은 겁니다. 스킬을 추가해도 기준선 대비 개선이 전혀 없었습니다:

개선 효과가 전무했습니다. 스킬이 존재했고, 에이전트가 사용할 수 있었지만, 스스로 사용하지 않기로 선택한 겁니다. Build/Lint/Test 세부 분석에서는 오히려 스킬이 기준선보다 낮은 지표를 보이기도 했습니다(테스트 58% vs 63%). 사용되지 않는 스킬이 환경에 존재하는 것만으로도 노이즈나 방해 요소가 될 수 있음을 시사합니다.

이는 우리 환경만의 문제가 아닙니다. 에이전트가 사용 가능한 도구를 안정적으로 활용하지 못하는 것은 현재 모델의 알려진 한계입니다.

명시적 지시로 개선되었지만, 문구에 따라 결과가 달라졌습니다

AGENTS.md에 에이전트가 스킬을 사용하도록 명시적으로 지시하는 문구를 추가해 보았습니다.

호출률이 95% 이상으로 올랐고, 통과율도 79%까지 상승했습니다.

상당한 개선이었습니다. 하지만 지시 문구의 표현 방식이 에이전트 동작에 미치는 영향에서 예상치 못한 점을 발견했습니다.

문구만 달라져도 결과가 크게 달라졌습니다:

같은 스킬, 같은 문서인데 미묘한 문구 차이만으로 결과가 달라졌습니다.

한 평가 케이스('use cache' 디렉티브 테스트)에서 "먼저 호출" 방식은 올바른 page.tsx를 작성했지만 필수인 next.config.ts 변경을 완전히 놓쳤습니다. "먼저 탐색" 방식은 둘 다 정확히 처리했습니다.

이런 취약성이 우려스러웠습니다. 사소한 문구 수정이 큰 동작 변화를 일으킨다면, 프로덕션 환경에서 쓰기에는 너무 불안정한 접근법입니다.

신뢰할 수 있는 평가 구축

결론을 내리기 전에, 먼저 신뢰할 수 있는 평가가 필요했습니다. 초기 테스트 스위트에는 모호한 프롬프트, 관찰 가능한 동작이 아닌 구현 세부사항을 검증하는 테스트, 이미 모델 학습 데이터에 있는 API에만 집중하는 문제가 있었습니다. 정작 중요한 것을 측정하고 있지 않았던 겁니다.

테스트 누수를 제거하고, 모순을 해소하고, 동작 기반 단언(assertion)으로 전환하여 평가 스위트를 강화했습니다. 가장 중요한 변경은 모델 학습 데이터에 없는 Next.js 16 API를 대상으로 하는 테스트를 추가한 것입니다.

집중 평가 스위트에 포함된 API:

• 동적 렌더링용 connection()

• 'use cache' 디렉티브

• cacheLife() 및 cacheTag()

• forbidden() 및 unauthorized()

• API 프록시용 proxy.ts

• 비동기 cookies() 및 headers()

• after(), updateTag(), refresh()

이하 모든 결과는 이 강화된 평가 스위트를 기준으로 합니다. 모든 구성은 동일한 테스트로 판정했으며, 모델 분산을 배제하기 위해 재시도를 포함했습니다.

적중한 직감

에이전트의 판단 자체를 없애면 어떨까요? 스킬 호출을 기대하는 대신, 문서 인덱스를 AGENTS.md에 직접 삽입하는 겁니다. 전체 문서가 아니라, 프로젝트의 Next.js 버전에 맞는 특정 문서 파일의 위치를 알려주는 인덱스만 넣는 방식입니다. 에이전트는 필요할 때 해당 파일을 읽으면 되므로, 최신 버전이든 구버전을 유지 중이든 버전에 정확한 정보를 얻을 수 있습니다.

삽입된 내용에 핵심 지시문도 함께 추가했습니다.

이 지시문은 에이전트가 잠재적으로 오래된 학습 데이터에 의존하지 말고 문서를 참조하도록 유도합니다.

예상을 뛰어넘은 결과

강화된 평가 스위트를 네 가지 구성 모두에 적용했습니다:

최종 통과율:

세부 분석에서도 AGENTS.md는 Build, Lint, Test 모두 만점을 기록했습니다.

예상과 달랐습니다. 정적 마크다운 파일이라는 "단순한" 방식이, 스킬 트리거를 세밀하게 조정한 경우까지 포함해 더 정교한 스킬 기반 검색 방식을 압도한 겁니다.

패시브 컨텍스트가 능동적 검색을 이기는 이유

세 가지 요인으로 설명할 수 있다고 봅니다.

1. 판단이 필요 없습니다. AGENTS.md 방식에서는 에이전트가 "이걸 찾아봐야 하나?"라고 판단할 순간 자체가 없습니다. 정보가 이미 주어져 있으니까요.

2. 항상 사용 가능합니다. 스킬은 비동기적으로 로드되며 호출 시에만 활성화됩니다. AGENTS.md 내용은 매 턴의 시스템 프롬프트에 포함됩니다.

3. 순서 문제가 없습니다. 스킬은 "문서를 먼저 읽을까, 프로젝트를 먼저 탐색할까"라는 순서 결정을 유발합니다. 패시브 컨텍스트는 이 문제를 근본적으로 회피합니다.

컨텍스트 비대화 문제 해결

AGENTS.md에 문서를 삽입하면 컨텍스트 윈도우가 비대해질 수 있습니다. 이를 압축으로 해결했습니다.

초기 문서 삽입 크기는 약 40KB였습니다. 이를 8KB(80% 감소)로 압축하면서도 100% 통과율을 유지했습니다. 압축 포맷은 파이프 구분자 구조를 사용해 문서 인덱스를 최소한의 공간에 담습니다:

전체 인덱스는 Next.js 문서의 모든 섹션을 커버합니다:

에이전트는 전체 내용을 컨텍스트에 담지 않고도 문서 위치를 파악합니다. 구체적인 정보가 필요하면 .next-docs/ 디렉토리에서 해당 파일을 읽으면 됩니다.

직접 적용해 보세요

명령어 하나로 Next.js 프로젝트에 설정할 수 있습니다:

npx @next/codemod@canary agents-md

이 기능은 공식 @next/codemod 패키지에 포함되어 있습니다.

이 명령어는 세 가지 작업을 수행합니다:

1. 프로젝트의 Next.js 버전 감지

2. 해당 버전에 맞는 문서를 .next-docs/에 다운로드

3. 압축된 인덱스를 AGENTS.md에 삽입

AGENTS.md를 지원하는 에이전트(Cursor 등)를 사용 중이라면 같은 방식을 그대로 적용할 수 있습니다.

프레임워크 제작자에게 주는 시사점

스킬이 쓸모없다는 뜻은 아닙니다. AGENTS.md 방식은 에이전트가 Next.js 전반에 걸쳐 작업할 때 광범위하고 수평적인 개선 효과를 줍니다. 반면 스킬은 사용자가 명시적으로 실행하는 수직적이고 특정 작업에 특화된 워크플로—"Next.js 버전 업그레이드", "App Router로 마이그레이션", 프레임워크 모범 사례 적용 등—에 더 적합합니다. 두 접근법은 상호 보완적입니다.

다만 범용 프레임워크 지식의 경우, 현재로서는 패시브 컨텍스트가 온디맨드 검색보다 성능이 뛰어납니다. 프레임워크를 관리하면서 코딩 에이전트가 올바른 코드를 생성하길 원한다면, 사용자가 프로젝트에 추가할 수 있는 AGENTS.md 스니펫을 제공하는 것을 고려해 보세요.

실무 권장 사항:

• 스킬 개선을 기다리지 마세요. 모델의 도구 활용 능력이 향상되면 격차가 줄어들 수 있지만, 지금 당장의 결과가 중요합니다.

• 과감하게 압축하세요. 전체 문서를 컨텍스트에 넣을 필요 없습니다. 검색 가능한 파일을 가리키는 인덱스만으로 충분합니다.

• 평가로 검증하세요. 학습 데이터에 없는 API를 대상으로 평가를 구축하세요. 문서 접근이 가장 큰 차이를 만드는 영역입니다.

• 검색에 최적화된 문서를 설계하세요. 에이전트가 모든 내용을 한꺼번에 필요로 하지 않도록, 특정 파일을 찾아 읽을 수 있는 구조로 문서를 작성하세요.

목표는 에이전트의 추론 방식을 사전 학습 의존에서 검색 기반으로 전환하는 것입니다. AGENTS.md가 이를 실현하는 가장 안정적인 방법으로 밝혀졌습니다.

리서치 및 평가: Jude Gao. CLI: npx @next/codemod@canary agents-md