최근 AI 코딩 어시스턴트를 사용해봤다면 아마 한 가지를 알아챘을 것입니다: 모두 Markdown 파일을 원합니다.

GitHub Copilot은 .github/copilot-instructions.md를 읽습니다. Cursor는 .cursor/rules/를 읽습니다. Claude Code는 CLAUDE.md를 읽습니다. Windsurf는 .windsurf/rules를 읽습니다. Google의 Jules는 JULES.md를 읽습니다. 그리고 범용 표준은? AGENTS.md --- 이제 60,000개 이상의 오픈소스 리포지토리에서 사용되며 Linux Foundation의 Agentic AI Foundation이 관리합니다.

Markdown은 문서화 형식에서 AI 코딩 에이전트의 운영 체제로 진화했습니다.

AGENTS.md란?

AGENTS.md는 리포지토리에 있는 간단한 오픈 포맷 Markdown 파일로 AI 코딩 에이전트를 위한 브리핑 패킷 역할을 합니다. README.md의 상대방으로 생각하세요:

README.md는 인간을 위한 것: 빠른 시작, 프로젝트 설명, 배지
AGENTS.md는 AI 에이전트를 위한 것: 빌드 단계, 테스트 명령, 코딩 규칙, 아키텍처 결정

에이전트는 디렉토리 트리에서 가장 가까운 파일을 읽으므로 가장 가까운 파일이 우선합니다. 각 하위 프로젝트는 맞춤형 지시사항을 제공할 수 있습니다.

CLAUDE.md란?

CLAUDE.md는 Anthropic의 Claude Code를 위한 것입니다. 각 세션 시작 시 자동으로 읽히며 그렇지 않으면 모든 프롬프트에서 반복해야 할 프로젝트별 지시사항을 담고 있습니다.

좋은 CLAUDE.md에는 일반적으로 다음이 포함됩니다:

프로젝트 컨텍스트: 프로젝트가 무엇을 하는지 Claude에게 방향을 잡아주는 한 줄
코드 스타일: 서식 기본 설정, 명명 규칙, 따라야 할 패턴
명령어: 테스트 실행, 빌드, 린트, 배포 방법
아키텍처 메모: Claude가 존중해야 할 핵심 결정사항

권장 접근 방식: 공유 지시사항은 AGENTS.md에 (모든 AI 도구가 혜택을 받도록), 그런 다음 Claude 특정 기능을 CLAUDE.md에 추가합니다.

AI 지시 파일의 전체 풍경

모든 주요 AI 코딩 도구와 해당 Markdown 규칙:

도구	파일	형식
GitHub Copilot	`.github/copilot-instructions.md`	Markdown
Cursor	`.cursor/rules/*.md`	Markdown
Claude Code	`CLAUDE.md`	Markdown
Windsurf	`.windsurf/rules`	Markdown
Google Jules	`JULES.md`	Markdown
범용	`AGENTS.md`	Markdown

패턴이 보이나요? 모두 Markdown입니다. 하나하나 다.

Markdown이 이긴 이유

Markdown이 AI 지시 파일의 완벽한 형식인 이유:

LLM이 기본적으로 이해 --- 훈련 데이터에서 가장 일반적인 형식
사람이 읽을 수 있음 --- 개발자가 지시사항을 쉽게 검토하고 편집 가능
버전 관리 가능 --- 코드와 함께 git에 있음
가벼움 --- 파싱 오버헤드 없음, 특수 도구 불필요
범용 --- 모든 AI 도구, 편집기, 플랫폼에서 작동

Visual Studio Magazine의 말대로: 에이전트 AI에서는 모두 Markdown에 관한 것입니다.

에이전트 지시사항 작성 모범 사례

수천 개의 리포지토리 분석을 바탕으로:

최소로 시작하세요. 에이전트가 같은 실수를 반복해서 하는 것을 알아챌 때만 규칙을 추가하세요. 너무 세밀하게 지정된 지시사항은 도움보다 혼란을 줄 수 있습니다.

명령어에 대해 구체적으로. “테스트 실행”이라고 하지 말고 pnpm test 또는 pytest -x tests/라고 하세요.

아키텍처를 문서화하세요. 프로젝트가 특정 패턴(예: 콘텐츠 스크립트와 서비스 워커 간의 메시지 전달)을 사용한다면 설명하세요. 에이전트는 코드만으로 아키텍처 결정을 추론할 수 없습니다.

하지 말아야 할 것도 포함하세요. 부정적 지시사항은 놀랍도록 효과적입니다: “데이터베이스 스키마를 직접 수정하지 마세요” 또는 “클래스 컴포넌트를 사용하지 말고, 항상 훅을 사용하세요.”

Save가 이 세계에 어떻게 맞는가

에이전트 지시 파일을 구축하고 있다면, 웹에서 참조 자료도 저장하고 있을 것입니다: 문서 페이지, Stack Overflow 답변, GitHub README, API 참조.

Save는 이러한 웹 소스를 한 클릭으로 깔끔한 Markdown으로 변환합니다 --- AI 에이전트에 필요한 컨텍스트를 구축하는 데 완벽합니다. 문서 페이지를 저장하고, Markdown을 AGENTS.md나 참조 문서에 붙여넣으면, AI 코딩 어시스턴트가 즉시 필요한 컨텍스트를 갖게 됩니다.

워크플로우:

웹에서 유용한 문서나 코드 예시 찾기
Save를 클릭하여 Markdown으로 변환
에이전트 지시 파일에 참조하거나 포함
저장할 때마다 AI 코딩 어시스턴트가 더 잘 작동

미래: AI의 제어 표면으로서의 Markdown

Microsoft와 GitHub는 이제 Markdown을 AI 동작을 위한 안정적이고 감사 가능한 제어 표면으로 취급하고 있습니다. 더 이상 문서화만이 아닙니다 --- 인간의 의도와 AI 실행 사이의 인터페이스입니다.

Markdown 파일이 세 가지 뚜렷한 역할을 하는 것을 봅니다:

문서화: 인간에게 시스템을 설명
지시: AI 동작을 제한하고 조종
스킬: 에이전트가 워크플로우를 반복할 수 있도록 지시사항과 리소스를 묶음

이 트렌드는 가속화될 뿐입니다. AI 코딩 어시스턴트가 더 유능해질수록, 그들을 안내하는 Markdown 파일이 더 중요해집니다.

Save는 어떤 웹페이지든 한 클릭으로 깔끔한 Markdown으로 변환합니다. 참조 라이브러리 구축, 문서 캡처, AI 코딩 워크플로우를 위한 컨텍스트 생성에 완벽합니다. Save 무료로 사용해보기.