AGENTS.md란 무엇이며 30분 만에 직접 작성하는 방법

바이브 코딩과 에이전트 활용에 관한 실용 자료: Ailoot 문서.

AGENTS.md 한 문단 요약#

아래에서는 agents.md, OpenAI Codex 문서, JetBrains Junie, Cursor Rules 문서, GitHub Copilot Coding Agent 변경 기록, Agentic AI Foundation에 관한 Linux Foundation 보도자료를 바탕으로 이 형식을 살펴봅니다. 모든 수치와 기능은 2026년 5월 30일 기준이며, Claude Code의 AGENTS.md 지원은 2026년 9월 24일에 갱신된 Anthropic 문서에 따라 설명합니다.

현재 시장에 있는 이 도구들의 세계가 무엇인지, 왜 공통 파일이 필요한지 전혀 모르겠다면 먼저 「2026년에 무엇으로 코딩할까: Claude Code부터 Antigravity까지 AI 도구 8가지」 가이드를 읽어 보세요. 이 글은 AGENTS.md 형식과 30분 만에 직접 작성하는 방법에 초점을 맞춥니다.

AGENTS.md란 무엇이며 어디서 시작되었나?#

이전에는 AI 도구마다 자체 규칙 파일이 있었습니다. Anthropic은 CLAUDE.md, Cursor는 .cursorrules, GitHub은 .github/copilot-instructions.md, Aider는 .aider.conf.yml, JetBrains는 .junie/guidelines.md를 사용했습니다. 팀에 서로 다른 에이전트가 세 개 있었다면, 같은 내용이 담긴 파일 세 개가 병렬로 존재했고 일주일도 안 되어 서로 달라지곤 했습니다.

OpenAI가 가장 먼저 이런 상황에 지쳤습니다. 2025년 8월 Codex CLI를 공개하면서 동시에 agents.md를 개방형 형식으로 출시했습니다. 사이트의 설명은 다음과 같습니다.

“AGENTS.md를 에이전트를 위한 README라고 생각해 보세요.”

(agents.md, 영어에서 번역)

핵심은 AGENTS.md가 README를 보완한다는 점입니다. README는 사람을 위해 작성합니다. “프로젝트가 무엇인지, 로컬에서 어떻게 실행하는지, 어떻게 기여하는지”를 설명합니다. AGENTS.md는 에이전트를 위해 작성합니다. 정확한 셸 명령, 검증 가능한 완료 기준, “이것은 절대 건드리지 말 것” 같은 경계를 담습니다.

사이트의 설명은 다음과 같습니다.

“AGENTS.md는 README를 보완합니다. 에이전트에 필요한 추가적이고 때로는 세부적인 맥락, 즉 빌드 단계, 테스트, 관례를 담습니다. 이런 내용은 README를 복잡하게 만들거나 사람 기여자에게는 필요하지 않을 수 있습니다.”

(agents.md, 영어에서 번역)

2025년 9월에는 GitHub Copilot Coding Agent가 이 형식을 지원했습니다(변경 기록, 28.08.2025). 12월에는 Cursor, Junie, Gemini CLI, Aider와 그 밖의 도구 12개가 합류했습니다. 2025년 12월 9일 Linux Foundation은 Agentic AI Foundation (AAIF)을 설립했습니다. 창립 프로젝트 3개는 OpenAI의 AGENTS.md, Anthropic의 MCP, Block의 goose였습니다. 창립 회원은 AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft, OpenAI였습니다. 2026년 2월 24일에는 Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath, Hitachi 등을 포함해 재단에 이미 146개 조직이 참여하고 있었습니다.

그때부터 AGENTS.md는 “OpenAI가 만든 또 하나의 것”이 아니라 사실상의 표준이 되었습니다.

어떤 AI 에이전트가 AGENTS.md를 읽고, 어떤 에이전트는 읽지 않나?#

지원 표는 2026년 5월 30일 기준이며, Claude Code 행은 2026년 9월 24일에 갱신했습니다.

Anthropic은 주요 업체 가운데 가장 늦게 합류했습니다. 2025년 8월, 공식 anthropics/claude-code 저장소에 AGENTS.md 지원을 요청하는 issue #6235가 열렸습니다.

이 이슈는 거의 1년 동안 열려 있다가 2026년 8월 17일에 닫혔고, AGENTS.md를 지원하는 버전 2.1.277은 9월 18일에 출시되었습니다. Anthropic의 작동 방식은 다음과 같습니다. CLAUDE.md가 우선하며, 작업 폴더나 상위 폴더 어디에도 CLAUDE.md가 없을 때 AGENTS.md를 읽습니다. 문서에 따르면 다음과 같이 작동합니다.

주의할 점은 개인용 CLAUDE.local.md도 해당하며, 이 파일이 있으면 Claude Code는 AGENTS.md 읽기를 중단합니다. /config의 Project instructions에서 이 동작을 바꿀 수 있습니다. 예를 들어 Claude Code가 두 파일을 동시에 읽게 할 수 있습니다. 2.1.277보다 이전 버전에서는 AGENTS.md를 자동으로 읽지 않으므로 CLAUDE.md의 @AGENTS.md 행이 여전히 우회 방법입니다.

AGENTS.md는 CLAUDE.md 및 .cursorrules와 어떻게 다른가?#

2026년 5월 30일 기준 네 가지 형식의 비교:

AGENTS.md에는 공통 프로젝트 지침을 둘 수 있지만 클라이언트별 로드 경로와 개인 설정은 별도로 구성해야 합니다. Claude Code에는 이를 위한 CLAUDE.local.md가 있고, Cursor에는 사용자별 로컬 .mdc 파일이 있습니다. AGENTS.md만으로는 이를 제공하지 않습니다. 다른 파일과 결합하거나 gitignore 대상 섹션에 개인 규칙을 작성하기로 팀에서 합의해야 합니다.

또 다른 중요한 세부 사항은 모노레포입니다. Codex와 Cursor는 “가장 가까운 AGENTS.md가 우선”이라는 규칙을 적용합니다.

“모노레포에서는 각 패키지 안에 별도의 AGENTS.md를 두세요. 에이전트는 디렉터리 트리에서 가장 가까운 파일을 자동으로 읽으며, 가장 가까운 파일이 우선합니다.”

(agents.md, 영어에서 번역)

agents.md에 따르면 OpenAI의 주요 모노레포에는 여러 하위 패키지를 위한 AGENTS.md 파일 88개가 있습니다. 모노레포에서 작업한다면 규칙을 여러 계층에 배치하세요. 일반 규칙은 루트에, 구체적인 규칙은 하위 폴더에 둡니다.

좋은 AGENTS.md에는 무엇이 들어가야 하나?#

agents.md 사이트는 “어떤 Markdown이든” 쓸 수 있는 유연한 형식을 제안합니다. 하지만 실제로 좋은 파일의 80%는 같은 8개 섹션을 담고 있습니다. 핵심 규칙은 모든 항목이 정확한 명령이나 구체적인 예시여야 한다는 것입니다. “깔끔한 코드를 작성하라” 같은 추상적인 생각은 에이전트가 무시합니다.

1. 프로젝트 개요 — 2–3줄. 프로젝트가 무엇인지, 누구를 위한 것인지, 주된 목표가 무엇인지 적습니다. 홍보 문구는 넣지 않습니다. 예시: “유료 워크숍 온보딩용 Telegram 봇. 기술 스택: Next.js 14, Prisma, PostgreSQL. purchases에 새 레코드가 생기면 실행됩니다.”
2. 설정 명령 — 로컬에서 실행할 정확한 셸 명령입니다. npm install, npm run dev, npm run build처럼 씁니다. “보통은 이렇게 합니다” 같은 문장은 쓰지 않습니다.
3. 코드 스타일 / 규칙 — “깔끔하게 작성하라”가 아니라 예시를 포함한 구체적인 규칙입니다. 예를 들어 “TypeScript strict, 작은따옴표, 기본 내보내기 금지, 컴포넌트 이름은 PascalCase, 훅 이름은 use로 시작.”
4. 개발 환경 팁 — 중요한 항목이 어디 있는지 설명합니다. .env에 필요한 변수, 비밀 정보 저장 위치, 사용 중인 포트, 로컬 DB 사용 방법을 적습니다.
5. 테스트 지침 — 특정 테스트를 실행하는 방법과 “통과”의 기준을 적습니다. 예를 들어 npm test -- --testPathPattern=user-auth; 테스트 100% 통과가 기대됩니다.
6. PR / 커밋 지침 — 커밋 메시지 형식, PR 전 확인 목록(테스트, 린터, 문서), 승인 담당자를 적습니다.
7. 보안 고려 사항 — 절대 해서는 안 되는 일을 적습니다. “.env를 커밋하지 마세요. 비밀 정보는 Vault에만 보관하세요. 사용자의 개인 정보를 로그에 표시하지 마세요.”
8. 경계 / 절대 하지 말아야 할 일 — 대안을 함께 적은 금지 사항입니다. “main에서 git push --force를 사용하지 마세요. 되돌려야 한다면 feature branch에서 git revert 또는 git reset을 사용하세요.”

각 섹션에서 “생각 대신 명령” 원칙을 따르세요. 에이전트는 “마이그레이션에 주의하세요”를 무시합니다. 하지만 “alembic upgrade head 전에 alembic check를 실행하세요. 오류가 나오면 마이그레이션을 적용하지 말고 저에게 물어보세요”는 따릅니다.

바로 사용할 수 있는 AGENTS.md 템플릿 (복사해 수정)#

# AGENTS.md

## Project overview

<project-name> - <one phrase describing its purpose>.
Stack: <Next.js / Python / Go / ...>.
Main entities: <users, orders, posts ...>.
Details for people are in README.md.

## Setup commands

```bash
# first install
npm install
cp .env.example .env  # then fill in manually; see list below

# run
npm run dev           # dev server on :3000
npm run build         # production build
npm run start         # run production build
```

## Dev environment

- Node 20+ (via nvm: `nvm use 20`)
- PostgreSQL 16 locally on :5432 (`docker-compose up postgres`)
- Redis is optional, needed only for queues (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Never read the entire `.env` file. If you need one variable: `grep "^VAR=" .env`

## Code style

- TypeScript strict mode
- Single quotes, no semicolons (unless ESLint requires them)
- Imports: external first, then internal via `@/`, then relative
- Components in PascalCase; hooks start with `use`
- No `any` without an explicit comment explaining “why it can’t be typed”

Example of a good module:

```ts
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function parseUser(raw: unknown) {
  return UserSchema.parse(raw)
}
```

## Testing

```bash
npm test                                # all tests
npm test -- --testPathPattern=auth      # auth only
npm test -- --watch                     # watch mode
```

All tests must pass (be green) before committing. If a test is red, don’t commit; ask me what to do.

## Pull request guidelines

- Commit format: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- Before PR: `npm run build && npm test && npm run lint`
- PR description = what changes, why, and how to test
- Don’t approve your own PR—always wait for human review

## Security

- Secrets only in `.env` and Vault, never in code
- Don’t log personal data (email, phone, name)
- When working with the production DB, use read-only queries only unless explicitly authorized
- Don’t hardcode external service API keys (Stripe, OpenAI) in tests

## Never do this

- Don’t `git push --force` to main. If you need to roll back, use `git revert` or open a new PR
- Don’t run DB migrations without `alembic check` (or the equivalent in your ORM)
- Don’t use `npm install -g` or `sudo` for project dependencies
- Don’t add dependencies without approval (especially heavy ones: webpack plugins, ORM)

템플릿은 평균 80–120줄입니다. 파일이 150줄을 넘으면 구조를 다시 정리하라는 신호입니다. 내용을 docs/로 옮기거나 링크를 추가하거나 한 줄로 압축하세요. 실제로는 100–150줄 파일이 가장 효과적이며, 그보다 길어지면 품질 향상이 반전되기 시작합니다.

AGENTS.md를 정말 유용하게 만드는 5가지 규칙은 무엇인가?#

1. 생각 대신 명령. 에이전트는 “마이그레이션에 주의하라”는 말을 이해하지 못합니다. alembic upgrade head 전에 alembic check를 실행하라는 지침은 따릅니다. 에이전트는 기분이 아니라 명령과 조건에 따라 작동합니다. 핵심 규칙은 모두 “X를 하라. 그렇지 않으면 Y를 하라”로 표현하세요.

2. 대안이 있는 금지 사항. “강제 푸시하지 마라”만 적으면 에이전트는 프롬프트 두세 개를 받은 뒤 이를 조용히 무시합니다. “X를 하지 말고 Y를 하라”라는 조합이 효과적입니다. 예: “main에서 git push --force를 사용하지 마세요. 되돌려야 한다면 git revert를 사용하거나 새 PR을 여세요.”

3. 단일 진실 공급원. 루트의 AGENTS.md가 프로젝트 전체의 기준 파일입니다. 모노레포라면 “가장 가까운 파일 우선” 규칙에 따라 하위 폴더에 중첩 AGENTS.md 파일을 두세요. 서로 충돌하는 지침이 담긴 병렬 파일은 만들지 마세요.

4. 검증 가능한 완료 기준. “테스트를 통과해야 한다”는 말은 쓸모가 없습니다. 정확한 기준은 npm test의 종료 코드가 0이고 stdout에 FAIL이 출력되지 않는 것입니다. “코드가 깔끔해야 한다” 역시 쓸모가 없습니다. 정확한 기준은 npm run lint가 경고 없이 통과하는 것입니다. 완료 조건을 명시해야 에이전트가 “완료”의 의미를 이해합니다.

5. 150줄 미만의 파일. 150줄을 넘으면 에이전트가 파일을 읽는 데 더 많은 컨텍스트를 쓰고 중요한 규칙을 놓치면서 지표가 나빠지기 시작합니다. 내용이 들어가지 않으면 세부 사항을 docs/architecture.md로 옮기고 AGENTS.md에서 연결하세요. 파일에는 명령과 경계만 남기면 됩니다.

AGENTS.md를 엉망으로 만드는 10가지 실수는 무엇인가?#

1. 명령 없는 모호한 규칙. 에이전트는 “마이그레이션에 주의하라”를 무시합니다. 에이전트에게 그 문장은 아무 의미도 없습니다. 조건이 포함된 구체적인 명령만 효과가 있습니다. “alembic upgrade head 전에 alembic check를 실행하세요. 오류가 있으면 마이그레이션을 적용하지 말고 저에게 물어보세요.”

2. “깔끔한 코드.” 쓸모없는 문구입니다. 구체적인 패턴으로 바꾸세요. “훅을 사용하는 함수형 컴포넌트를 쓰세요. 예: function LoginForm() { const [email, setEmail] = useState(''); ... }”

3. 구조 없는 산문. AGENTS.md가 제목 없는 산문 300줄로 되어 있으면 에이전트는 관련 없는 부분에 80K 컨텍스트 토큰을 쓰고 중요한 내용을 놓칩니다. H2/H3 제목, 짧은 섹션, 글머리표를 사용하세요.

4. 150줄이 넘는 파일. 이 기준을 넘으면 품질 지표가 떨어집니다. 주 파일 하나와 docs/의 세부 문서 링크로 나누세요.

5. 대안 없는 금지 사항 30개 이상. 파일에 “X를 하지 마라, Y를 하지 마라”라는 긴 목록만 있고 “대신 Z를 하라”는 설명이 없으면 에이전트는 방향을 잡지 못합니다.

6. README.md 중복. README에 이미 “설치와 실행 방법”을 썼다면 AGENTS.md에 복사하지 마세요. 대신 한 줄로 README를 참조하고, 사람이 아닌 에이전트에게 필요한 내용을 AGENTS.md에 적으세요.

7. 비밀 정보를 하드코딩하기. AGENTS.md는 git에 들어가므로 공개될 수 있습니다. 실제 API 키, 토큰, 비밀번호를 넣지 마세요. 비밀 정보 저장소만 참조하세요. “Vault 참조: secret/staging/db.”

8. 순위를 정하지 않은 충돌 우선순위. “빠르게 진행하라”와 “테스트 커버리지를 90% 유지하라”는 지침만 있으면 에이전트는 무엇을 선택해야 할지 모릅니다. 우선순위를 명시하세요. “테스트 커버리지 ≥80%를 우선하고, 그다음 속도를 고려하세요. 서로 충돌하면 테스트가 우선입니다.”

9. 오래된 문서. 현실은 이미 WebSocket인데 아키텍처 설명에는 REST + polling이라고 적혀 있는 경우입니다. 에이전트는 오래된 설명을 따르다가 아키텍처를 망가뜨립니다. 규칙: 아키텍처가 바뀌면 같은 PR에서 AGENTS.md도 갱신하세요.

10. 간단한 작업에 과도한 아키텍처 설명을 요구하기. 누군가 설정에서 두 줄을 바꿔 달라고 했는데 에이전트가 마이크로서비스 14개의 전체 구성을 읽어야 해서는 안 됩니다. “심층” 아키텍처는 docs/architecture.md로 옮기고, AGENTS.md에는 “작업이 아키텍처와 관련되면 docs/architecture.md를 읽으세요”만 남기세요.

2,500개가 넘는 AGENTS.md 저장소에 관한 GitHub Blog의 연구는 핵심 결론을 이렇게 밝힙니다.

“대부분의 에이전트 파일은 너무 일반적이어서 실패합니다. ‘당신은 유용한 코딩 도우미입니다’라는 말은 효과가 없습니다.”

(GitHub Blog, 영어에서 번역)

하나의 저장소에서 AGENTS.md와 CLAUDE.md를 함께 유지하는 방법#

두 파일의 내용을 중복하지 않으면서 함께 사용하는 방법이 가장 실용적인 질문입니다. 세 가지 시나리오가 있습니다.

시나리오 1: Claude Code만 사용. CLAUDE.md를 유지하고 Claude Code의 모든 기능을 사용합니다. 사용자 수준 지침은 ~/.claude/CLAUDE.md, 프로젝트 지침은 CLAUDE.md, 개인 설정은 CLAUDE.local.md, 다른 파일 포함은 @import, 전문화된 skill은 .claude/skills/를 사용하세요. AGENTS.md는 필요 없습니다.

시나리오 2: 여러 코딩 클라이언트 사용. 공통 규칙은 AGENTS.md에 두고 클라이언트별로 연결하고 검증하세요. Gemini CLI는 컨텍스트 파일명을 설정할 수 있고 Aider는 read 설정으로 파일을 불러올 수 있습니다. 이는 명시적인 로드 경로이며 같은 자동 탐색 기능이 아닙니다.

안전한 테스트 저장소에서 새 세션을 열고 “테스트 응답에 instructions-loaded 표시를 포함하세요” 같은 고유하고 무해한 지침을 넣으세요. 응답과 함께 클라이언트가 공식적으로 제공하는 로드된 파일 보기나 로그도 확인하세요. 실제로 사용하는 클라이언트와 버전마다 반복해야 합니다. 모델이 파일을 읽었다고 말하는 것만으로는 독립적인 증거가 되지 않으며, 한 번 성공했다고 다른 모든 도구의 지원을 입증한 것은 아닙니다.

시나리오 3: 혼합 팀 (Claude Code + 다른 도구). 2026년에 가장 흔한 구성입니다. AGENTS.md를 기본 파일로 두는 것이 해결책입니다. Claude Code 전용 규칙이 없다면 CLAUDE.md를 만들지 마세요. 2.1.277 버전부터 프로젝트에 CLAUDE.md가 없으면 Claude Code가 AGENTS.md를 읽습니다. 별도 규칙이 있다면 CLAUDE.md를 심볼릭 링크로 만들거나 @AGENTS.md 가져오기를 포함한 짧은 래퍼로 만드세요.

변경 전에 두 파일을 확인하고 백업하세요. 둘 다 있다면 충돌하지 않는 공통 지침은 AGENTS.md에 병합하고 Claude 전용 지침은 @AGENTS.md 가져오기와 함께 CLAUDE.md에 유지하세요. 기존 심볼릭 링크를 교체하지 말고 보존하세요.

AGENTS.md가 없고 CLAUDE.md가 일반 파일일 때만 다음 macOS/Linux 셸 보호문을 사용하세요. 기존 대상이나 심볼릭 링크를 덮어쓰지 않습니다.

if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2
elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
else
  printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2
fi

이름 변경이 성공하면 CLAUDE.md는 AGENTS.md를 가리키는 심볼릭 링크입니다. AGENTS.md를 읽는 모든 에이전트가 같은 내용을 봅니다. CLAUDE.md를 읽는 Claude Code도 심볼릭 링크를 통해 동일한 내용을 봅니다.

Windows에서 심볼릭 링크를 만들려면 Developer Mode(또는 관리자 권한)가 필요하며, 팀 전체가 사용하기에는 번거로울 수 있습니다. 대신 AGENTS.md를 가져오는 짧은 CLAUDE.md를 만들 수 있습니다.

# CLAUDE.md

@AGENTS.md

## Claude Code specific

- Use .claude/skills/ for specialized prompts
- When working with Skills, consult .claude/skills/INDEX.md
- Use Plan Mode before major changes (Shift+Tab)

Claude Code에서는 이 구문 한 줄로 AGENTS.md를 포함하고 그 아래에 Claude Code 전용 내용을 추가합니다. 나중에 AGENTS.md를 제거하고 싶다면 가져오기 행만 삭제하면 됩니다. 이 행 때문에 같은 파일을 두 번 읽지는 않습니다. Claude Code 문서에 따르면 Claude Code가 AGENTS.md를 자체적으로 읽을 수 있더라도 중복해서 불러오지 않습니다.

2026년 여러 도구를 사용하는 팀의 표준 구성:

repo-root/
├── AGENTS.md                              # 기준 파일, ≤150줄
├── CLAUDE.md                              # Claude 전용 규칙이 있을 때만: AGENTS.md로 가는 심볼릭 링크 또는 @AGENTS.md + 추가 내용
├── .cursor/rules/                         # Cursor 전용 대상별 재정의
├── .github/copilot-instructions.md        # 사용하는 경우 “AGENTS.md 참조”
└── docs/architecture.md                   # AGENTS.md가 참조하는 상세 아키텍처

CLAUDE.md에 관한 자세한 내용은 “CLAUDE.md를 올바르게 구성하는 방법” 가이드에서 확인할 수 있습니다. 에이전트에게 긴 지침 파일이 필요한 이유를 알고 싶다면 “컨텍스트 엔지니어링이란 무엇인가”를 읽어 보세요.

2026년에 무엇이 바뀌었나: AAIF는 왜 AGENTS.md를 Linux Foundation으로 가져왔나?#

2026년 5월 AI 코딩 분야에서 중요한 정치적 변화는 새로운 모델 출시가 아니라 형식의 통합이었습니다. 이전에는 업체마다 자체 규칙 파일이 있었습니다. 여러 도구를 쓰는 팀에는 불편했지만 업체에는 편리한 방식이었습니다.

2025년 12월 9일자 보도자료에서 Linux Foundation은 세 형식의 기반이 될 Agentic AI Foundation을 발표했습니다.

• OpenAI의 AGENTS.md — 에이전트용 지침 파일 형식
• Anthropic의 Model Context Protocol (MCP) — 외부 도구를 에이전트에 연결하는 프로토콜
• Block의 goose — 오픈 소스 에이전트 프레임워크

Linux Foundation 보도자료에서 인용:

“이 프로젝트들을 AAIF의 틀 아래 모으면 개방형 거버넌스만이 제공할 수 있는 투명성과 안정성을 바탕으로 발전할 수 있습니다.”

(Linux Foundation 보도자료, 2025년 12월 9일, 영어에서 번역)

2026년 2월 24일까지 146개 조직이 AAIF에 속해 있었습니다(두 달 동안 신규 회원 97개). 새 Gold 회원에는 Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express, Autodesk가 포함되었습니다. Anthropic은 MCP를 추진하는 Platinum 회원입니다. OpenAI는 AGENTS.md를 추진하는 Platinum 회원입니다. Block은 goose의 Platinum 회원입니다.

이로써 AGENTS.md의 위상이 바뀝니다. “OpenAI 형식”에서 업계 표준으로 바뀌는 것입니다. 2026년 봄까지 Claude Code는 아직 이 흐름에 참여하지 않았지만, 9월 버전 2.1.277부터 AGENTS.md를 자체적으로 읽게 되었습니다. CLAUDE.md는 사라지지 않았으며 프로젝트에 있으면 여전히 기본적으로 우선합니다.

공통 프로젝트 규칙을 AGENTS.md에 두고 사용하는 각 클라이언트가 요구하는 가져오기, 래퍼 또는 명시적 read 설정을 함께 쓰는 것이 출발점입니다. Claude Code는 설치 버전과 지침 파일 우선순위를 확인한 뒤 CLAUDE.md 가져오기나 심볼릭 링크가 필요한지 판단하세요. 클라이언트마다 로드를 검증해야 하며 여기서 지원 비율은 입증하지 않았습니다.

다음은 무엇인가?#

AGENTS.md는 “에이전트가 예측 가능하게 작동하도록 합의하는 방법”의 첫 번째 구성 요소입니다. 다음은 프로젝트 지식 폴더입니다. 여기에는 비즈니스 맥락, 대상 고객, 제품, 가격이 담깁니다. 세 번째 구성 요소는 컨텍스트 엔지니어링으로, 모든 것을 연결합니다. 에이전트가 단계마다 어떤 파일을 보는지, 세션 사이에 상태를 어떻게 보존하는지, 서로 다른 모델 사이를 어떻게 전환하는지 다룹니다.

실용 자료: Ailoot 문서.

더 많은 자료와 도구: Ailoot.