CLAUDE.md / AGENTS.md, 에이전트 운영 파일 표준화

프로젝트마다 CLAUDE.md, .cursorrules, copilot-instructions.md를 따로따로 관리하고 계신 분들 많으실 텐데요, 이거 하나로 합치려는 흐름이 실제로 표준화 단계까지 갔더라고요. 확인된 사실 위주로 정리해봤어요.

 

왜 파일이 이렇게 여러 개로 쪼개졌나

AI 코딩 에이전트마다 프로젝트 컨텍스트를 읽어오는 방식이 제각각이에요. 클로드 코드는 CLAUDE.md를 자동으로 읽고, 커서는 .cursorrules나 .cursor/rules 디렉터리를 읽고, 깃허브 코파일럿은 .github/copilot-instructions.md를 읽어요. 여러 도구를 같이 쓰는 팀이라면 같은 내용을 파일 세 개, 네 개에 나눠서 중복 관리해야 하는 상황이 생기는 거예요. 이 비효율을 해결하려고 나온 게 AGENTS.md라는 오픈 스탠다드예요.

 

AGENTS.md는 누가 만들었고 지금 어디까지 왔나

AGENTS.md는 원래 오픈AI의 코덱스 CLI가 먼저 대중화시킨 파일 형식이에요. 지금은 리눅스 재단 산하의 에이전틱 AI 파운데이션이 관리하는 개방형 표준으로 넘어갔고, 이 재단에는 앤트로픽, 구글, 마이크로소프트, 오픈AI가 플래티넘 멤버로 참여하고 있어요. 경쟁 관계인 회사들이 같은 표준화 기구에 이름을 올렸다는 게 이 흐름이 단순한 유행이 아니라는 걸 보여주는 부분이에요. 실제 채택 규모도 6만 개가 넘는 오픈소스 프로젝트에서 쓰이고 있다고 확인됐고요.

지원하는 도구 목록도 꽤 넓어요. 오픈AI 코덱스 CLI, 커서, 깃허브 코파일럿, 제미나이 CLI, 구글 줄스, 팩토리, 에이더, 젯, VS코드, 윈드서프, 데빈까지 30개 넘는 에이전트가 이 형식을 읽을 수 있다고 해요.

 

클로드 코드는 이 표준을 어떻게 다루나

여기서 중요한 부분인데요, AGENTS.md는 앤트로픽의 공식 스펙이 아니에요. 클로드 코드는 여전히 자기만의 CLAUDE.md를 기본으로 쓰고 있고요. 다만 클로드 코드가 특정 디렉터리에서 CLAUDE.md를 찾지 못했을 때 대체 수단으로 AGENTS.md를 읽어오도록 지원하고 있어요. 그러니까 완전히 갈아탄 게 아니라 폴백 방식으로 호환성만 열어둔 상태라고 보시면 정확해요.

여러 도구를 같이 쓰는 팀이라면 AGENTS.md 하나를 메인으로 두고, 클로드 코드 전용 기능이 필요할 때만 CLAUDE.md를 따로 두는 식으로 운영하는 게 지금 나온 가이드들의 공통된 조언이에요.

실전: AGENTS.md 기본 구조

AGENTS.md는 특별한 문법이 없어요. 그냥 마크다운으로 제목이랑 항목을 써주면 에이전트가 텍스트를 파싱해서 그대로 행동에 반영하는 방식이에요. 필수 필드도 없고 고정된 스키마도 없어서, 아래처럼 프로젝트 개요, 빌드 명령어, 코드 스타일, 테스트 방법, 보안 유의사항 정도를 담는 게 일반적이에요.

# 프로젝트 개요
FastAPI와 PostgreSQL을 쓰는 파이썬 웹 앱입니다.

# 빌드 및 테스트
- 가상환경 생성: python -m venv .venv
- 의존성 설치: pip install -r requirements.txt
- 테스트 실행: pytest tests/
- 앱 실행: uvicorn app.main:app --reload

# 코드 스타일
- PEP8을 따릅니다.
- 포맷팅은 black을 사용합니다.

# 보안 유의사항
- .env 파일은 절대 커밋하지 않습니다.
- 모든 사용자 입력을 검증합니다.

이렇게 만들어두시면 코덱스, 커서, 클로드 코드까지 대부분의 에이전트가 이 파일을 읽고 프로젝트 컨텍스트를 파악해요. 다만 여기서 주의하실 점이 하나 있는데요, 이 파일은 사람이 읽는 문서가 아니라 에이전트가 매 세션 시작할 때마다 읽는 운영 지침이라는 거예요. 그래서 "깔끔한 코드를 작성하세요" 같은 당연한 얘기나 린터가 알아서 처리할 스타일 규칙은 넣지 마시고, 에이전트가 코드만 봐서는 알 수 없는 정보 위주로 채우시는 게 효율적이에요.

모노레포에서는 이렇게

큰 레포지토리를 여러 패키지로 나눠서 관리하신다면 각 서브디렉터리마다 AGENTS.md를 따로 두실 수 있어요. 에이전트는 지금 수정하려는 파일과 가장 가까운 위치의 AGENTS.md를 우선적으로 읽어요. .gitignore나 eslint 설정 파일이 동작하는 방식이랑 비슷하다고 보시면 돼요. 실제로 오픈AI의 코덱스 리포지토리 자체도 디렉터리 트리 전체에 88개의 AGENTS.md 파일을 나눠서 운영하고 있다고 알려져 있어요.

정리

결국 지금 벌어지고 있는 건 에이전트별로 흩어져 있던 설정 파일들을 하나의 표준으로 수렴시키려는 움직임이에요. 앤트로픽을 포함한 주요 플레이어들이 표준화 기구에 이름을 올렸다는 게 이 흐름의 방향성을 보여주고요. 다만 클로드 코드 입장에서는 아직 AGENTS.md가 메인이 아니라 폴백 수단이라는 걸 기억하셔야 해요. 여러 도구를 같이 쓰시는 팀이라면 지금부터라도 AGENTS.md를 기본으로 잡고 필요한 부분만 CLAUDE.md로 보완하는 식으로 정리해두시면, 나중에 도구를 바꾸거나 팀원이 다른 에이전트를 쓰게 되더라도 설정을 다시 만드는 수고를 덜 수 있을 것 같아요.