프로젝트 지침 파일 (Project Instruction Files)

한 줄 정의

코딩 에이전트가 세션마다 자동으로 읽어 프로젝트 맥락·규칙을 파악하게 만드는 저장소 루트(또는 하위 폴더)의 마크다운 파일.

지금 상태 (2026-09 기준)

벤더별 전용 파일(CLAUDE.md, GEMINI.md 등)과 벤더 중립적 표준인 AGENTS.md가 공존합니다. AGENTS.md는 OpenAI Codex, Cursor, Google Jules, Amp, Factory 등이 함께 만든 개방형 포맷으로 6만 개 이상의 오픈소스 프로젝트가 채택했고, 이제 Linux Foundation 산하 Agentic AI Foundation(AAIF)이 관리합니다. Claude Code도 AGENTS.md를 폴백으로 인식하도록 확장되어, 한 저장소에 파일 하나만 두고 여러 에이전트에서 재사용하는 흐름이 자리 잡는 중입니다. Cursor의 .cursorrules는 사실상 폐기되어 .cursor/rules/*.mdc(파일별 glob·alwaysApply 메타데이터 포함)로 완전히 대체됐습니다.

개념

• CLAUDE.md: Claude Code가 세션 시작 시 자동 로드. 계층 구조를 가짐 — 전역(~/.claude/CLAUDE.md) → 프로젝트 루트 → 하위 디렉터리, 하위 디렉터리 파일이 우선하며 상위 내용은 상속·누적됨. @경로/파일.md 문법으로 다른 마크다운 파일을 임포트할 수 있어, 긴 규칙은 .claude/rules/*.md로 분리해 필요한 것만 불러오는 패턴이 일반적입니다. /init 명령으로 저장소를 스캔해 초안을 생성할 수 있습니다.
• AGENTS.md: 특정 벤더 전용 필드 없이 "빌드 명령, 테스트 명령, 코드 스타일, PR 규칙" 등을 표준 마크다운 섹션으로 적는 포맷. 모노레포에서는 여러 개(루트 + 하위 패키지별)를 둘 수 있고, 더 깊은 파일이 우선합니다.
• GEMINI.md: Gemini CLI가 동일한 계층 방식(전역/프로젝트/하위 폴더)으로 로드하는 자체 지침 파일.
• Cursor 규칙: 예전 .cursorrules(단일 파일, 컨텍스트 항상 포함)에서 .cursor/rules/ 아래 .mdc 파일들로 이전. 각 .mdc는 frontmatter로 description, globs, alwaysApply 여부를 지정해 특정 경로·상황에서만 로드되도록 스코프를 좁힐 수 있습니다.
• GitHub Copilot: 저장소 전체에 적용되는 .github/copilot-instructions.md와, 경로별로 스코프를 지정하는 .github/instructions/*.instructions.md(applyTo 프론트매터)를 지원. Copilot coding agent는 이후 AGENTS.md도 커스텀 지침으로 인식하도록 확장됐습니다.
• Windsurf: .windsurfrules(레포 단위)와 global_rules.md(전역, Cascade 설정에서 관리) 두 계층으로 규칙을 적용.
• Codex(OpenAI): AGENTS.md를 1급 지침 파일로 사용하며 CLI/IDE 확장 모두 동일 포맷을 공유.

벤더별 비교

잘 쓰는 법

• 짧게 유지합니다. 매 세션 컨텍스트로 통째로 들어가므로 수백 줄짜리 지침 파일은 오히려 핵심 규칙을 희석시킵니다 — 자주 언급되는 값(빌드/테스트 명령, 디렉터리 구조, 금지 사항)만 남기고 나머지는 링크나 @import로 분리.
  • 예: CLAUDE.md에 아키텍처 설명까지 500줄로 욱여넣으면 정작 "테스트는 npm test로 돌려라" 같은 자주 쓰는 규칙이 묻혀버리므로, 핵심 명령만 남기고 아키텍처 설명은 @docs/architecture.md로 분리합니다.
• "무엇을 하지 말라"보다 "무엇을 확인/실행하라"는 구체적 명령형으로 씁니다. 애매한 원칙 설명은 실제 동작에 잘 반영되지 않습니다.
  • 예: "코드 품질에 신경 써라" 대신 "수정 후 반드시 npm run lint를 실행하고 통과를 확인하라"처럼 구체적으로 써야 에이전트가 실제로 그 단계를 수행합니다.
• 빌드·테스트·린트 실행 명령, 커밋/PR 컨벤션처럼 도구가 매번 확인해야 하는 사실 정보를 최우선으로 넣습니다.
  • 예: 매번 다른 테스트 명령을 추측하게 두는 대신 "테스트는 pytest tests/, 린트는 ruff check ."처럼 정확한 명령을 CLAUDE.md 맨 위에 박아두면 에이전트가 헤매지 않습니다.
• 코드베이스 전반의 설명(아키텍처 개요, 사용 이유 등)은 별도 문서로 두고 지침 파일에는 "그 문서를 참고하라"는 포인터만 남깁니다.
  • 예: "왜 이 프로젝트가 마이크로서비스 구조인지"에 대한 긴 설명은 docs/architecture.md에 두고, CLAUDE.md에는 "구조 이해가 필요하면 docs/architecture.md를 먼저 읽어라"는 한 줄만 남깁니다.
• 모노레포는 하위 패키지별로 별도 AGENTS.md/CLAUDE.md를 둬서 스코프를 좁히는 것이 하나의 거대 파일보다 낫습니다.
  • 예: packages/api와 packages/web을 함께 쓰는 모노레포라면, 루트 AGENTS.md에는 공통 규칙만 두고 각 패키지 폴더에 "이 패키지는 Go, 테스트는 go test ./..." 같은 패키지별 규칙을 따로 둡니다.
• 여러 도구를 함께 쓴다면 AGENTS.md 하나를 기준으로 삼고, 벤더 전용 파일(CLAUDE.md 등)은 심볼릭 링크나 짧은 위임 문구("자세한 내용은 AGENTS.md 참고")로 중복을 줄입니다.
  • 예: Claude Code와 Codex CLI를 같이 쓰는 팀이라면 AGENTS.md에 실제 규칙을 다 적고, CLAUDE.md에는 "AGENTS.md 참고"라는 한 줄만 남기거나 AGENTS.md를 가리키는 심볼릭 링크로 대체합니다.
• 정기적으로 실제 에이전트 동작을 보고 지침을 다듬습니다 — 한 번 쓰고 방치하면 코드베이스가 바뀌어도 지침이 낡은 채로 남아 오히려 잘못된 방향을 유도합니다.
  • 예: 6개월 전 Jest로 테스트하던 시절 적어둔 "테스트는 npm test"가 그 사이 Vitest로 바뀌었는데도 CLAUDE.md에 그대로 남아있으면, 에이전트가 계속 존재하지 않는 명령을 실행하려 시도합니다.
• 시크릿·API 키·내부 URL 같은 민감 정보는 넣지 않습니다 — 저장소를 보는 모든 에이전트·사람이 읽는 파일입니다.
  • 예: "스테이징 DB 접속은 postgres://user:password@내부IP"처럼 실제 자격증명을 CLAUDE.md에 적어두면, 저장소를 포크하거나 열람하는 누구나 그 정보를 그대로 보게 됩니다.