AGENTS.md: 파일 위치와 도구별 읽기 방식

AGENTS.md는 대부분의 코딩 에이전트가 별도 설정 없이 읽는 일반 Markdown 형식의 프로젝트 지침 파일입니다. OpenAI는 이 파일을 Linux Foundation 산하 Agentic AI Foundation에 기여했으며, 6만 개가 넘는 오픈소스 프로젝트에서 사용합니다.

파일 위치

• 저장소 루트의 AGENTS.md: 프로젝트 전체에 적용됩니다.
• 하위 디렉터리나 패키지에 있는 AGENTS.md: 에이전트는 디렉터리 트리에서 가장 가까운 파일을 사용합니다.
• OpenAI Codex: 전역 파일 ~/.codex/AGENTS.override.md를 사용합니다. 이 파일이 비어 있거나 없으면 ~/.codex/AGENTS.md를 사용합니다.
• Cline: 전역 파일 ~/.agents/AGENTS.md를 사용합니다.
• Claude Code는 .claude/AGENTS.md도 지원합니다.

형식

frontmatter나 필수 필드가 없는 일반 Markdown 형식입니다. 제목은 자유롭게 사용할 수 있습니다. 형식 자체에는 크기 제한이 없지만, OpenAI Codex는 기본값인 32 KiB의 project_doc_max_bytes에 도달하면 읽기를 중단합니다.

# Acme web app

Customer-facing web app with an admin area and a REST API.

## Commands

- Install: `pnpm install`
- Test: `pnpm test`
- Lint and type-check: `pnpm lint && pnpm tsc --noEmit`

## Code style

- TypeScript strict mode; no `any` in new code.
- Keep database access in `src/db/`.

## Never

- Never commit secrets or .env files.
- Never edit files under `src/generated/` by hand.

우선순위 및 병합

편집 중인 파일과 가장 가까운 AGENTS.md가 우선하며, 채팅에서 명시한 지침은 모든 파일보다 우선합니다. OpenAI Codex는 프로젝트 루트부터 작업 디렉터리까지 각 디렉터리에서 파일 하나씩을 이어 붙이므로, 가까운 파일이 뒤에 와서 우선 적용됩니다. CLAUDE.md가 있으면 Claude Code는 기본적으로 AGENTS.md를 무시합니다.

이 파일을 읽는 도구

팁

• 기존 AGENT.md의 이름을 바꾸나요? agents.md에서는 두 이름을 모두 사용할 수 있도록 mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md를 제안합니다.
• 테스트 및 린트 명령을 적어 두세요. 에이전트는 명령을 찾아 실행하고, 완료 전에 실패를 수정하려고 합니다.
• 모노레포에서는 루트 파일 하나를 길게 늘리는 대신 패키지마다 짧은 AGENTS.md를 추가하세요.
• OpenAI Codex에서는 같은 디렉터리의 AGENTS.override.md가 AGENTS.md보다 우선합니다.

기타 지침 파일