AI 에이전트 성능을 2배 높이는 agents.md 전략: 기술보다 맥락이 중요한 이유

AI 에이전트가 코드를 작성하고 인프라를 구축하는 시대다. 하지만 현장의 개발자들은 여전히 불안함을 느낀다. 방금 전까지 완벽하던 에이전트가 갑자기 엉뚱한 대답을 내놓거나, 명확히 지시한 도구를 무시하는 상황이 빈번하기 때문이다.

Vercel AI SDK 팀의 최근 실험 결과는 충격적이다. AI 에이전트에게 도구 선택권, 즉 스킬(Skills)을 맡겼을 때 발생하는 실패율은 무려 56%에 달한다. 이는 모델의 지능 문제가 아니다. 우리가 AI에게 정보를 제공하는 방식이 근본적으로 잘못되었다는 증거다. 에이전트의 성공률을 100%로 끌어올리는 비결은 도구의 추가가 아니라 agents.md 기반의 지속성 컨텍스트 전략에 있다.

---

AI 스킬 방식이 현장에서 실패하는 이유

많은 개발자가 에이전트에게 다양한 도구 호출 기능을 부여하고, 필요할 때마다 AI가 이를 스스로 꺼내 쓰길 기대한다. 하지만 이 방식에는 결정 노이즈라는 치명적인 약점이 존재한다.

대화가 길어질수록 발생하는 컨텍스트 부패

AI 모델의 컨텍스트 윈도우는 인간의 단기 기억과 같다. 대화가 5회 이상 오가면 초기 시스템 프롬프트에 적힌 지침은 우선순위에서 밀려난다. 이를 컨텍스트 부패라고 부른다. 에이전트는 매 순간 내가 지금 도구를 써야 하나, 아니면 그냥 아는 대로 대답해야 하나 고민한다. 이 결정 지점 자체가 실패를 유도하는 단일 장애점이 된다.

---

agents.md: 100% 성공률을 위한 패시브 컨텍스트

실패율 56%를 0%로 만드는 해법은 단순하다. 에이전트에게 선택권을 주는 대신, 프로젝트의 핵심 규칙과 정보를 시스템 프롬프트에 고정하는 것이다. 그 중심에 agents.md 파일이 있다.

왜 agents.md가 더 강력한가

Vercel의 벤치마크에 따르면 동일한 정보를 도구로 제공했을 때 성공률은 79%였으나, agents.md에 인덱스 형태로 직접 포함시켰을 때는 100%의 통과율을 기록했다.

• 결정 지점의 제거: 에이전트가 문서를 찾아볼지 고민할 필요 없이 눈앞의 정보를 즉각 참조한다.
• 검색 중심 추론: 모델의 내부 기억에 의존하는 대신 제공된 최신 문서 경로를 따라가도록 강제한다.
• 최신성 유지: 학습 데이터에 없는 최신 API 규칙도 오차 없이 준수하게 만든다.

분석 지표	도구 호출 방식 (Skills)	지속성 컨텍스트 (agents.md)
의사결정	에이전트가 매번 로드 여부 결정	정보가 항상 시스템에 상주
신뢰성	약 53% ~ 79% (불안정)	최대 100% 달성 가능
추론 부하	결정 노이즈로 인한 높은 부하	의사결정 생략으로 낮은 부하
특징	온디맨드 방식	패시브 방식

---

효과적인 agents.md 설계를 위한 3단계 로드맵

성능을 극대화하려면 agents.md를 단순한 텍스트 파일이 아닌 기계를 위한 리드미(README)로 설계해야 한다.

1. 제약 사항을 명확히 명시하라

추상적인 원칙보다 구체적인 금지 사항이 에이전트의 결과물 품질을 즉각적으로 높인다. MUI v3를 사용하고 상태 관리는 반드시 Jotai를 쓰라는 식의 구체적인 명령이 필요하다. 절대 alert()를 사용하지 말고 특정 라이브러리의 컴포넌트를 활용하라는 지시가 에이전트의 이탈을 막는다.

2. 구조의 시각화와 실행 명령 제공

에이전트가 전체 리포지토리를 훑으며 토큰을 낭비하게 두어서는 안 된다. 핵심 파일 위치를 미니 인덱스로 제공해야 한다. 빌드 시 pnpm을 사용해야 하는지, 라우트 파일과 스키마 파일이 어디에 위치하는지 명확한 지도를 그려주어야 한다.

3. 8KB의 법칙: 문서 인덱스 압축

파일이 비대해지면 성능은 오히려 떨어진다. Vercel은 40KB의 문서를 8KB로 압축하여 인덱싱하는 방식을 권장한다. 에이전트에게 지식 자체를 떠먹여 주기보다 지식에 접근할 수 있는 경로를 최적화하여 전달하는 것이 핵심이다.

---

프롬프트 부채를 방지하는 협업 인터페이스

코드에 기술적 부채가 쌓이듯 AI 활용에도 프롬프트 부채가 쌓인다. 팀원마다 에이전트에게 주는 지침이 다르면 결과물의 일관성은 무너진다. agents.md를 프로젝트 루트에 두고 Git으로 관리하면 버전 제어가 통합되고 어떤 모델을 사용하더라도 팀의 표준 가이드를 동일하게 적용할 수 있다.

AI 에이전트의 시대에 승패는 모델의 지능보다 컨텍스트 엔지니어링에서 갈린다. 에이전트가 더 똑똑해지기를 기다리기보다 에이전트가 실수할 수 없는 환경을 구축하는 것이 생산성을 높이는 가장 확실한 길이다. 지금 당장 프로젝트 루트에 agents.md를 생성하고 팀의 규칙을 명문화하는 것부터 시작하라.