Hacker News 2026.06.09 60

AGENTS.md, 진짜 효과 있나요? AI 코딩 에이전트에게 메모를 남기는 일

AI한테도 '인수인계 문서'가 필요할까

요즘 코드 짤 때 옆에 AI 에이전트 하나씩 끼고 일하는 분들 많죠. Claude Code, Cursor, 코덱스 같은 도구한테 '이 버그 좀 고쳐줘' 하면 알아서 파일 뒤지고 코드 고쳐주잖아요. 그런데 한 가지 불편한 게 있어요. 에이전트가 우리 프로젝트의 '사정'을 모른다는 거예요. 테스트는 어떤 명령어로 돌리는지, 빌드는 뭘로 하는지, 우리 팀은 들여쓰기를 탭으로 쓰는지 스페이스로 쓰는지 같은 거요.

그래서 등장한 게 바로 AGENTS.md라는 파일이에요. 이게 뭐냐면, 사람을 위한 설명서가 README.md라면, AI 에이전트를 위한 설명서가 AGENTS.md예요. 프로젝트 루트에 이 파일을 하나 만들어 두면, 에이전트가 작업을 시작하기 전에 먼저 읽어보고 '아, 이 프로젝트는 이렇게 돌아가는구나' 하고 맥락을 잡는 거죠. 이번에 머신러닝 쪽으로 유명한 세바스찬 라쉬카(rasbt)가 던진 질문이 딱 핵심을 찔러요. 'AGENTS.md 파일이 정말로 코딩 에이전트한테 도움이 되긴 하는 거야?'

그 안에 보통 뭘 적냐면

실제로 잘 쓰인 AGENTS.md를 열어보면 거창한 게 아니에요. '테스트는 pytest tests/로 돌려라', '커밋 전에 ruff로 린트 검사해라', '새 함수에는 타입 힌트를 꼭 붙여라', 'API 키 같은 비밀값은 절대 코드에 직접 쓰지 말고 환경변수에서 읽어라' 같은, 우리가 신입한테 입으로 알려줄 법한 내용들이거든요. 에이전트가 매번 똑같은 실수를 반복하면, 그 부분을 한 줄 적어두는 식으로 점점 다듬어 나가는 거예요.

핵심은 '에이전트가 추측하지 않게 만든다'는 거예요. 안내가 없으면 에이전트는 흔한 관습대로 행동해요. 예를 들어 패키지 매니저를 npm이라고 가정해버리는데, 우리 팀은 pnpm을 쓴다면 엉뚱한 명령을 실행하고 헤매겠죠. 이런 걸 미리 적어두면 시행착오가 확 줄어요.

그런데 왜 '효과 있나?'라는 질문이 나올까

라쉬카의 질문이 의미심장한 이유가 있어요. 첫째, 에이전트가 그 파일을 진짜로 따르는지가 불확실하다는 거예요. AGENTS.md에 '한 줄에 80자 넘기지 마' 라고 적어놔도, 모델이 그걸 깜빡하거나 무시하는 경우가 종종 있거든요. 사람도 사내 규칙 문서 다 안 읽잖아요. AI도 비슷해요.

둘째, 맥락 비용 문제예요. 이게 뭐냐면, 에이전트가 AGENTS.md를 읽으면 그 내용이 전부 모델의 한정된 '기억 공간(컨텍스트 윈도우)'을 차지해요. 파일이 수백 줄로 비대해지면 정작 코드를 읽고 생각할 공간이 줄어들어서 오히려 성능이 떨어질 수 있어요. 그래서 '길게 쓸수록 좋은 게 아니라, 핵심만 짧게'가 정답에 가까워요.

셋째, 표준이 파편화돼 있어요. 도구마다 CLAUDE.md, .cursorrules, .github/copilot-instructions.md처럼 제각각 이름을 쓰던 걸, AGENTS.md로 하나로 모으자는 움직임이 있어요. 통일된다면 같은 문서를 여러 도구가 공유할 수 있으니 큰 진전이죠. 다만 아직 모든 도구가 이걸 따르는 건 아니에요.

한국 개발자에게 주는 시사점

실무에서 바로 해볼 수 있어요. 지금 AI 에이전트를 쓰고 있다면, 거창하게 시작하지 말고 에이전트가 자주 틀리는 것 서너 개만 한 줄씩 적어보세요. 테스트 명령어, 코드 스타일, 자주 쓰는 내부 라이브러리 정도면 충분해요. 그리고 에이전트가 또 실수하면 그때그때 한 줄씩 추가하는 식으로, 살아있는 문서처럼 키워나가는 게 가장 효과적이에요.

재밌는 건, 이게 사실 우리 팀 온보딩 문서를 정리하는 일과 거의 똑같다는 거예요. AI가 헷갈려하는 부분은 사람 신입도 헷갈려하는 부분이거든요. AGENTS.md를 잘 써두면 사람한테도 도움이 되는 셈이죠.