AI 코딩용 Claude.md, 정말 효과 있나… 최신 연구 “생각보다 미미” > 뉴스 보스톤코리아

(보스턴 = 보스턴코리아) 장명술 기자 = 소프트웨어 개발에 대형언어모델(LLM)을 활용할 때 가장 큰 과제 가운데 하나는 AI에게 얼마나 적절한 작업 맥락을 제공하느냐다. 이를 해결하기 위한 초기 방식은 정교한 프롬프트 작성이었다. 이후 2025년 초부터는 AGENTS.md 같은 리포지토리(저장소, Repositoy)용 문서가 등장해 업계의 주목을 받기 시작했다.

AGENTS.md는 쉽게 말해 대형언어모델 AI가 코드 저장소를 이해하도록 돕는 안내 문서다. 개발 환경, 테스트 방식, 풀 리퀘스트(Pull Request) 작성 규칙, 자주 쓰는 명령어 같은 내용을 AI가 읽기 쉬운 형식으로 정리해 둔 것이다. 사람으로 치면 새로 들어온 주니어 개발자에게 건네는 업무 매뉴얼과 비슷하다. 이 문서는 OpenAI가 설계한 개방형 형식으로 알려져 있으며, 현재는 여러 에이전트형 코딩 도구와 연동되는 사실상의 표준처럼 쓰이고 있다.

그동안 이런 문서는 AI가 더 나은 코드를 작성하도록 도와주는 유용한 수단으로 여겨졌다. 특히 사람이 일일이 개입하지 않고도 스스로 작업을 이어가는 에이전트형 코딩 도구가 확산되면서, AGENTS.md의 필요성은 더 커 보였다. 실제로 초기 연구들에서는 이런 저장소 수준의 컨텍스트 파일을 사용할 경우 성능이 최대 36%까지 개선됐다는 결과도 나왔다.

하지만 최근 분위기는 달라지고 있다. ETH 취리히의 최신 연구에 따르면, 2026년 기준으로 이런 문서가 가져오는 출력 품질 개선은 베이스라인 대비 최대 5% 수준에 그쳤다. 일부 경우에는 오히려 AI가 만든 컨텍스트 파일이 성능에 부정적인 영향을 주기도 했다. 사람이 직접 만든 문서도 기대만큼 큰 차이를 만들지 못한 것으로 나타났다.

이 결과가 중요한 이유는 분명하다. AGENTS.md 파일은 한 번 만드는 것으로 끝나지 않는다. 계속 수정하고 유지해야 하며, 조직의 워크플로우가 바뀔 때마다 업데이트해야 한다. 그런데 이렇게 많은 시간을 들여도 실제 코딩 성능 향상은 매우 제한적이라면, 투자 대비 효과를 다시 따져볼 수밖에 없다. 결국 이 문서는 AI 성능 향상 도구라기보다, 조직 내부의 업무 지식을 문서화한 편람 정도의 가치가 더 크다는 해석도 가능하다.

연구진은 또 다른 문제도 지적했다. 이런 컨텍스트 파일을 넣으면 에이전트가 해결책을 찾는 데 필요한 단계 수가 늘어나고, 추론 토큰 사용량도 최대 20%까지 증가할 수 있다는 것이다. API 비용이 드는 환경에서는 무시하기 어려운 부담이다. 성능 개선은 한 자릿수에 그치는데 비용은 더 늘어나는 셈이다.

그렇다고 이런 문서가 완전히 쓸모없다는 뜻은 아니다. 다만 긴 개요나 조직 설명보다는 꼭 필요한 명령어, 도구 사용법, 테스트 규칙처럼 실제 작업에 바로 필요한 최소한의 내용만 넣는 편이 더 낫다는 것이다. 최신 모델들은 코드베이스의 큰 구조나 개요는 스스로 어느 정도 파악할 수 있기 때문에, 장황한 설명은 오히려 방해가 될 수 있다.

대안으로는 더 정교한 프롬프팅과 검색 기반 접근이 제시된다. 예를 들어 “1단계 분석, 2단계 패치, 3단계 업데이트할 테스트 제시”처럼 작업 순서를 명확히 제한하는 방식이 더 효과적일 수 있다. 또한 한 파일에 모든 지침을 몰아넣기보다는, 필요할 때 필요한 문서나 도구를 불러오는 MCP 서버나 검색 가능한 문서 체계를 활용하는 편이 낫다는 분석도 나온다. 이렇게 하면 처음부터 불필요한 지침으로 컨텍스트 창을 채우지 않아도 된다.

결국 이번 연구가 말하는 핵심은 단순하다. AGENTS.md 같은 문서가 완전히 무용하다는 것이 아니라, 그것이 AI 코딩의 핵심 해법은 아니라는 점이다. AI 코딩이 빠르게 발전하는 지금, 과거의 모범 사례가 더 이상 최선이 아닐 수 있다. 앞으로는 크고 포괄적인 지침 문서보다, 더 짧고 정밀한 맥락 제공과 필요할 때 꺼내 쓰는 검색형 지식 구조가 실제 작업 효율을 더 높일 가능성이 크다.