질문
AGENTS.md, CLAUDE.md 같은 파일은 무엇인가요?
답변
이 파일들은 AI가 프로젝트에서 일할 때 먼저 참고하도록 적어 두는 작업 안내문입니다. 사람이 새 팀원에게 폴더 구조와 규칙을 알려 주는 메모와 비슷합니다.
예를 들어 어떤 명령으로 테스트하는지, 건드리면 안 되는 폴더는 어디인지, 글이나 코드의 형식은 무엇인지 적을 수 있습니다.
다만 파일 이름과 읽는 방식은 도구마다 다릅니다. 중요한 규칙은 짧고 구체적으로 쓰고, 비밀번호·API 키·개인정보는 넣지 마세요.
짧게 답하면
AGENTS.md나 CLAUDE.md는 AI에게 매번 반복해서 말하던 프로젝트 규칙을 한곳에 모아 두는 파일입니다. AI가 무엇을 해야 하는지뿐 아니라, 무엇을 하면 안 되는지도 적어 두면 도움이 됩니다.
적어 두면 좋은 내용
프로젝트 목적, 자주 쓰는 실행 명령, 테스트 방법, 파일 작성 형식, 검토가 필요한 변경 범위입니다.
적으면 안 되는 내용
비밀번호, API 키, 고객 정보, 주민등록번호처럼 공개되면 안 되는 실제 비밀값입니다.
처음 쓰는 사람 기준으로 설명하면
AI는 프로젝트마다 폴더 이름, 실행 방법, 금지 사항을 저절로 알지 못합니다. 안내 파일은 그 차이를 줄여 주는 공용 메모입니다.
GitHub Copilot 문서는 AGENTS.md·CLAUDE.md·GEMINI.md를 에이전트 지침 파일로 안내하고, Claude Code 문서는 CLAUDE.md를 프로젝트 정보와 관례를 기록하는 메모로 설명합니다. 하지만 실제로 어느 파일을 읽는지는 사용 중인 도구의 공식 문서를 확인해야 합니다.
한 줄 정리: 안내 파일은 AI를 위한 프로젝트 사용설명서이고, 실제 권한이나 보안 설정을 대신하지는 않습니다.
바로 따라 해보기
1단계. 먼저 쓰는 AI 도구의 공식 문서에서 지원하는 안내 파일 이름과 위치를 확인하세요. 도구마다 AGENTS.md, CLAUDE.md 또는 다른 형식을 사용할 수 있습니다.
2단계. 첫 파일에는 “이 프로젝트의 목적”, “실행·테스트 명령”, “수정 전에 확인할 일”처럼 세 가지만 짧게 적어 보세요.
3단계. AI에게 파일 내용을 요약해 달라고 한 뒤, 실제로 지켜야 할 규칙이 빠지거나 오해될 여지가 없는지 사람이 검토하세요.
주의할 점
안내 파일에 “항상 실행”처럼 넓고 모호한 지시를 쓰면, AI가 생각보다 큰 범위의 작업을 시도할 수 있습니다. 삭제, 외부 전송, 결제, 관리자 권한처럼 영향이 큰 행동은 별도 승인과 확인을 남겨 두세요.
이런 내용은 다시 확인하세요
모든 파일 수정 허용 · 테스트 없이 배포 · 비밀값을 파일에 직접 기록 · 외부 서비스로 자동 전송 · 이해하지 못한 명령의 자동 실행
웹사이트와 앱 중 무엇부터 쓰면 좋을까요?
웹사이트·데스크톱 앱
프로젝트 폴더, 안내 파일, 바뀐 내용을 함께 보기 쉬워 처음 규칙을 작성하고 검토하기에 편합니다.
모바일 앱
안내문 초안을 생각하거나 문장을 다듬는 데는 좋지만, 실제 파일 위치와 변경 범위를 확인하는 일은 PC에서 하는 편이 안전합니다.
같이 보면 좋은 질문
AI에게 내 스타일이나 회사 규칙을 어떻게 알려주나요?
권한 승인은 어떤 기준으로 허용해야 하나요?
AI가 만든 변경사항은 어떻게 되돌리고 검토하나요?
확인한 공식 자료
GitHub Docs: Support for different types of custom instructions — AGENTS.md, CLAUDE.md, GEMINI.md 등 지원 형식이 도구별로 다를 수 있음을 확인했습니다.
GitHub Docs: Comparing Copilot CLI customization features — 프로젝트 지침이 반복 안내를 줄이고 팀 규칙을 유지하는 용도를 확인했습니다.
Anthropic Docs: Manage Claude’s memory — CLAUDE.md에 프로젝트 정보, 관례, 자주 쓰는 명령을 기록하는 방법을 확인했습니다.
