AGENTS.md 가이드: AI 코딩 에이전트를 위한 범용 구성 파일

어제 엔터프라이즈 팀을 위한 CLAUDE.md 가이드를 게시했습니다. 몇 시간 안에 세 명이 같은 질문을 했습니다: “Claude Code에 올인하지 않은 팀은요?”

타당한 지적입니다. 조직이 일부 팀은 GitHub Copilot을, 다른 팀은 Cursor를, 백그라운드 작업에는 Codex를, 복잡한 리팩터링에는 Claude Code를 사용한다면 — 그리고 이것은 점점 흔해지고 있습니다 — 어디서든 작동하는 무언가가 필요합니다.

그게 AGENTS.md입니다.

AGENTS.md가 무엇인지 (그리고 아닌지)

AGENTS.md는 AI 코딭 에이전트에게 코드베이스에서 어떻게 작업할지 알려주는 벤더 중립 마크다운 파일입니다. 저장소 루트(또는 범위가 지정된 규칙을 위해 하위 디렉터리)에 위치하며, 첫날 신규 개발자에게 줄 것과 같은 종류의 정보를 포함합니다: 빌드 명령, 테스트 프로토콜, 코딩 규칙, 프로젝트 아키텍처, 그리고 명시적 경계.

README.md와의 핵심 차이: 사람이 아닌 기계를 위해 구조화되어 있습니다. README가 “React와 TypeScript를 사용합니다"라고 말할 수 있지만, AGENTS.md는 이렇게 말합니다:

## Tech Stack
- React 18.3, TypeScript 5.4, Vite 5.2, Tailwind CSS 3.4

정확한 버전. 서술 없음. 에이전트는 프로젝트의 유래담이 필요 없습니다.

이 형식은 실용적인 문제에서 나왔습니다. AGENTS.md 이전에 모든 에이전트는 자체 구성 파일을 가졌습니다 — Aider는 CONVENTIONS.md를, Roo Code는 .roomodes 파일을, Cline은 .clinerules 디렉터리를, Claude Code는 CLAUDE.md를 사용했습니다. 여러 에이전트를 운영하는 팀은 중복되고 분기된 구성을 유지했습니다. AGENTS.md는 이제 60,000개 이상의 오픈소스 프로젝트가 채택한 단일 진실 소스로 이를 통합합니다.

엔터프라이즈 팀이 왜 관심을 가져야 하는가

숫자가 말해줍니다. GitHub는 2,500개 이상의 저장소를 분석했고, 적절한 가이드가 있을 때 에이전트 성공률이 극적으로 상승함을 발견했습니다:

• AGENTS.md 없음 — 40-60% 작업 성공률
• 최소한의 AGENTS.md — 60-70% 성공률
• 포괄적인 AGENTS.md — 85-90% 성공률

아침마다 다섯 개의 에이전트 작업을 큐에 넣는 엔터프라이즈 팀(WorkOS 팀이 Codex로 개척한 패턴)에게, 이는 하루 두 번 실패와 제로 실패의 차이입니다. 조직 전체에 걸쳐 곱해보면 ROI는 자명합니다.

하지만 진정한 엔터프라이즈 가치는 단순히 성공률이 아닙니다. 도구 간 표준화입니다. 프론트엔드 팀은 Cursor를, 플랫폼 팀은 Claude Code를, DevOps 팀은 Codex를 실험할 때, 단일 AGENTS.md가 모두 동일한 규칙을 따르게 합니다. 한 번 작성하면, 모든 에이전트가 읽습니다.

주요 에이전트별 AGENTS.md 활용 방식

모든 에이전트가 AGENTS.md를 동일하게 소비하지는 않습니다. 차이를 이해하면 어디서든 잘 작동하는 파일을 작성하는 데 도움이 됩니다.

GitHub Copilot

Copilot은 워크스페이스 루트와 하위 디렉터리에서 AGENTS.md를 자동 발견합니다. GitHub 팀은 Copilot이 형식을 해석하는 방식을 개선하기 위해 2,500개 이상의 저장소를 구체적으로 분석했습니다. Copilot은 또한 .agent.md 파일도 지원합니다 — 특정 도구와 역할을 가진 커스텀 에이전트 페르소나를 정의하기 위해 YAML 프론트매터를 사용하는 별도 형식입니다.

Cursor

Cursor는 AGENTS.md를 자동 발견하여 지침 시스템에 주입합니다. 구성이 필요 없습니다 — 저장소에 파일을 드롭하면 Cursor가 가져갑니다. 단순하고 효과적입니다.

Windsurf

Windsurf가 가장 정교한 통합을 갖습니다. AGENTS.md를 자동 스코핑을 갖춘 Rules 엔진의 일부로 취급합니다: 루트 파일은 항상 활성화되는 글로벌 규칙이 되는 반면, 하위 디렉터리 파일은 위치를 기반으로 glob 패턴을 자동 적용합니다. Windsurf는 전체 워크스페이스의 모든 AGENTS.md 파일을 스캔합니다.

Claude Code

Claude Code는 네이티브 CLAUDE.md 형식과 함께 AGENTS.md를 지원합니다. 두 가지는 상호 보완적입니다 — 범용 규칙은 AGENTS.md, 자동 메모리, MCP 서버 선언, 그리고 The Anatomy of a Claude Code Project에서 다룬 3계층 아키텍처 같은 Claude 전용 기능은 CLAUDE.md.

OpenAI Codex

Codex는 시작 시 AGENTS.md를 자동 발견하여 로드하고, 작업 실행 중에 명령을 자주 참조합니다. WorkOS 사례 연구가 빛을 발하는 부분입니다 — 그들의 팀은 매일 아침 Codex에 4-5개의 유지보수 작업(TypeScript 수정, 웹훅 업데이트, 인증 마이그레이션)을 큐에 넣고, 잘 정의된 작업에서 85-90% 성공률을 보고합니다.

Aider

Aider는 이미 --conventions-file을 통해 규칙 파일을 지원했습니다. AGENTS.md가 표준 기본 위치가 되었고, 기존 CONVENTIONS.md 파일은 하위 호환성을 위해 계속 작동합니다.

기타

Roo Code, Google Jules, Factory.ai Droids, Zed 모두 다양한 수준의 정교함으로 AGENTS.md를 지원합니다. Factory.ai는 디렉터리에 걸친 포괄적인 발견과 함께 이를 주요 브리핑 메커니즘으로 사용합니다. 추세는 명확합니다: AGENTS.md가 테이블 스테이크스(기본 요건)가 되어가고 있습니다.

모든 AGENTS.md에 필요한 6가지

GitHub의 2,500개 이상 저장소 분석은 가장 큰 차이를 만드는 여섯 가지 핵심 영역을 식별했습니다:

1. 실행 가능한 명령

이것들을 먼저 넣으세요. 에이전트는 끊임없이 찾아 사용합니다.

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test all: `pnpm test`
- Test single: `pnpm test -- --grep "test name"`
- Build: `pnpm build`
- Lint: `pnpm lint --fix`

2. 테스트 지침

테스트를 실행하는 방법만이 아니라 작성하는 방법도. 어떤 프레임워크, 어떤 패턴, 어디에 위치하는지.

## Testing
- Framework: Vitest with React Testing Library
- Location: `__tests__/` directories adjacent to source
- Pattern: one test file per component, named `ComponentName.test.tsx`
- Run single file: `pnpm test src/components/__tests__/Button.test.tsx`

3. 프로젝트 아키텍처

간단한 주석이 포함된 파일 구조. 에이전트는 이를 사용하여 낯선 코드베이스를 탐색합니다.

## Architecture
- `src/api/` — .NET 8 Web API (Clean Architecture)
- `src/web/` — React 18 + TypeScript frontend
- `src/shared/` — Shared types and utilities
- `infra/` — Terraform modules and Bicep templates
- `scripts/` — CI/CD and automation scripts

4. 코드 스타일 (예시 포함)

추상적 규칙은 전달되지 않습니다. 구체적 예시가 전달됩니다.

## Code Style
- Use functional components with hooks (no class components)
- Prefer named exports over default exports
- Example:
  ```tsx
  export function UserCard({ name, role }: UserCardProps) {
    const [expanded, setExpanded] = useState(false);
    return (
      <Card onClick={() => setExpanded(!expanded)}>
        <h3>{name}</h3>
        {expanded && <p>{role}</p>}
      </Card>
    );
  }
  ```

5. Git 워크플로

커밋 표준, 브랜치 규칙, PR 요구 사항.

## Git Conventions
- Commit format: `type(scope): description` (conventional commits)
- Branch naming: `feature/JIRA-123-brief-description`
- PRs require passing tests and lint checks

6. 명시적 경계

3단계 제약 구조는 엔터프라이즈 팀에게 결정적입니다:

## Boundaries
**Always do:**
- Include unit tests for new functions
- Run lint before committing
- Use environment variables for configuration

**Ask first:**
- Database schema changes
- Adding new dependencies
- Modifying CI/CD pipelines
- Changes to authentication or authorization logic

**Never do:**
- Commit secrets, API keys, or connection strings
- Modify files in `vendor/` or `node_modules/`
- Edit generated migration files
- Push directly to main branch
- Modify `.env.production`

모노레포 패턴

이것이 엔터프라이즈 팀을 위해 AGENTS.md가 흥미로워지는 부분입니다. 형식은 계층적 중첩을 지원합니다 — 하위 디렉터리 파일이 부모 파일을 상속하고 재정의하며, 가장 가까운 파일이 우선합니다.

/AGENTS.md                          ← Global: security rules, commit conventions
/frontend/AGENTS.md                 ← React patterns, CSS conventions, component rules
/frontend/components/AGENTS.md      ← Component library specifics
/backend/AGENTS.md                  ← API patterns, database rules, service conventions
/infra/AGENTS.md                    ← Terraform/Bicep rules, naming conventions

OpenAI는 저장소 전체에 약 88개의 중첩된 AGENTS.md 파일을 유지합니다. 과도한 것이 아니라 — 정밀한 것입니다. 각 팀이 자신의 하위 디렉터리 에이전트 가이드를 소유하고, 글로벌 규칙이 루트에서 아래로 전파됩니다.

엔터프라이즈 팀에게 이는 팀 소유권에 자연스럽게 매핑됩니다. 플랫폼 팀이 루트 수준 규칙을 소유합니다. 프론트엔드, 백엔드, 인프라 팀이 각자의 하위 디렉터리 파일을 소유합니다. 변경은 코드처럼 풀 리퀘스트를 거칩니다.

AGENTS.md, CLAUDE.md, SKILL.md — 어떻게 결합되는가

Claude Code를 사용 중이라면(CLAUDE.md 가이드를 읽으셨다면 아마 그럴 것입니다), 이 파일들이 어떻게 관련되는지 궁금할 수 있습니다. 멘탈 모델은 이렇습니다:

• AGENTS.md — “이 코드베이스에서 어떻게 작업할 것인가.” 벤더 중립. 모든 에이전트가 읽음. 명령, 아키텍처, 규칙, 경계를 포함.

• CLAUDE.md — “Claude가 구체적으로 여기서 어떻게 작업해야 하는가.” Claude Code 전용. 자동 메모리, MCP 서버 선언, 훅 구성, Claude 특정 최적화를 추가.

• SKILL.md — “이 범주의 작업을 어떻게 수행하는가.” 재사용 가능한 전문성 패키지 — 코드베이스 특정이 아니라 작업 특정. 스킬 생성 워크플로는 Claude Code와 Gemini CLI 스킬 도구에 대한 글에서 다루었습니다.

스택으로 생각하세요:

• 시스템 프롬프트 — 모델 기준선 (통제 불가)
• AGENTS.md — 코드베이스 컨텍스트 (범용)
• SKILL.md — 작업 전문성 (온디맨드)
• CLAUDE.md / .agent.md — 에이전트별 구성 (도구별)
• MCP 서버 — 외부 시스템 접근 (라이브 데이터)

멀티 에이전트 팀을 위해, AGENTS.md에 가장 많은 노력을 투자하세요. 가장 넓은 도달 범위를 갖습니다. 그 다음 에이전트별 최적화를 위해 CLAUDE.md 또는 .agent.md 파일을 추가하세요.

엔터프라이즈 스타터 템플릿

엔터프라이즈 팀을 위한 복사-붙여넣기 준비된 템플릿입니다. 세부 사항은 커스터마이즈하고, 구조는 유지하세요:

# AGENTS.md

## Project Overview
[One sentence: what this system does and who it serves]

## Tech Stack
- [Language] [version], [Framework] [version], [Build tool] [version]
- Database: [system] [version]
- Infrastructure: [platform] (Terraform/Bicep/CDK)
- CI/CD: [platform]

## Commands
- Install: `[command]`
- Dev: `[command]`
- Build: `[command]`
- Test all: `[command]`
- Test single: `[command] [path]`
- Lint: `[command]`
- Format: `[command]`

## Architecture
- `src/` — Application source code
  - `src/api/` — [description]
  - `src/web/` — [description]
  - `src/shared/` — [description]
- `infra/` — Infrastructure as code
- `tests/` — Integration and E2E tests
- `scripts/` — Automation and CI/CD
- `docs/` — Architecture decisions and runbooks

## Code Style
- [2-3 concrete rules with examples]
- Example:
  ```[language]
  // Preferred pattern
  [code example]
  ```

## Testing
- Framework: [name]
- Location: [pattern]
- Naming: [convention]
- Coverage: [minimum threshold if any]

## Git Conventions
- Commits: [format]
- Branches: [naming pattern]
- PRs: [requirements]

## Boundaries
**Always do:**
- [list critical always-do items]

**Ask first:**
- [list items requiring human approval]

**Never do:**
- [list absolute prohibitions]

15분 만에 시작하기

첫날부터 완벽한 AGENTS.md가 필요하지 않습니다. 최소로 시작하고 반복하세요.

1단계 (5분): 저장소 루트에 AGENTS.md를 생성하세요. 빌드, 테스트, 린트 명령을 추가하세요. 이것이 즉각적 영향이 가장 큽니다.

2단계 (5분): 정확한 버전이 포함된 기술 스택과 디렉터리 구조를 나열한 간단한 아키텍처 섹션을 추가하세요.

3단계 (5분): 경계 섹션을 추가하세요. “never do"로 시작하세요 — 에이전트가 하면 실제 피해가 발생하는 것들. 사람의 판단이 필요한 모든 것에 대해 “ask first” 항목을 추가하세요.

4단계 (진행 중): 에이전트가 실수를 할 때마다 규칙을 추가하세요. 이것이 모든 성공적인 팀이 따르는 유기적 성장 패턴입니다. AGENTS.md는 배운 교훈의 살아 있는 기록이 됩니다.

프로 팁: 기존 저장소를 스캔하여 — 패키지 파일, CI/CD 워크플로, 기여 가이드라인, git 기록 — 시작 AGENTS.md를 자동 생성해 달라고 AI 에이전트에게 요청하는 커뮤니티 관리 프롬프트가 있습니다. 기존 프로젝트를 위한 가장 빠른 부트스트랩입니다.

멀티 에이전트 현실

지금 이것이 중요한 이유입니다. AI CLI 전쟁은 팀들이 승인 여부와 관계없이 아마 이미 여러 에이전트를 사용하고 있음을 의미합니다. 개발자는 작업에 가장 잘 맞는 도구를 선택합니다 — 대화형 편집에는 Cursor, 복잡한 리팩터링에는 Claude Code, 백그라운드 작업 큐에는 Codex.

AGENTS.md가 없으면, 각 개발자가 각 에이전트를 독립적으로 구성합니다. 규칙이 표류합니다. 품질이 달라집니다. 같은 실수가 코드베이스의 다른 부분에서 다른 에이전트에 의해 반복됩니다.

AGENTS.md가 있으면, 표준을 한 번 정의합니다. 모든 에이전트, 모든 개발자, 모든 세션이 동일한 기준선에서 시작합니다. 이것이 엔터프라이즈 가치 제안입니다: 하나의 에이전트를 선택하는 것이 아니라, 모두 일관되게 작동하게 만드는 것.

리소스

• 공식 AGENTS.md 스펙 및 예시
• GitHub Blog: 훌륭한 agents.md 작성법 — 2,500개 이상 저장소의 교훈
• Windsurf AGENTS.md 문서
• agentsmd.net 템플릿 — 기술 스택별 14개의 프로덕션 준비 템플릿

멀티 에이전트 전략을 제대로 잡으세요

AGENTS.md가 기반이지만, 더 넓은 AI 코딩 전략의 한 조각입니다. CLAUDE.md 파일과 어떻게 결합되나요? MCP 서버 인프라는요? 거버넌스 요구 사항은요? 팀의 실제 워크플로는요?

Big Hat Group은 엔터프라이즈 팀이 일관된 AI 에이전트 전략을 구축하도록 돕습니다 — 단순한 구성 파일이 아니라 전체 스택: 에이전트 구성, 스킬 개발, 보안 경계, 그리고 컴플라이언스 팀을 편안하게 유지하는 거버넌스 프레임워크. 우리는 Copilot, Claude Code, Codex를 동시에 운영하는 조직에 이 패턴을 배포해 왔습니다.

팀이 여러 AI 코딩 에이전트를 관리하며 통합된 접근 방식이 필요하다면, 연락하세요.

Kevin Kaminski는 Microsoft MVP이자 Big Hat Group의 Principal로, 엔터프라이즈 팀이 AI 에이전트, Windows 365, 그리고 현대 관리 솔루션을 배포하도록 돕습니다.