에이전트는 추측한다, 문서가 없으면
Claude Code나 Cursor에 작업을 던져본 적 있다면 이 경험을 알 것이다. 에이전트가 엉뚱한 디렉토리에 파일을 만들거나, 프로젝트에서 쓰지 않는 테스트 러너를 실행하거나, 마이그레이션 파일을 손으로 수정하거나. 모델이 나빠서가 아니다. 에이전트는 컨텍스트가 없으면 합리적으로 추측할 뿐이다. 그 추측이 팀 표준과 맞지 않으면 결과는 리버트 커밋이다.
AGENTS.md는 그 추측을 없애는 파일이다. 레포 루트에 놓이는 단일 마크다운 파일로, AI 코딩 에이전트에게 이 프로젝트의 빌드 방법, 테스트 실행법, 코드 컨벤션, 건드리면 안 되는 지뢰를 명시한다. dev.to의 실전 튜토리얼("AGENTS.md, Hands-On: Build One Step by Step")은 Python FastAPI 프로젝트를 예시로 파일을 단계별로 완성하면서, 에이전트가 실제로 이 파일을 어떻게 활용하는지를 보여준다. 그 과정에서 드러나는 건 단순한 프롬프트 엔지니어링 팁이 아니다. 팀 표준을 에이전트가 읽을 수 있는 형태로 버전관리하는 방식이다.
7개 섹션, 30초 브리핑
파일의 구조는 간단하다. 각 섹션이 에이전트의 행동 하나를 제어한다.
- Orientation: 한 줄 요약. 언어, 프레임워크, 스토리지. 에이전트가 코드 한 줄 읽기 전에 컨텍스트를 세팅한다.
- Setup / Run: 실제로 동작하는 복붙 가능한 명령어. 플레이스홀더 금지.
- Test:
pytest,ruff check .,mypy app. 에이전트의 자기 검증 루프다. 이 섹션이 없으면 에이전트는 테스트를 돌릴 줄 몰라서 브로큰 브랜치를 넘긴다. - Structure: 디렉토리 맵. 파일 위치를 알려주면서 컨벤션과 가드레일을 슬쩍 끼워넣는 지점이다.
"parameterized queries only, never string-built SQL"처럼. - Conventions: 구체적인 패턴.
"Write good code"는 노이즈다."Validate all input with Pydantic at the route boundary"는 실행 가능한 규칙이다. - Commits & PRs: 커밋 포맷, PR 단위 정책. 에이전트가 PR을 여는 프로젝트라면 필수다.
- Don't: 지뢰 목록. 마이그레이션 파일 직접 수정 금지, main 직접 커밋 금지, 시드 스크립트 프로덕션 실행 금지.
이 파일을 에이전트에게 주고 DELETE /links/{code} 엔드포인트 추가를 요청하면, 에이전트는 파일을 먼저 읽고, 컨벤션에 맞게 핸들러를 작성하고, tests/에 pytest 테스트를 미러링하고, pytest + ruff + mypy를 돌려서 통과 확인 후 브랜치를 열고 PR을 낸다. migrations/는 건드리지 않는다. 파일이 없으면? 에이전트는 당신에게 묻거나, 추측하거나, 생성 파일을 수정한다. AGENTS.md는 에이전트가 당신을 방해하는 횟수를 줄이는 구조다.
팀 표준화 관점에서 진짜 가치
개인 프로젝트에서 AGENTS.md는 편의 기능이다. 팀 레포에서는 다르다. 신규 팀원이 온보딩할 때 README.md를 읽는 것처럼, AI 에이전트는 AGENTS.md를 읽는다. 문제는 README는 사람이 해석하지만 AGENTS.md는 에이전트가 문자 그대로 실행한다는 것이다. 모호한 규칙은 사람에게 질문을 만들지만, 에이전트에게는 잘못된 코드를 만든다.
테크 리드 입장에서 이 파일의 가치는 세 가지다.
첫째, 팀 컨벤션의 단일 진실 소스다. PR 리뷰에서 매번 반복하던 "여기는 HTTPException 써야 해", "Pydantic 모델로 검증해"를 파일 한 곳에 모은다. 에이전트도, 신규 팀원도, 같은 소스를 본다.
둘째, 에이전트 행동의 감사 가능한 기록이다. 에이전트가 왜 이 구조로 코드를 짰는지 추적하고 싶다면 AGENTS.md 커밋 히스토리를 보면 된다.
셋째, 스케일링 레버다. 에이전트를 여러 개 붙이든, 팀원이 늘든, 레포가 커지든—AGENTS.md 하나가 모든 에이전트의 행동 기준선이 된다.
파일을 죽이는 한 가지 습관
튜토리얼에서 가장 중요한 경고는 마지막에 나온다. 낡은 AGENTS.md는 없는 것보다 나쁘다. 에이전트는 파일을 신뢰한다. 테스트 커맨드가 바뀌었는데 파일이 업데이트 안 됐으면, 에이전트는 틀린 커맨드를 자신 있게 실행한다. 디렉토리 구조가 바뀌었는데 맵이 그대로면, 에이전트는 존재하지 않는 경로에 파일을 만든다.
규칙은 하나다. 코드를 바꿀 때 AGENTS.md를 같은 커밋에 업데이트한다. 같은 맥락에서 테크 리드가 PR 리뷰 체크리스트에 "AGENTS.md 업데이트 필요?" 항목을 넣는 게 현실적인 시작점이다. 이 파일을 코드로 취급한다는 건 버전관리, 리뷰, 업데이트 책임을 코드와 동일하게 적용한다는 의미다.
지금 팀에 적용한다면
이미 Claude Code나 Cursor를 쓰는 팀이라면 AGENTS.md 도입 비용은 낮다. 파일을 처음 만드는 데 30분이면 충분하다. 기존 README.md의 Setup 섹션, 린트/테스트 커맨드, 코드 리뷰에서 반복 지적하던 컨벤션 세 가지만 옮겨도 에이전트 행동이 달라진다.
단, 팀 규모가 커질수록 컨벤션의 추상도를 관리해야 한다. 너무 세세하면 파일 유지보수 부담이 커지고, 너무 추상적이면 에이전트가 실행할 수 없다. 실용적인 기준은 "PR 리뷰에서 같은 코멘트를 두 번 이상 달았다면 AGENTS.md에 넣어라"다. 반복되는 리뷰 코멘트는 곧 에이전트가 반복하는 실수다.
전망: 에이전트 온보딩 문서의 표준화
AGENTS.md는 현재 OpenAI Codex, Claude Code, Cursor가 지원하는 사실상의 표준이 돼가고 있다. Google ADK 2.0 안정화, MCP 프로토콜 확산과 맞물려, 에이전트 레이어의 인터페이스 표준화 속도는 빨라지고 있다. 이 흐름에서 팀 단위 컨텍스트를 에이전트에게 전달하는 방식도 결국 어떤 형태로든 표준화될 것이다.
지금 AGENTS.md를 팀 레포에 정착시키는 건 단순히 에이전트 생산성 향상이 아니다. 팀의 암묵지를 에이전트가 읽을 수 있는 명시적 지식으로 변환하는 작업이다. 그 작업을 지금 시작하는 팀과 하지 않는 팀의 격차는, 에이전트 활용 빈도가 높아질수록 더 벌어진다.