AI 코딩 도구들의 공통 언어, AGENTS.md 완전정복

 

 

요즘 AI 코딩 도구들 많이 쓰시죠?

Cursor, GitHub Copilot, Claude Code, Antigravity, Gemini CLI...

그런데 이 도구들을 여러 개 쓰다 보면 한 가지 불편한 점이 생깁니다.

 

"같은 내용인데 도구마다 설정 파일을 따로 만들어야 해?"

 

바로 이 문제를 해결하기 위해 등장한 것이 AGENTS.md 입니다!

 

 

AGENTS.md가 뭔가요?

 

한마디로 표현하면 "AI 에이전트를 위한 README" 입니다.

 

우리가 사람을 위해 `README.md`를 작성하듯이,

AI 코딩 도구들을 위해 `AGENTS.md`를 작성하는 거예요.

 

"이 프로젝트는 이렇게 빌드해. 테스트는 이렇게 실행해. 코딩 스타일은 이걸 따라줘."

 

이런 내용을 AI에게 미리 알려주는 파일입니다.

그냥 평범한 Markdown 파일이라 별다른 문법도 필요 없어요!

 

 

왜 필요한가요?

 

AGENTS.md가 나오기 전에는 이런 상황이었습니다...

AI 도구	설정 파일
Claude Code	CLAUDE.md
Cursor	.cursor/rules
GitHub Copilot	.github/copilot-instructions.md
Gemini CLI	GEMINI.md

 

도구마다 파일 이름이 다 달랐던 거죠.

같은 내용을 4번씩 반복해서 써야 하는 상황...

 

그래서 OpenAI, Google, Cursor, Factory 등 여러 회사들이 모여서

"우리 하나로 통일하자!" 하고 만든 공통 표준이 바로 AGENTS.md입니다.

 

현재는 Linux Foundation 산하 Agentic AI Foundation(AAIF) 에서 관리하고 있어,

특정 회사에 종속되지 않는 진짜 오픈 표준이에요.

 

 

얼마나 많이 쓰이고 있나요?

 

- GitHub 오픈소스 프로젝트 6만 개 이상 채택

- 지원 도구 30개 이상 (Cursor, Copilot, Claude Code, Gemini CLI, Devin, Aider 등)

- OpenAI 메인 레포지토리에만 88개의 AGENTS.md 파일이 있을 정도!

 

이미 사실상 표준(de facto standard)으로 자리 잡은 거나 다름없습니다.

 

 

어떻게 작성하나요?

 

특별한 형식이 없어서 정말 간단합니다.

프로젝트 루트에 `AGENTS.md` 파일을 만들고, 아래처럼 작성하면 끝!

 

# AGENTS.md

## 빌드 & 테스트 명령어
- 의존성 설치: `pnpm install`
- 개발 서버 실행: `pnpm dev`
- 테스트 실행: `pnpm test`
- 린트 실행: `pnpm lint`

## 코딩 스타일
- TypeScript strict mode 사용
- 단일 따옴표, 세미콜론 없음

## PR 규칙
- 커밋 전 `pnpm lint && pnpm test` 필수 실행

 

 

이게 전부예요! 어렵지 않죠?

 

딱 하나만 기억하세요.

파일이 너무 길면 AI가 제대로 읽지 못합니다.

50~100줄 이내로 짧고 명확하게 작성하는 게 핵심입니다.

 

 

## 실전 예시

 

그럼 중고거래 앱 개발을 위한 AGENTS.md 작성 예제를 살펴보겠습니다.

# AGENTS.md

## Project Overview
Flutter 기반 중고거래 앱 (iOS/Android 동시 지원)
- 백엔드: Node.js + Express / DB: PostgreSQL / 스토리지: AWS S3
- 상태관리: Riverpod / 라우팅: GoRouter

---

## Build & Run Commands
- 의존성 설치: `flutter pub get`
- 앱 실행 (개발): `flutter run --flavor dev`
- 앱 실행 (운영): `flutter run --flavor prod`
- 빌드 (Android): `flutter build apk --flavor prod`
- 빌드 (iOS): `flutter build ipa --flavor prod`
- 백엔드 실행: `npm run dev`
- DB 마이그레이션: `npm run migrate`

## Test Commands
- Flutter 단위 테스트: `flutter test`
- 백엔드 테스트: `npm test`
- E2E 테스트: `flutter test integration_test/`
- 커버리지 확인: `flutter test --coverage`

---

## Project Structure
lib/
├── core/ # 공통 유틸, 상수, 테마
├── features/
│ ├── auth/ # 로그인/회원가입
│ ├── product/ # 상품 등록/조회/검색
│ ├── chat/ # 채팅 (Firebase Realtime DB)
│ ├── payment/ # 결제 (포트원 연동)
│ └── mypage/ # 마이페이지, 거래내역
├── shared/ # 공통 위젯, 모델
server/
├── routes/ # API 라우트
├── controllers/ # 비즈니스 로직
├── models/ # DB 모델 (Sequelize)
└── middlewares/ # 인증, 에러 핸들링

---

## Domain Terms (도메인 용어)
- **거래상태**: SALE(판매중) / RESERVED(예약중) / SOLD(판매완료)
- **신고유형**: FRAUD(사기) / PROHIBITED(금지품목) / SPAM(도배)
- **안전거래**: 포트원 에스크로 결제 방식 (구매확정 전 판매자 정산 없음)
- **매너온도**: 사용자 신뢰도 지표 (기본 36.5°C, 최대 99°C)

---

## Code Style
- Flutter: `flutter_lints` 규칙 준수
- 파일명: snake_case / 클래스명: PascalCase
- API 응답은 반드시 `Result<T>` 패턴으로 래핑
- 비동기 처리: async/await 사용 (콜백 금지)
- 하드코딩 문자열 금지 → `AppStrings` 상수 클래스 사용

## Architecture Rules
- **Feature-first** 폴더 구조 유지 (도메인별로 분리)
- 비즈니스 로직은 Controller/UseCase에만 작성 (Widget에 직접 금지)
- API 호출은 반드시 `Repository` 레이어를 통해서만 수행
- 화면 간 데이터 전달은 GoRouter의 `extra` 파라미터 사용

---

## Security (보안 주의사항)
- `.env` 파일 절대 커밋 금지 (AWS Key, API Secret 포함)
- 사용자 업로드 이미지는 서버 직접 저장 금지 → S3 Presigned URL 사용
- 결제 금액 검증은 반드시 **서버 사이드**에서 수행 (클라이언트 값 신뢰 금지)
- JWT 토큰은 `flutter_secure_storage`에만 저장 (SharedPreferences 금지)
- 전화번호, 주소 등 개인정보는 로그에 출력 금지

---

## PR & Commit Rules
- 브랜치 형식: `feature/기능명`, `fix/버그명`, `hotfix/긴급수정명`
- 커밋 형식: `feat: 상품 검색 필터 추가` / `fix: 채팅 메시지 중복 표시 버그 수정`
- PR 머지 전 조건: `flutter test` + `npm test` 모두 통과 필수
- 리뷰어 최소 1명 승인 후 머지

---

## Never Do (절대 하지 말 것)
- `main` 브랜치에 직접 푸시 금지
- 결제 관련 코드 수정 시 단독 판단 금지 → 반드시 리뷰 요청
- 사용자 데이터 직접 삭제 금지 → soft delete(is_deleted 플래그) 사용
- 운영 DB에 직접 쿼리 실행 금지

 

 

도메인 용어 섹션이 핵심입니다.

매너온도, 안전거래, 거래상태 같은 앱 고유 용어를 AI가 모르면 엉뚱한 코드를 짜거든요.

Never Do 섹션도 중요한데, 결제나 운영 DB처럼 실수하면 돌이킬 수 없는 작업들을 명시적으로 막아두는 역할을 합니다.

 

 

CLAUDE.md와는 다른 건가요?

 

헷갈리실 수 있는데, 간단히 정리하면 이렇습니다.

 

- AGENTS.md : 모든 AI 도구에서 공통으로 동작하는 범용 파일

- CLAUDE.md : Claude Code 전용, `@imports` 같은 고급 기능 사용 가능

 

Claude Code만 쓰신다면 CLAUDE.md가 더 강력하고,

여러 AI 도구를 함께 쓰신다면 AGENTS.md 하나로 통일하는 게 훨씬 편합니다.

 

두 파일을 동시에 쓰고 싶다면 심볼릭 링크로 연결하는 방법도 있어요.

 

ln -s AGENTS.md CLAUDE.md

 

 

파일 하나로 두 이름 모두 사용하는 꿀팁입니다!

 

 

마무리하며...

 

AI 코딩 도구가 점점 다양해지는 시대에,

AGENTS.md 하나면 모든 도구에 프로젝트 맥락을 한 번에 전달할 수 있습니다.

 

새 프로젝트를 시작할 때 README.md 만들듯이,

이제 AGENTS.md도 함께 만드는 습관을 들여보세요!

 

특히 여러 AI 도구를 혼용하는 팀 환경이라면,

설정 파일 관리에 드는 시간을 확 줄일 수 있을 거예요.

 

 

 

#AGENTS.md #AI코딩 #Claude코드 #Cursor #GitHubCopilot #GeminiCLI #AI개발도구 #오픈표준 #LinuxFoundation #개발자팁