AGENTS.md: AI 개발자를 위한 실전 활용 가이드

AGENTS.md란 무엇인가?

AGENTS.md는 스타트업에서 AI 개발이나 코드 자동화 도구(코딩 에이전트)를 활용할 때 필요한 추가 안내서입니다. 기존의 README.md가 사람에게 친절하게 프로젝트 전반을 설명했다면, AGENTS.md는 주로 에이전트가 코드를 다루고 테스트하거나 빌드할 때 헷갈리지 말라고 상세 지침만 따로 담아둡니다.

OpenAI 의 코덱스를 포함 다양한 에이전트 시스템에서 도입하고 있습니다.

README.md와의 차이점

README.md는 개발자, 디자이너 등 실제 사람이 빠르게 프로젝트를 이해하고 참여할 수 있게 만듭니다. 반면 AGENTS.md는 지루할 수 있는 빌드, 테스트, 관습 등 에이전트에게만 필요한 실무적인 지침을 별도로 모아두어 사람 기준 문서를 깔끔하게 유지할 수 있도록 도와줍니다.

AGENTS.md의 주요 장점

• 코딩 에이전트가 작업을 자동화할 때 어디서 정보를 찾을지 즉시 알 수 있습니다.

• 사람에게 필요 없는 상세 정보(예: 자동화 명령어, 테스트 방법 등)를 분리해 두어 메인 문서가 복잡해지지 않습니다.

• 오픈 포맷(Markdown)이라 별도의 도구나 시스템 없이 누구나 적용할 수 있습니다.

다양한 AI 코딩 도구와 호환됨

AGENTS.md 한 번 만들면 OpenAI Codex, Amp, Google Jules, Cursor 등 다양한 AI 코딩 툴에서 쓸 수 있습니다. 특정 에이전트에 종속되지 않는 점이 스타트업에 무척 유리하죠. 이로써 협업 생태계가 넓어집니다.

실전 예시: AGENTS.md에 담는 내용

보통 이런 항목들을 추가합니다:

• 프로젝트 개요

• 빌드 및 테스트 명령어

• 코드 스타일 규칙

• 소규모 보안 주의사항

• 커밋·PR 작성 규칙

• 데이터셋·배포 방법 등 신규 멤버에게 당부하고 싶은 것

코드 블록 예시: 개발 환경/테스트 관련 명령어

# 패키지로 이동하기
pnpm dlx turbo run where <project_name>

# 패키지 설치 및 확인
pnpm install --filter <project_name>
pnpm create vite@latest <project_name> -- --template react-ts

# 테스트 실행
pnpm turbo run test --filter <project_name>
pnpm test

대형 프로젝트(모노레포), 팀별 AGENTS.md 활용법

모듈별로 AGENTS.md를 만들 수 있습니다. 각 패키지(폴더)에 별도 파일을 두면, 에이전트는 그 파일 기준으로 안내를 받게 됩니다. 예를 들어, 오픈AI는 88개의 AGENTS.md 파일로 대규모 프로젝트 관리 중입니다.

도입 및 관리 방법

• 루트 폴더에 AGENTS.md를 추가하세요.

• 필요한 내용만 자유롭게 Markdown으로 작성하면 됩니다.

• 기존 AGENT.md가 있다면 다음 명령어로 쉽게 이름 바꿔서 이전할 수 있어요:

  mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

• 문서 내용은 언제든 업데이트 및 추가 가능! ‘살아있는 규칙서’로 관리하세요.

자주 묻는 질문(FAQ) 요약

• 필수 항목은 없습니다.

• 중복/충돌 시, 가장 가까운(최상위?) AGENTS.md가 우선합니다.

• 테스트, 빌드 등 AGENTS.md에 적힌 명령은 에이전트가 실제로 실행해볼 수 있습니다.

• 지속적으로 업데이트하면서 팀/에이전트에게 최적화하세요.

창업자/팀장이라면 왜 신경 써야 할까?

AI 개발 자동화가 점점 보편화되는 만큼, 사람과 에이전트 모두를 만족시키는 명확한 기준서가 협업 생산성을 크게 높여줍니다. 스타트업처럼 속도가 중요한 팀에서는 AGENTS.md로 개별 의존도 줄이고 자동화/스케일업에 대비해보세요!

출처 : AGENTS.md