요즘 Cursor나 Claude Code 같은 AI 코딩 에이전트 쓰시는 분들 참 많죠? 프로젝트 루트 디렉터리에 에이전트 전용 가이드 파일을 하나만 잘 두어도 에이전트가 프로젝트 스타일을 찰떡같이 이해하고 코딩해 주는 시대가 되었습니다. 특히 OpenAI가 처음 제안하고 이제는 리눅스 재단의 에이전틱 AI 재단(AAIF)에서 공식 오픈 표준으로 관리하는 AGENTS.md가 대표적입니다.

그런데 코딩 에이전트가 더 완벽하게 일하게 만들려고 이 파일에 온갖 규칙과 코딩 스타일 가이드라인을 구구절절 적어두는 분들이 많으신데요. 의외로 이게 독이 될 수 있습니다 ㅎㅎ

최근 ICLR 2026에 발표된 한 논문에 따르면, 프로젝트 컨텍스트 파일이 너무 무겁고 복잡해질수록 에이전트의 실제 작업 성공률은 오히려 떨어지고 추론 비용은 약 20%나 불어났다고 합니다. 규칙이 너무 빽빽하면 에이전트가 불필요한 파일 탐색이나 무의미한 테스트에 집착하면서 정작 중요한 해결책을 찾지 못하고 길을 잃기 때문인 것 같네요.

결국 핵심은 '이 프로젝트만의 고유한 규칙'과 '핵심 빌드/테스트 명령어'만 가볍게 남겨두는 스마트한 타협입니다. 안 그래도 똑똑한 요즘 모델들에게 뻔한 기술 스택 지식을 구구절절 가르쳐서 토큰을 낭비할 필요는 없으니까요 ㅎㅎ

그리고 꿀팁이 하나 더 있는데요. Cursor나 Windsurf는 AGENTS.md를 잘 지원하지만, Claude Code는 아직 CLAUDE.md를 우선해서 읽습니다. 이럴 땐 두 파일을 따로 관리하며 싱크 맞추느라 고생하지 마시고, 아래처럼 심볼릭 링크로 가볍게 연결해두는 방식을 추천해 드립니다!

# AGENTS.md와 CLAUDE.md 싱크 맞추기 (macOS/Linux)
ln -s AGENTS.md CLAUDE.md

가장 가볍고 명확한 컨텍스트가 가장 똑똑하고 가성비 좋은 AI 에이전트를 만든다는 점, 꼭 기억해 두시면 좋겠습니다 ㅎㅎ