AGENTS.md — Cross-Tool 시스템 가이드라인 표준

Codex·Claude Code·Gemini 등 주요 코딩 에이전트가 공통으로 인식하는 프로젝트 루트의 시스템 프롬프트 .md 파일. 벤더 중립 표준으로 부상 중.

정의

AGENTS.md 는 프로젝트 루트에 두는 에이전트용 시스템 가이드라인 문서다. 다음 4가지 역할을 한다.

1. 프로젝트 맥락 — 이 코드가 무엇을 하는가, 누가 쓰는가
2. 반복 실수 방지 — AI가 과거에 했던 흔한 실수의 가드레일
3. 서브에이전트·스킬 사용 규칙 — 어떤 워크플로우에 어떤 도구를 써야 하는가
4. 유지보수 메모 — 의도적 결정·트레이드오프·미해결 항목

왜 표준이 됐는가

• CLAUDE.md / .codex.md / .gemini.md 벤더별 파일이 난립 → 멀티 도구 사용자가 같은 내용을 여러 곳에 복붙해야 함 → 비효율
• AGENTS.md는 벤더가 만든 표준이 아니라 사용자가 만든 표준 — 커뮤니티가 자연 수렴한 이름
• 주요 LLM 벤더들이 이를 자발적으로 인식하기 시작 — Codex 공식 가이드, Claude Code CLAUDE.md와 병행 인식, Gemini CLI 도입

작성 원칙

• 한글로 작성: 유지보수 가독성이 토큰 효율(영어 대비 ~1.7배 비싸다는 통계)보다 중요. (출처: yt-ZDfNfEGo7Fc-Codex-바이브코딩-2시간-라이브)
• 살아있는 문서: 일회성 작성 후 방치 ❌. 매 작업마다 새로 학습한 가드레일을 추가.
• 간결성: 50~100줄 권장. 너무 길면 모델이 핵심을 놓침.
• 명령형 문장: “X 하지 마” / “Y 할 땐 Z 확인” — 모호한 설명문보다 명령이 효과적.

시연 사례

yt-ZDfNfEGo7Fc-Codex-바이브코딩-2시간-라이브 에서 영어로 자동 생성된 AGENTS.md를 즉시 “한글로 다시 써줘”로 재작성하는 패턴을 명시. 4단계 문서 하네스의 마지막 단계로 배치.

관련 개념

• 4단계-문서-하네스 — AGENTS.md는 이 패턴의 4번째 문서.
• harness-engineering — AGENTS.md는 가장 표준화된 하네스 컴포넌트.
• MCP-모델-컨텍스트-프로토콜 — 다른 cross-tool 벤더 표준 사례 (도구 연결 측면).
• vibe-coding — 바이브 코딩 시 AGENTS.md 유무가 품질을 좌우.

관련 엔티티

• openai-codex — AGENTS.md를 공식 가이드에 명시.
• claude-code — CLAUDE.md와 병행 인식.
• Gemini — Gemini CLI에서 인식.