AGENTS.md vs CLAUDE.md vs SKILL.md: 어떤 에이전트에 어떤 파일? 연구가 말하는 것 (2026)

- 이 글의 연구 수치와 도구 현황(크로스툴 표준으로서의 AGENTS.md, 임포트 문법)은 집필 시점의 출처와 대조해 확인했어요. 이 도구들은 변화가 빠르니 최신 공식 문서로 확인하세요.

AGENTS.md 와 CLAUDE.md — 같은 걸까요?

본질적으로는 같은 아이디어예요 — 에이전트가 프로젝트 관례를 익히려고 읽는 파일이고, 도구마다 이름만 다를 뿐이죠. CLAUDE.md 는 Claude Code의 관례예요. AGENTS.md 는 떠오르는 크로스툴 표준으로, Codex CLI, Copilot CLI, Gemini CLI, Cursor, 그리고 Claude Code에서도 읽혀요.

둘 다 하는 일은 같아요. 채팅 세션이 바뀌어도 남아 있는 지속적인 브리핑을 에이전트에게 주는 거죠. 그래서 매번 관례를 다시 물어보지 않아도 돼요. 기억해 둘 만한 유일한 차이는, CLAUDE.md에는 AGENTS.md가 표준화하지 않은 Claude Code 고유 기능이 몇 가지 남아 있다는 점이에요 — 특히 계층적 로딩과 임포트요. 템플릿과 함께 CLAUDE.md를 처음부터 끝까지 작성하는 방법은 CLAUDE.md 가이드를 보세요.

비슷한 셋을 헷갈리지 않게 한 줄로: AGENTS.md(파일 표준)는 AgentKit(Claude Code용 키트, agentkit.best)과도, OpenAI AgentKit(Agent Builder/ChatKit)과도 다른 거예요.

AGENTS.md vs CLAUDE.md vs SKILL.md: 어떤 파일이 어떤 일을 하나요?

이제 AGENTS.md와 CLAUDE.md만 에이전트가 읽는 프로젝트 파일이 아니에요. SKILL.md 는 완전히 다른 종류의 파일이에요. SKILL.md 파일이 담긴 폴더로(name/description을 담은 YAML 프런트매터와 Markdown 본문, 선택적으로 scripts/, references/, assets/를 함께 두죠), 항상 로드되는 컨텍스트가 아니라 재사용 가능한 온디맨드 기능을 패키징해요. 에이전트는 작업을 스킬의 description과 대조해 관련될 때만 로드해요(또는 직접 호출하죠). Anthropic이 이 포맷을 Claude Code용으로 만들었고(2025년 10월), 오픈 Agent Skills 표준으로 공개했어요(agentskills.io). Codex는 몇 주 만에 도입했고 — OpenAI 자체 문서도 Codex의 「skills build on the open agent skills standard」라고 확인해 줘요(learn.chatgpt.com/docs/build-skills).

AGENTS.md/CLAUDE.md와의 차이는 단순한 이름이 아니라 종류의 차이예요. AGENTS.md와 CLAUDE.md는 항상 로드되는 지속적 컨텍스트예요 — 바로 아래 연구가 측정한 대상이고, 부풀리면 추론 비용이 20% 넘게 드는 이유이기도 하죠. SKILL.md는 작업이 일치할 때만 온디맨드로 로드돼요 — 뒤 절에서 글쓰기 기법으로 빌려 오는 프로그레시브 디스클로저 모델이에요. 이제 그 기법이 왜 통하는지 알겠죠. 지금 쓰지도 않는 기능에 컨텍스트를 낭비하지 않으려는, 스킬 그 자체의 작동 방식이니까요.

세 파일은 누가 읽는지, 어떤 포맷을 쓰는지, 무엇에 좋은지에서도 달라요:

분명히 짚을 사실 하나: Codex는 AGENTS.md를 읽어요 — CLAUDE.md는 전혀 읽지 않아요. Codex가 도구 체인에 있다면 실제로 보는 파일은 AGENTS.md예요. 로딩 순서 전체는 Codex의 AGENTS.md 설정 메커니즘을 보세요. Codex가 스킬을 구체적으로 어떻게 로드하는지는 Codex Skills의 작동 방식을 보세요.

빠른 선택: 에이전트가 테스트/빌드 명령과 깨뜨리면 안 되는 규칙을 늘 알고 있어야 하나요? 그럼 AGENTS.md(Claude Code에서는 CLAUDE.md)를 쓰세요. 가끔만 트리거하는 재사용 가능한 기능 — 워크플로나 스크립트 묶음 — 이 필요하면 대신 SKILL.md를 쓰세요.

연구가 찾아낸 것 — 도움은 되지만, 아주 조금

"컨텍스트 파일이 정말 도움이 되나"라는 물음에 이제 데이터가 있어요. Gloaguen 외의 연구 "Evaluating AGENTS.md"(2026년 2월 제출)는 여러 에이전트, 모델, 리포지터리에 걸쳐 컨텍스트 파일을 측정했어요. 결과는 한 번 멈춰서 볼 만해요:

• 작업 성공률에서 전반적인 개선은 없었어요 — LLM이 생성한 파일에도, 개발자가 커밋한 파일에도 둘 다 해당돼요. 흔한 권장과는 반대되는 결과죠.
• 추론 비용은 평균 20% 넘게 올랐어요.
• 리포지터리 개요는 — 인기 있고 모델 제공사도 권장하지만 — 도움이 안 됐어요. 반면 컨텍스트 파일 안의 지시는 에이전트가 제대로 따랐어요.

과장되기 쉬운 점 하나: "개발자가 쓴 파일이 더 낫다"는 게 아니에요. 연구는 어느 유형도 성공률을 확실히 높이지 못한다는 걸 밝혔어요. 다만 지시는 따르는데 개요는 안 따르니, 실용적 결론은 날카로워요. 개요라는 군더더기는 잘라내고, 실행 가능한 지시는 남기세요. 파일은 작게, 성공률은 그대로, 비용은 낮게.

역설 — 에이전트가 너무 열심히 따라요

흥미로운 부분은, 에이전트가 지시를 무시하는 게 아니라 조금 너무 열심히 따른다는 거예요. 테스트를 언급하면 테스트를 더 돌려요. 도구를 언급하면 도구를 더 써요. 리포지터리 고유 워크플로를 언급하면 더 많이 탐색해요.

문제는 그런 지시 중 상당수가 작업을 더 빨리 풀도록 돕지 않고, 그저 작업을 더 무겁게 만든다는 점이에요. 당신이 한 줄 더할 때마다 에이전트가 "반드시" 실행해야 한다고 느끼는 줄이 하나 더 늘어요. 그래서 부풀린 파일은 토큰을 태우고, 더 나은 결과도 없이 작업을 질질 끌어요.

그러니 AGENTS.md가 잘못된 게 아니라 — 쓰는 방식이 문제예요

핵심은 "컨텍스트 파일을 버려라"가 아니에요. 이거예요: 버그 하나 고칠 때마다 에이전트가 다시 읽어야 하는 2,000단어짜리 안내서로 AGENTS.md를 만들지 마세요.

실행 가능한 부분은 남기세요:

• 테스트 명령, 빌드 명령, 실행 명령.
• 깨뜨리면 안 되는 규칙(공개 API를 바꾸지 마라, 디렉터리 X를 건드리지 마라…).
• 중요한 경로 / 디렉터리.

나머지는 에이전트가 알아내게 두세요. 노골적으로 말하면, 에이전트를 우리 지식에 너무 꽉 묶어 두면 결국… 우리처럼 멍청해져요. 날아다닐 여유를 좀 주고, 그다음에 실제 요구사항 쪽으로 다시 몰아가면 돼요.

SKILL.md처럼 "프로그레시브 디스클로저" 방식으로 쓰세요

위에서 다뤘듯 SKILL.md는 온디맨드로 로드돼요 — 같은 아이디어를 AGENTS.md에도 적용하세요. 작은 파일로 쪼개서 지연 로드하는 거죠: "A를 한다면 파일 X를 읽어라." 필요 없을 때는 에이전트가 건너뛰고 컨텍스트를 전혀 쓰지 않아요.

CLAUDE.md에서는 @path/to/file 임포트 문법으로 이걸 해요(도구가 빨리 바뀌니 최신 문법을 확인하세요). 루트 파일에는 늘 참인 코어만 두고, 작업 종류별 상세는 별도 파일에 두었다가 관련될 때 끌어와요. 이건 Claude Code skills가 컨텍스트에 따라 지시를 로드하는 것과 같은 메커니즘이에요. 만드는 법은 커스텀 스킬 만드는 방법을 보세요. 전체 컨텍스트 예산은 컨텍스트와 메모리 관리를 보세요.

파일 하나? 둘? (심링크 트릭)

파일을 하나만 둔다면, 가장 많은 도구가 읽는 AGENTS.md로 하세요. Claude Code가 주력 에이전트이지만 모든 도구가 동작하길 원한다면, 인기 있는 트릭은 단일 진실 소스로 만드는 거예요: AGENTS.md를 쓰고 CLAUDE.md를 거기로 심링크하세요.

mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md

이렇게 하면 콘텐츠를 한곳에 두면서 모든 도구를 지원해요. 트레이드오프는 CLAUDE.md의 계층적 로딩과 임포트를 잃는다는 점이에요 — 그러니 @path 임포트에 크게 의존한다면 CLAUDE.md를 심링크 대신 실제 파일로 남겨 두는 걸 고려하세요.

비포/애프터: 긴 안내서에서 열몇 줄로

초기부터 지금까지 Claude Code 키트를 써 본 사람이라면 알아챌 거예요. 하나의 긴 CLAUDE.md를 저는 겨우 열몇 줄로 압축했어요. 이 파일은 프로젝트 특화여야 하니까요 — 이 프로젝트에 필요한 추가 규칙만 딱 담고, 뭐든 쟁여 두는 범용 잡동사니가 되면 안 돼요.

다듬는 규칙: 모든 줄이 "이게 에이전트의 판단을 어디서 바꾸지?"에 답할 수 있어야 해요. 답을 못 하면 그건 개요 군더더기예요 — 잘라내거나 지연 로드 파일로 밀어내세요. 복사해 쓸 간결한 CLAUDE.md 템플릿은 CLAUDE.md 가이드에 있어요.

남기기 / 잘라내기 체크리스트

간결한 컨텍스트가 기본 내장된 키트 (AgentKit)

직접 조율하고 싶지 않다면, AgentKit 같은 키트(agentkit.best, ak CLI — OpenAI AgentKit과는 달라요)는 간결한 CLAUDE.md 관례에 더해 프로그레시브 디스클로저 방식으로 쓰인 스킬 세트를 함께 제공해서, 부풀린 안내서를 손수 만들 필요가 없어요. 개요는 AgentKit 리뷰를 읽거나 AgentKit(링크로 20% 할인)을 보세요.

자주 묻는 질문 (FAQ)

AGENTS.md와 CLAUDE.md는 같나요?

아이디어는 같고 도구마다 이름만 달라요. CLAUDE.md는 Claude Code의 관례이고, AGENTS.md는 여러 도구(Codex, Copilot CLI, Gemini CLI, Cursor, Claude Code)가 읽는 크로스툴 표준이에요. CLAUDE.md에는 계층적 로딩과 임포트 같은 추가 기능이 몇 가지 남아 있어요.

Claude Code는 AGENTS.md를 읽나요?

현재로선 Claude Code가 CLAUDE.md와 함께 AGENTS.md도 읽을 수 있어요 — 다만 이 영역은 빨리 바뀌니 최신 공식 문서로 확인하세요. @path 임포트와 계층적 로딩에 의존한다면 CLAUDE.md는 여전히 남겨 둘 만한 루트 파일이에요.

컨텍스트 파일이 정말 에이전트에 도움이 되나요?

2026년 연구에 따르면, 컨텍스트 파일은 작업 성공률을 확실히 높이지 못하고(LLM 생성이든 개발자 작성이든) 비용을 20% 넘게 올려요. 특히 리포지터리 개요는 도움이 안 됐고, 구체적인 지시는 잘 따랐어요. 교훈: 실행 가능한 지시는 남기고 개요는 잘라내세요.

CLAUDE.md는 얼마나 길어야 하나요?

가능한 한 간결하게 — 늘 참인 코어만 남기고 상세는 @path 임포트로 지연 로드 파일에 밀어내세요. 모든 줄이 에이전트의 판단을 바꿔야 하고, 아니면 잘라내세요.

CLAUDE.md에서 "프로그레시브 디스클로저"란 무엇인가요?

내용을 작은 파일로 쪼개 온디맨드로 로드하는 거예요: "A를 한다면 파일 X를 읽어라." 관련이 없을 때는 에이전트가 건너뛰고 컨텍스트를 쓰지 않아요 — 스킬이 컨텍스트가 맞을 때 지시를 로드하는 것과 같은 방식이죠.

AGENTS.md에서 무엇을 남기고 무엇을 잘라내야 하나요?

남기기: 테스트/빌드/실행 명령, 깨뜨리면 안 되는 규칙, 중요한 경로, 그리고 필요할 때 상세를 읽는 임포트. 잘라내기: 리포지터리 개요, 긴 문장, 거의 안 쓰는 워크플로, 에이전트가 이미 아는 일반 지식.

SKILL.md는 AGENTS.md와 어떻게 다른가요?

SKILL.md는 작업이 일치할 때만 온디맨드로 로드되는 재사용 가능한 기능이에요. 반면 AGENTS.md는 항상 로드되는 지속적 컨텍스트죠. 스킬 제작과 설치 전체 과정은 Codex Skills의 작동 방식을 보세요.

결론

컨텍스트 파일은 효과가 있어요 — 간결하고 프로그레시브 디스클로저 방식으로 쓰였을 때요. 길게 쓰는 건 자해예요: 비용은 20% 넘게 늘고 결과는 나아지지 않아요. 개요는 잘라내고, 실행 가능한 지시는 남기고, 나머지는 지연 로드하세요. 템플릿은 CLAUDE.md 가이드를 보고, 자율 실행도 한다면 /goal 효율적으로 쓰는 법과 함께 쓰세요.