AGENTS.md¶
왜 AGENTS.md인가요¶
코드 어시스턴트가 프로젝트를 제대로 이해하고 일하려면, 프로젝트마다 다른 규칙을 알아야 해요. AGENTS.md는 이를 위한 가볍고 레포 안에 두는 지시 파일이에요. 프로젝트 루트에 두면 코딩 에이전트가 일관된, 프로젝트별 가이드를 받을 수 있죠. 컨벤션, 커맨드, 아키텍처 메모, 가드레일을 여기에 담아서, "어시스턴트가 어떤 방식으로 일해주길 바라는지"의 기준점으로 삼아요. 레포 안의 이 파일이 곧 작업 방식의 source of truth가 되는 셈이에요.
CLI로 프로젝트 만들기¶
CrewAI CLI로 프로젝트를 스캐폴딩하면, 루트에 AGENTS.md가 자동으로 추가돼요.
# Crew
crewai create crew my_crew
# Flow
crewai create flow my_flow
# Tool repository
crewai tool create my_tool
프로젝트 유형(Crew, Flow, Tool 리포지토리)에 따라 만드는 커맨드가 달라지는데, 어떤 걸 만들든 루트에 AGENTS.md가 생긴다는 점은 같아요.
도구별 세팅: 어시스턴트가 AGENTS.md를 보게 하기¶
AGENTS.md를 만든 것만으로는 부족해요. 실제로 쓰는 코딩 어시스턴트가 이 파일을 읽도록 연결해줘야 해요. 도구마다 방식이 조금씩 다르니 하나씩 살펴볼게요.
Codex¶
Codex는 레포에 둔 AGENTS.md 파일의 안내를 받을 수 있어요. 컨벤션, 커맨드, 워크플로 기대치 같은 지속적인 프로젝트 컨텍스트를 공급하는 용도로 쓰면 돼요.
Claude Code¶
Claude Code는 프로젝트 메모리를 CLAUDE.md에 저장해요. /init으로 초기화할 수 있고, /memory로 편집하죠. 또 CLAUDE.md 안에서 import를 지원해서, 한 줄(@AGENTS.md)만 추가해도 공유 지시를 복제 없이 끌어올 수 있어요. 단순히 이렇게 해도 됩니다:
Gemini CLI와 Google Antigravity¶
Gemini CLI와 Antigravity는 레포 루트와 상위 디렉터리에서 프로젝트 컨텍스트 파일(기본값: GEMINI.md)을 읽어요. Gemini CLI 설정에서 context.fileName을 바꾸면 AGENTS.md를 대신(또는 추가로) 읽게 구성할 수 있어요. 예를 들어 AGENTS.md만 지정하거나, 각 도구의 형식을 유지하고 싶다면 AGENTS.md와 GEMINI.md를 둘 다 넣을 수도 있어요. 이렇게 간단히 써도 되고요:
Cursor¶
Cursor는 AGENTS.md를 프로젝트 지시 파일로 지원해요. 프로젝트 루트에 놓으면 Cursor의 코딩 어시스턴트가 그 안내를 따르게 돼요.
Windsurf¶
Claude Code가 Windsurf와 공식 통합을 제공해요. Windsurf 안에서 Claude Code를 쓴다면 위의 Claude Code 안내를 따르고, CLAUDE.md에서 AGENTS.md를 import하면 돼요. Windsurf의 네이티브 어시스턴트를 쓴다면, 프로젝트 규칙이나 지시 기능(가능한 경우)을 AGENTS.md를 읽도록 설정하거나, 내용을 그대로 붙여넣으면 돼요.
더 알아보기¶
AGENTS.md를 프로젝트별 작업 방식의 기준점으로 삼고, CLI로 프로젝트를 만들면 자동으로 생긴다는 점을 기억해두세요.- Codex, Claude Code, Gemini CLI/Antigravity, Cursor, Windsurf처럼 각 도구마다 이 파일을 연결하는 방식이 다르다는 점을 확인해두면, 팀에서 쓰는 도구가 바뀌어도 헷갈리지 않아요.
AGENTS.md를 공유 기준으로 두고CLAUDE.md나GEMINI.md같은 도구별 파일에는 import 한 줄만 넣는 패턴이, 중복을 피하면서 도구별 형식도 살리는 방법이에요.