더 많은 정보가 항상 정답은 아니다

AGENTS.md의 역설

최근 GitHub 등에서 AI 코딩 에이전트(Claude Code, Cursor 등)가 프로젝트를 더 잘 이해하도록 돕는 AGENTS.md나 .cursorrules 같은 컨텍스트 파일을 만드는 것이 유행입니다. 정말 도움이 될지를 연구한 Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?​​를 소개합니다. 이 논문은 ’정말 도움이 될까?‘라는 질문에 꼭 그렇지는 않다는 냉정한 답변을 내놓았습니다.

LLM이 만든 컨텍스트는 '독‘

많은 개발자가 AI를 시켜서 프로젝트 요약 파일(AGENTS.md)을 생성합니다. 그런데 연구 결과에 따르면, LLM이 생성한 컨텍스트 파일을 제공했을 때 작업 성공률은 0.5~2% 감소한 반면, 추론 비용은 20%나 증가했습니다. AI가 자기가 쓴 글에 현혹되어 불필요한 탐색을 반복하느라 토큰만 더 많이 쓴 셈이죠.

개발자가 직접 써도 '비용 대비 효율'이 숙제

사람이 직접 공들여 작성한 컨텍스트 파일은 성공률을 약 4% 정도 높여주었습니다. 하지만 이 역시 공짜는 아닙니다. 여전히 더 많은 추론 단계와 비용이 발생했습니다. 프로젝트의 전체적인 구조를 설명하는 글들이 이미 코드나 기존 문서에 있는 내용을 중복해서 보여주는 경우가 많기 때문입니다.

말 잘 듣는 에이전트의 함정

재미있는 점은, 컨텍스트 파일이 있으면 에이전트들이 지시사항을 더 열심히 따르려고 노력한다는 것입니다. 도구 사용 빈도가 1.6~2.5배 늘어났지만, 정작 결과물은 더 나빠지는 명령 이행의 역설이 관찰되었습니다. 맥락 정보가 너무 많으면 에이전트가 "무엇을 해야 할지"보다 "어떻게 설명되어 있는지"에 매몰될 수 있다는 뜻입니다.

우리를 위한 실전 가이드

이 연구가 주는 교훈은 명확합니다. AI 에이전트와 협업할 때 정보의 양보다 정보의 밀도에 집중해야 합니다.

• LLM 생성 요약은 지양: AI가 만든 프로젝트 요약을 다시 AI에게 먹이는 것은 큰 도움이 되지 않습니다.

• 미니멀리즘 유지: 사람이 직접 작성하더라도 전체적인 개요보다는, 해당 AI가 수행해야 할 특정한 작업별 요구사항에 집중해서 최소한으로 작성하는 것이 좋습니다.

• 중복 제거: 이미 README.md나 코드 주석에 있는 내용을 다시 복제해서 넣지 마세요. AI의 컨텍스트 윈도우만 낭비하게 됩니다.

마무리: 사람도 AI도 명확하고 간결한 지시를 좋아한다

이 논문을 액면 그대로 믿어야 할지는 잘 모르겠습니다만, 맥락은 다다익선이라는 믿음을 깨뜨릴 수도 있다는 흥미로운 연구였습니다. AI 코딩 에이전트의 성능을 높이고 싶다면, 가이드 파일을 두껍게 만들기보다 군더더기 없는 깔끔한 코드 구조와 명확한 작업 지시가 훨씬 더 경제적이고 강력한 방법이 될 것 같습니다.

최신 에이전트를 활용해 복잡한 시스템을 설계하시는 분들이라면, 이번 기회에 프로젝트 내 가이드 파일들을 '다이어트' 해보시는 건 어떨까요? 내 숨은 노하우를 AI에게 나눠줘 보는 것도 좋겠네요.