AI 코딩 에이전트, /init 한 번으로 끝? AGENTS.md에 대한 우리의 오해와 진짜 사용법
요즘 개발 커뮤니티에서 AI 코딩 에이전트 이야기가 끊이지 않잖아요. 많은 개발자분들이 코드 작성부터 리팩토링, 디버깅까지 다양한 작업을 에이전트에게 맡기면서 생산성 혁명을 기대하고 있어요. 저 역시 여러 에이전트를 시험해보면서 이 기술의 잠재력에 감탄하고 있고요.
그런데 한 가지 흥미로운 점이 있습니다. 우리가 AI 에이전트를 프로젝트에 처음 도입할 때, 마치 의식처럼 거치는 과정이 하나 있거든요. 바로 /init 명령어를 실행해서 AGENTS.md 파일을 자동 생성하는 거죠. 이 파일이 우리 코드베이스의 구조, 기술 스택, 테스트 컨벤션 같은 걸 정리해서 에이전트에게 컨텍스트를 제공해줄 거라고 믿으면서요. 저도 처음엔 당연히 이렇게 해야 하는 줄 알았습니다. ‘책임감 있는 개발자라면 에이전트를 이렇게 설정해줘야지!’ 하면서요.
하지만 최근에 공개된 몇몇 연구 결과들을 보면서, 우리가 그동안 당연하게 여겼던 이 방식이 사실은 에이전트를 더 느리고, 더 비싸고, 심지어 정확도까지 떨어뜨릴 수 있다는 충격적인 사실을 알게 됐습니다. 이건 단순히 “뉴스거리가 나왔네” 하고 넘길 이야기가 아니더라고요. 실제로 우리 작업 방식에 직접적인 영향을 줄 수 있는 중요한 변화라고 생각합니다.
우리가 에이전트를 바보로 만들고 있었던 건 아닐까?
핵심은 이겁니다. 많은 개발자들이 AGENTS.md를 마치 ‘영구적인 설정 파일’처럼 여기지만, 사실은 ‘아직 고치지 못한 코드 스멜(Code Smell) 목록’처럼 다뤄야 한다는 거예요. 좀 추상적이죠? 쉽게 말해, 에이전트가 스스로 알아낼 수 있는 정보를 굳이 AGENTS.md에 중복해서 넣어줄 필요가 없다는 겁니다. 오히려 그게 독이 될 수 있어요.
한 연구에서는 자동 생성된 AGENTS.md 파일이 에이전트의 성능을 저하시키고 비용을 20% 이상 증가시킨다고 지적했습니다. 왜냐고요? 에이전트가 이미 코드베이스를 스캔해서 파악할 수 있는 내용을 또다시 AGENTS.md에서 읽느라 시간과 토큰을 낭비하기 때문입니다. 마치 이미 다 아는 길을 안내 책자로 다시 설명해주는 것과 같아요. 가이드가 스스로 길을 찾도록 내버려 두는 게 훨씬 효율적이죠.
제가 실제로 몇몇 프로젝트에서 자동 생성된 AGENTS.md 파일을 사용해봤을 때도 비슷한 느낌을 받은 적이 있어요. 분명 컨텍스트를 제공해줬는데, 에이전트가 엉뚱한 방향으로 코드를 작성하거나, 질문에 대한 답변이 느려지는 경험을 했거든요. 그때는 ‘에이전트가 아직 똑똑하지 않아서 그런가?‘라고 생각했는데, 어쩌면 제가 너무 많은 ‘소음’을 준 게 아닐까 싶더라고요.
AGENTS.md, 버려야 할까? 아니요, 제대로 써야죠.
그럼 AGENTS.md는 아예 쓰지 말아야 할까요? 그건 또 아닙니다. 또 다른 연구에서는 흥미로운 결과를 보여줬어요. 개발자가 직접 작성한 AGENTS.md 파일이 특정 조건에서는 에이전트의 작업 성공률을 약 4% 높이고, 실행 시간을 28% 단축시키며, 토큰 소모량도 16% 이상 줄여준다는 겁니다.
여기서 중요한 건 어떤 내용을 담느냐 하는 문제입니다. 개발자가 직접 작성한 파일이라도, 에이전트가 이미 파악할 수 있는 일반적인 정보(디렉터리 구조, 기술 스택 등)를 담고 있다면 역시나 독이 됩니다. 이 연구에서는 개발자 작성 파일조차 비용을 최대 19%까지 증가시킬 수 있다고 했거든요.
진정으로 도움이 되는 AGENTS.md는 에이전트가 스스로 발견하기 어려운 정보를 담고 있을 때입니다. 예를 들어, 특정 툴링의 고질적인 문제점, 프로젝트에만 존재하는 비표준적인 컨벤션, 과거에 발생했던 ‘지뢰밭’ 같은 케이스들이죠. 이런 정보들은 에이전트가 실수하지 않도록 미리 방지하는 역할을 합니다. 우리 코드에는 보이지 않는 수많은 ‘암묵적인 지식’들이 있잖아요? 그런 것들을 AGENTS.md에 담아야 하는 겁니다. 모든 다른 줄은 그저 소음일 뿐이고요.
컨텍스트도 ‘스코프’가 중요하다
또 한 가지 짚어볼 점은, AGENTS.md 파일을 프로젝트의 루트 디렉토리에 하나만 두는 것이 비효율적이라는 겁니다. 복잡한 코드베이스에서는 전체 프로젝트의 모든 정보를 하나의 파일에 담는 것이 거의 불가능하잖아요. 그리고 에이전트가 특정 모듈이나 디렉토리에서 작업할 때, 프로젝트 전체 컨텍스트보다는 그 부분에 특화된 컨텍스트를 받는 것이 훨씬 효과적일 겁니다.
그래서 연구자들은 AGENTS.md 파일도 계층적으로 관리되어야 한다고 제안합니다. 관련 디렉토리나 모듈 레벨에 AGENTS.md 파일을 배치해서, 에이전트가 작업하는 코드에 정확히 맞는 범위의 컨텍스트만 받도록 하는 거죠. 이 파일들은 자동으로 유지 관리되어야 하고요. 이렇게 하면 에이전트가 불필요한 정보를 처리하느라 낭비하는 것을 막고, 훨씬 더 정확하고 효율적인 작업을 수행할 수 있을 겁니다.
이 아이디어는 기존에 우리가 마이크로서비스 아키텍처나 모듈러 프로그래밍에서 ‘응집도’와 ‘결합도’를 중요하게 생각했던 것과 일맥상통한다고 생각해요. 컨텍스트도 특정 작업에 대한 응집도를 높이고, 불필요한 결합도를 줄여야 하는 거죠.
그래서 우리가 뭘 바꿔야 할까요?
개인적으로 이 연구 결과들을 보면서, AI 에이전트를 활용하는 방식에 대한 우리의 ‘정신 모델’ 자체를 바꿔야겠다는 생각을 했습니다.
- AGENTS.md는 동적인 ‘코드 스멜’ 리스트: 한 번 생성하고 끝내는 설정 파일이 아니라, 코드베이스에서 에이전트가 실수할 수 있는 지점이나 특별히 주의해야 할 부분을 그때그때 업데이트하는 리스트로 봐야 합니다. 마치 TODO 리스트처럼요.
- ‘숨겨진 지식’에 집중: 에이전트가 스스로 발견할 수 있는 뻔한 정보보다는, 우리 개발팀만이 아는 ‘암묵적인 규칙’, ‘특별한 히스토리’, ‘반복되는 함정’ 같은 것들을 기록하는 데 집중해야 합니다. “이 함수는 절대 직접 호출하면 안 되고, 반드시 유틸리티 함수의 래퍼를 통해야 한다” 같은 것들이죠.
- 컨텍스트는 ‘스코프’ 있게: 가능하면
AGENTS.md를 프로젝트 루트에만 두지 말고, 각 서브모듈이나 도메인별 디렉토리에 분산해서 배치하고, 에이전트가 작업하는 코드에 가장 적절한 컨텍스트만 제공하도록 해야 합니다. 궁극적으로는 이런 파일들이 자동으로 유지 관리되는 시스템이 필요할 거고요.
마무리하며: 더 똑똑하게 에이전트와 일하는 법
지금까지 AI 코딩 에이전트를 위한 AGENTS.md 파일에 대한 흥미로운 연구 결과들과 제 생각을 공유해봤습니다. 우리는 AI 기술이 발전하면서 단순히 ‘더 편리해지는 것’을 넘어, ‘더 똑똑하게 일하는 방식’을 고민해야 합니다. 무심코 진행했던 /init 작업 한 번이 사실은 에이전트의 효율성을 떨어뜨리고, 비용을 낭비하게 만들 수도 있다는 점은 시사하는 바가 크다고 생각해요.
이제는 에이전트에게 “이 코드 베이스는 이렇게 생겼어”라고 설명하기보다는, “여기 이런 함정이 있으니 조심해!”라고 핵심을 짚어주는 방식으로 전환해야 할 때가 아닐까요? 우리 코드의 ‘숨겨진 이야기’를 에이전트에게 전달하는 것이야말로, AI의 잠재력을 최대한으로 끌어내고 더 나은 개발 경험을 만드는 길이 될 겁니다.
여러분은 AI 에이전트와 어떻게 협업하고 계신가요? 이 글을 읽고 어떤 생각이 드셨는지 댓글로 알려주시면 좋겠습니다. 다음에도 흥미로운 AI 개발 이야기로 찾아오겠습니다!