빠른 답변 (Quick answer)

만약 두 개 이상의 AI 코딩 에이전트 (AI coding agent)를 사용한다면, 모든 도구에 적용할 하나의 거대한 지침 파일을 만드는 것으로 시작하지 마세요. 프로젝트 레이아웃, 설치 및 테스트 명령, 코딩 컨벤션 (coding conventions), 안전 경계, 그리고 완료 정의 (definition of done)와 같은 공유 계약을 담은 작은 레포지토리 수준의 AGENTS.md로 시작하세요.

그 후, 동작이 진정으로 달라질 때만 도구별 파일을 추가하세요:

• Codex, Cursor 및 기타 에이전트가 읽을 수 있는 휴대 가능한 프로젝트 지침에는 AGENTS.md를 사용하세요.
• Claude Code가 Claude 전용 프로젝트 메모리나 규칙이 필요할 때는 CLAUDE.md를 사용하세요.
• GitHub Copilot이 레포지토리 또는 조직 컨텍스트 (context)가 필요할 때는 .github/copilot-instructions.md 또는 범위가 지정된 GitHub 지침 파일을 사용하세요.
• 지침이 파일 유형, 디렉토리 또는 IDE 워크플로우 (workflow)에 따라 범위가 지정되어야 할 때는 Cursor Rules를 사용하세요.

중요한 차이점: 지침 파일은 모델의 동작을 안내합니다. 이는 강제적인 집행이 아닙니다. 협상 불가능한 체크 사항은 스크립트 (scripts), CI, 훅 (hooks), 권한 또는 리뷰 게이트 (review gates)에 배치하세요.

대상 (Who this is for)

이 가이드는 AI 코딩 도구를 사용하면서도 다음과 같은 동일한 수정을 계속 반복하고 있는 인디 개발자, 소규모 팀, 그리고 1인 창업자를 위한 것입니다:

• "완료되었다고 말하기 전에 테스트를 실행하세요."
• "이를 위해 새로운 의존성 (dependency)을 추가하지 마세요."
• "기존의 컴포넌트 패턴을 따르세요."
• "관련 없는 파일은 건드리지 마세요."
• "중국어 카피도 작성하세요."

그러한 반복은 하나의 신호입니다: 해당 규칙은 채팅에서 벗어나 지속 가능한 프로젝트 파일로 이동해야 합니다. 이는 Codex는 레포지토리 작업용, Claude Code는 탐색용, Cursor는 IDE 작업용, Copilot은 제안 또는 리뷰용으로 여러 도구를 동시에 사용할 때 더욱 중요합니다.

무엇이 변했고 왜 지금인가 (What changed and why now)

AI 코딩 도구는 자동 완성 (autocomplete) 단계에서 에이전트 워크플로우 (agent workflows) 단계로 이동했습니다. 이들은 레포지토리를 읽고, 명령을 실행하며, 파일을 편집하고, MCP 서버를 호출하며, 때로는 여러 단계에 걸쳐 작업합니다. 이제 프로젝트 지침은 가치가 있지만, 과하게 설정하기 쉽습니다.

수요 신호가 명확히 보입니다. Google 자동 완성에는 agents.md best practices, agents.md vs claude.md, agents.md vs copilot-instructions.md와 같은 검색어가 나타납니다. 최근 Hacker News의 토론에서는 AGENTS.md, 공유 에이전트 메모리 (shared agent memory), 그리고 지침 파일 (instruction files)이 실제로 도움이 되는지에 대해 언급하고 있습니다. 공식 문서 또한 생태계의 형태를 드러냅니다. OpenAI는 AGENTS.md를 문서화하고, Anthropic은 CLAUDE.md와 자동 메모리 (auto memory)를 문서화하며, GitHub은 Copilot 커스텀 지침 (custom instructions)을 문서화하고, Cursor는 Rules와 더불어 AGENTS.md 지원을 문서화하고 있습니다.

소규모 제품 저장소 (repo)의 경우, 이는 다음과 같은 실무적인 질문을 던집니다: 규칙은 어디에 위치해야 하는가?

실무 워크플로우 (The practical workflow)

더 많은 지침 파일을 추가하기 전에 다음 순서를 따르십시오:

1. 반복되는 수정 사항을 감사 (Audit) 하십시오. 명령어를 잊음, 관련 없는 파일 편집, 놓친 아키텍처 패턴, 오해된 제품 경계, 또는 검증되지 않은 성공 사례 등 실제 실수들을 수집하십시오.
2. 공유 저장소 정보 (shared repo facts)를 AGENTS.md에 넣으십시오: 레이아웃, 소유권 경계, 패키지 매니저 (package manager), 빌드/테스트/린트 (build/test/lint) 명령어, 제품 규칙, "하지 말아야 할" 규칙, 그리고 완료 기준 (completion standards).
3. 실제 차이점이 있는 경우에만 도구별 파일을 추가하십시오. Claude 전용 메모리나 규칙에는 CLAUDE.md를, GitHub 네이티브 동작에는 Copilot 지침을, 범위가 지정된 IDE 워크플로우에는 Cursor Rules를 사용하십시오.
4. 강제성 (enforcement)을 체크 단계로 이동시키십시오. 비밀값 (Secrets), 배포 권한, JSON 유효성, 그리고 이중 언어 파일 요구 사항은 스크립트, CI, 훅 (hooks), 권한 또는 리뷰 게이트 (review gates)를 통해 검증되어야 합니다.
5. 새로운 세션에서 테스트하십시오. 에이전트에게 로드된 규칙을 요약하도록 요청한 다음, 작고 안전한 작업을 부여하십시오. 만약 에이전트가 명령어나 완료 기준을 놓친다면, 파일을 줄이고 규칙을 더 구체적으로 만드십시오.

"깨끗한 코드를 작성하라" 또는 "주의하라"와 같은 모호한 선호 사항은 피하십시오. 대신 관찰 가능한 체크 사항으로 대체하십시오: 이 명령어를 실행하라, 이 경로를 검사하라, 이 API를 보존하라, 이 디렉토리를 편집하지 마라, 이 리스크를 보고하라.

결정 트리 (Decision tree)

이 규칙이 저장소 내의 모든 도구에 유용한가?
  예 -> AGENTS.md에 넣으십시오.
  아니오 -> 계속 진행하십시오.
...

시작용 AGENTS.md 템플릿

AGENTS.md

Project context (프로젝트 컨텍스트)

...

첫 번째 버전은 지루하게 유지하십시오. 가장 좋은 파일은 에이전트가 실제로 따를 수 있는 파일입니다.

Common mistakes (흔한 실수)

• 다른 저장소(repo)의 파일을 복사하는 것. 이는 다른 팀의 도구, 위험 요소, 리뷰 습관을 인코딩(encoding)합니다.
• 선호도와 강제 사항을 혼합하는 것. "비밀 정보를 절대 노출하지 마십시오"는 비밀 스캐닝(secret scanning), 무시된 환경 변수 파일(.env files), 그리고 리뷰 단계보다 약합니다.
• 동일한 규칙을 다섯 군데에 중복해서 넣는 것. 공유 규칙은 AGENTS.md에 속해야 하며, 도구별 파일은 해당 도구가 다른 형식을 필요로 할 때만 존재해야 합니다.
• 지침 파일(instruction files)을 영구적인 것으로 취급하는 것. 반복적인 실패가 나타나면 업데이트하고, 규칙이 오래되면 다듬으십시오.

FAQ (자주 묻는 질문)

AGENTS.md와 CLAUDE.md에 동일한 내용이 포함되어야 합니까?

보통은 아닙니다. 공유 프로젝트 규칙은 AGENTS.md에 넣으십시오. Claude Code가 Claude 전용 메모리, 규칙 또는 워크플로(workflow) 노트를 필요로 할 때 CLAUDE.md를 추가하십시오. 두 파일이 모두 존재한다면, 파일 간의 내용이 어긋나지 않도록 하나가 공유 계약(shared contract)을 참조하게 만드십시오.

AGENTS.md만으로 보안이 충분합니까?

아니요. 에이전트에게 비밀 정보, 권한, 위험한 명령에 대해 상기시킬 수는 있지만, 강제 집행(enforcement)은 권한 설정, 훅(hooks), CI, 비밀 스캐닝(secret scanning) 및 인간의 리뷰에 맡겨야 합니다.

파일의 길이는 어느 정도가 적당합니까?

새로운 기여자가 훑어볼 수 있을 정도로 짧아야 합니다. 만약 파일이 매뉴얼처럼 커진다면, 반복되는 워크플로를 스크립트(scripts), 스킬(skills) 또는 런북(runbooks)으로 옮기십시오.

IndieSeek는 이 기사를 어디에 링크해야 합니까?

자연스러운 내부 링크로는 재사용 가능한 에이전트 워크플로를 위한 Codex Record & Replay principles 기사와, 게시 전 AI가 생성한 Markdown 또는 HTML을 검토하기 위한 MD+HTML Reader가 있습니다.

Sources (출처)

• OpenAI Codex: AGENTS.md를 활용한 커스텀 인스트럭션 (Custom instructions)
• OpenAI Codex: 베스트 프랙티스 (Best practices)
• Claude Code 문서: Claude가 프로젝트를 기억하는 방법
• GitHub Docs: Copilot을 위한 커스텀 인스트럭션 (Custom instructions) 추가하기
• Cursor Docs: 규칙 (Rules)
• Hacker News Algolia 검색: AGENTS.md
• Google Trends US RSS