AGENTS.md란 무엇인가? Claude Code 프로젝트 운영 규칙 설계 완전 정리 (2026)

AGENTS.md란 무엇인가? Claude Code 프로젝트 운영 규칙 설계 완전 정리 (2026)

한 줄 요약

AGENTS.md는 Claude Code, Codex, Cursor 같은 AI 코딩 에이전트가 프로젝트 구조, 개발 규칙, 아키텍처 원칙을 이해하도록 만드는 저장소 수준(Repository-level) 설정 파일이다. 2026년에는 사실상 AI 개발 프로젝트의 새로운 README 역할로 자리잡고 있다. (arXiv)

---

이 글에서 다루는 내용

• AGENTS.md란?
• 왜 필요한가?
• CLAUDE.md와 차이
• 실제 예제
• 실무 설계 방법
• NestJS 프로젝트 예시
• 자주 하는 실수
• FAQ

---

AGENTS.md란?

AGENTS.md는 AI 에이전트에게 프로젝트 규칙을 설명하는 파일이다.

예전에는 개발자가 README를 읽었다.

지금은:

개발자
+
Claude Code
+
Cursor
+
Codex
+
Gemini CLI

모두 프로젝트를 읽는다.

그래서 프로젝트는 이제 사람뿐 아니라 AI도 이해해야 한다.

최근 연구에서는 AGENTS.md가 여러 AI 코딩 도구에서 공통적으로 사용되는 사실상 표준(interoperable standard)으로 등장했다고 분석한다. (arXiv)

---

왜 AGENTS.md가 필요한가?

예를 들어 Claude에게 이렇게 시킨다.

회원가입 API 만들어줘

AGENTS.md가 없으면:

Claude가 추측
↓
구조 제각각
↓
코드 스타일 흔들림

---

AGENTS.md가 있으면:

프로젝트 규칙 읽기
↓
아키텍처 이해
↓
규칙 기반 생성

---

실제로 효과가 있나?

의외로 꽤 크다.

2026 연구 기준:

• 실행 시간 감소
• 토큰 사용 감소
• 작업 효율 향상

AGENTS.md가 있는 저장소는 AI 에이전트의 실행 시간과 출력 토큰 사용량이 감소하는 경향을 보였다. (arXiv)

---

AGENTS.md와 CLAUDE.md 차이는?

많이 헷갈린다.

구분AGENTS.mdCLAUDE.md

목적	범용 Agent 규칙	Claude 전용
대상	여러 Agent	Claude
범위	저장소 규칙	Claude 작업 최적화
활용	공통 표준	세부 동작

---

요즘 많이 쓰는 구조:

repo/

AGENTS.md
CLAUDE.md
skills/
context/

---

가장 많이 쓰는 AGENTS.md 구조

최소 버전

# Project Rules

- Use NestJS
- Use PostgreSQL
- Use Service Layer
- No business logic in controllers

---

추천 버전

# Architecture

- Controller
- Service
- Repository

# Backend Rules

- NestJS only
- Transaction in service
- DTO validation required

# Database

- PostgreSQL
- UUID primary key

# Testing

- Unit test required

# Security

- JWT authentication

---

NestJS 프로젝트 실제 예시

예를 들어:

backend/

src/

---

AGENTS.md

# NestJS Backend Rules

## Controller

- Request validation only
- No business logic

## Service

- Transaction handling
- Domain logic

## Repository

- Database access only

## Security

- JWT required
- Role validation required

---

Claude는 이후 생성하는 코드에 이 규칙을 반영한다.

---

AGENTS.md에서 가장 중요한 것

반응형

많은 사람들이 이렇게 쓴다.

이 프로젝트는...
우리는...
회사 소개...

Claude는 이런 거 별로 안 좋아한다.

---

좋은 예:

# API Rules

- REST only
- snake_case 금지
- DTO validation required

---

핵심:

설명보다 규칙

---

Context Engineering 관점

2026 AI 개발 핵심 키워드:

Context Engineering

---

AI 성능은 이제:

모델
❌

컨텍스트
⭕

이라는 말이 나올 정도다.

최근 연구에서도 Context Files가 Agent 설정의 가장 지배적인 방식으로 확인됐다. (arXiv)

---

AGENTS.md 추천 폴더 구조

초보

repo/

AGENTS.md

---

중급

repo/

AGENTS.md

context/
 ├── architecture.md
 ├── db.md
 └── api.md

---

고급

repo/

AGENTS.md

skills/
subagents/
context/
evals/

---

실제 상위권 팀 구조

2026 Claude Code 프로젝트들은 점점 이런 방향으로 간다.

AGENTS.md
↓
Skill
↓
Subagent
↓
Eval
↓
Workflow

Claude Code는 Skill, Hook, MCP, Subagent 같은 여러 확장 메커니즘을 중심으로 진화하고 있다. (arXiv)

---

AGENTS.md 작성할 때 넣어야 하는 것

1. 아키텍처

Controller
Service
Repository

---

2. 네이밍 규칙

camelCase required

---

3. 테스트 규칙

Unit test required

---

4. 보안 규칙

JWT required

---

5. 금지 규칙

Never:
- use any
- bypass validation
- skip tests

---

자주 하는 실수

실수 1

너무 김

---

Claude는 긴 문서보다:

짧고 명확한 규칙

을 더 잘 활용한다.

---

실수 2

회사 소개 작성

---

필요 없음.

Claude는 마케팅 자료가 아니라:

개발 규칙

이 필요하다.

---

실수 3

모든 규칙 AGENTS.md에 작성

---

좋은 방법:

AGENTS.md
↓
context 링크

---

앞으로 뜨는 구조 — Repository Intelligence

최근 연구에서는 Repository Intelligence Graph(RIG) 개념도 등장했다.

핵심:

저장소 구조
↓
그래프화
↓
Agent 이해 향상

복잡한 저장소에서 정확도와 작업 효율이 크게 향상되는 결과가 보고됐다. (arXiv)

---

FAQ

Q. README와 AGENTS.md 둘 다 필요한가요?

필요하다.

파일대상

README	사람
AGENTS.md	AI

---

Q. AGENTS.md는 Claude만 사용하나요?

아니다.

최근 연구에서는:

• Claude Code
• Cursor
• Codex
• Gemini

등에서 유사한 Context File 구조가 사용되는 것으로 분석됐다. (arXiv)

---

Q. AGENTS.md는 어디에 두나요?

보통:

repo root

최상위.

---

실무 팁

개인적으로 2026년부터는:

README
+
AGENTS.md
+
SKILLS

이 세 개가 거의 세트라고 본다.

---

예전에는:

코드 작성

이 중요했다.

지금은:

AI가 이해하기 쉬운 저장소 설계

가 중요해지고 있다.

---

핵심 요약

• AGENTS.md는 AI 에이전트용 프로젝트 규칙 파일
• Claude Code 시대 사실상 표준으로 확산 중
• 실행 시간과 토큰 사용량 감소 효과 연구 존재
• 설명보다 규칙 중심으로 작성
• Context Engineering의 핵심 요소
• README + AGENTS.md + Skills 조합이 강력

---

출처

• Configuring Agentic AI Coding Tools 연구 (arXiv)
• AGENTS.md 효율성 연구 (arXiv)
• Claude Code 아키텍처 분석 (arXiv)
• Claude Agent Skills 공식 문서 (Claude 플랫폼)
• CLAUDE.md Best Practices 2026 (agentlint.app)

---

AGENTSmd, ClaudeCode, ClaudeSkill, ContextEngineering, AI개발, AgenticAI, LLM개발, SKILLmd, AI아키텍처, 2026AI