AGENTS.md란? Codex·Claude Code·Cursor에서 프로젝트 지침 파일을 쓰는 이유

AGENTS.md가 무엇인지, Codex·Claude Code·Cursor에서 프로젝트 지침 파일을 어떻게 쓰는지 정리합니다. Claude Code의 CLAUDE.md, Cursor Rules와 .mdc 파일 구조, 실제 작성 예시와 주의사항까지 초보자 기준으로 설명합니다.

 

AGENTS.md는 AI 코딩 에이전트에게 “이 프로젝트에서는 이렇게 작업해라”라고 알려주는 지침 파일이다. Codex를 쓰다 보면 자주 보이고, Claude Code나 Cursor까지 같이 쓰면 파일명이 달라서 헷갈리기 쉽다.

먼저 결론부터 정리하면 이렇다.

도구	기본 프로젝트 지침 파일	동작 방식
Codex	AGENTS.md	작업 전 프로젝트 지침으로 참고
Claude Code	CLAUDE.md	Claude Code 메모리/프로젝트 지침으로 참고
Cursor	.cursor/rules, Cursor Rules, AGENTS.md 관련 지원	규칙 파일과 범위별 Rules를 통해 적용
공통 목적	프로젝트 구조, 명령어, 코드 스타일, 작업 규칙 전달	AI가 작업 전 참고할 기준 제공

 

여기서 중요한 점은 **모든 AI 코딩 도구가 AGENTS.md 하나만 공통으로 읽는 것은 아니라는 점**이다.

특히 Claude Code는 AGENTS.md가 아니라 CLAUDE.md가 기본이다. 2026년 6월 기준 Anthropic 공식 문서에서는 Claude Code의 프로젝트 메모리 파일로 CLAUDE.md를 안내한다. 이미 AGENTS.md를 쓰는 프로젝트라면 CLAUDE.md 안에서 @AGENTS.md로 가져오거나, 심볼릭 링크를 만들어 공통 지침을 공유하는 식으로 구성할 수 있다.

 

AGENTS.md는 AI 코딩 에이전트용 프로젝트 설명서다

개발자가 새 프로젝트에 들어오면 보통 README.md를 먼저 읽는다.

AI 코딩 에이전트도 비슷하다. 다만 AI에게는 사람이 읽는 설명서보다 조금 더 직접적인 지시가 필요하다.

예를 들면 이런 내용이다.

- 패키지 매니저는 npm이 아니라 pnpm을 사용한다.
- 테스트는 변경 후 pnpm test로 확인한다.
- API 라우터는 src/routes 아래에 둔다.
- DB 스키마를 직접 수정하지 말고 migration 파일을 만든다.
- 보안 관련 파일은 수정하기 전에 먼저 설명한다.

 

이런 내용을 매번 채팅으로 입력하면 번거롭다.

“이 프로젝트는 FastAPI야. SQLAlchemy 쓰고, 테스트는 pytest로 돌리고, env 파일은 건드리지 말고, 기존 구조 따라줘.”

처음에는 이렇게 말해도, 세션이 바뀌면 다시 설명해야 한다. 작업 도중에도 AI가 프로젝트 규칙을 잊거나, 다른 방식으로 코드를 짤 수 있다.

AGENTS.md나 CLAUDE.md 같은 파일은 이 반복 설명을 줄이기 위한 장치다.

 

왜 프로젝트 지침 파일이 필요한가

AI 코딩 도구는 코드베이스를 읽을 수 있지만, 프로젝트의 암묵적인 규칙까지 항상 정확히 이해하는 것은 아니다.

예를 들어 같은 React 프로젝트라도 팀마다 구조가 다르다.

src/components
src/features
src/app
src/pages
src/api

 

어떤 팀은 기능 단위로 묶고, 어떤 팀은 역할 단위로 묶는다. 테스트 파일 위치도 다르고, 상태 관리 방식도 다르다.

AI가 주변 코드를 보고 어느 정도 맞출 수는 있다. 하지만 프로젝트가 커질수록 애매한 선택지가 많아진다.

이때 지침 파일이 있으면 AI가 작업 전에 참고할 기준이 생긴다.

- 새 기능은 src/features/{featureName} 아래에 만든다.
- 공통 UI 컴포넌트는 src/components/ui에 둔다.
- API 호출 코드는 src/lib/api에 둔다.
- 테스트 파일은 원본 파일 옆에 *.test.ts 형식으로 둔다.

 

이 정도만 있어도 AI가 엉뚱한 위치에 파일을 만들 확률이 줄어든다.

실제로는 지침 파일이 코드 품질을 자동으로 보장한다기보다, AI가 매번 새 프로젝트처럼 행동하지 않게 만드는 기준선에 가깝다.

 

CLI형 AI 에이전트에서는 명령어 지침이 더 중요하다

Codex나 Claude Code 같은 최근 AI 코딩 도구는 단순히 코드 조각만 추천하는 자동완성 도구와 다르다. 프로젝트 파일을 읽고, 코드를 수정하고, 터미널에서 명령어를 실행하는 에이전트 성격이 강하다.

그래서 지침 파일의 명령어 섹션이 중요하다.

AI가 단순히 텍스트를 생성하는 수준이라면 “실행 명령어”는 참고 정보에 가깝다. 하지만 AI가 직접 테스트, 린트, 빌드 명령어를 실행할 수 있다면 이야기가 달라진다. 이때 명령어 지침은 실제 실행 기준이 된다.

예를 들어 프로젝트는 pnpm을 쓰는데 AI가 습관적으로 npm install을 실행하면 lock 파일이 꼬이거나 의존성 관리 방식이 달라질 수 있다.

## Commands

- Install dependencies: `pnpm install`
- Run dev server: `pnpm dev`
- Run lint: `pnpm lint`
- Run tests: `pnpm test`
- Do not use npm or yarn in this repository.

 

이런 식으로 적어두면 AI가 프로젝트에서 어떤 명령어를 우선 사용해야 하는지 판단하기 쉬워진다.

여기서 중요한 점은 명령어를 많이 넣는 것이 아니다. 실제로 이 프로젝트에서 써야 하는 명령어만 정확히 넣는 것이다.

잘못된 예시는 다음과 같다.

## Commands

- Run app: `npm run dev`
- Run app: `pnpm dev`
- Run tests: `npm test`
- Run tests: `pnpm test`

 

이렇게 쓰면 AI 입장에서는 어떤 명령어가 현재 기준인지 헷갈릴 수 있다.

수정하면 이렇게 된다.

## Commands

- Use `pnpm` only.
- Run app: `pnpm dev`
- Run tests: `pnpm test`
- Do not use `npm install` or `yarn install`.

 

AI가 터미널에서 직접 실행할 수 있는 도구일수록, 명령어 지침은 짧고 명확해야 한다.

 

Codex는 AGENTS.md를 읽는다

Codex에서는 AGENTS.md가 프로젝트 지침 파일 역할을 한다.

OpenAI 공식 문서 기준으로 Codex는 작업을 시작하기 전에 AGENTS.md 파일을 읽는다. 전역 범위의 지침과 프로젝트별 지침을 계층적으로 적용할 수 있다.

일반적인 위치는 프로젝트 루트다.

my-project/
├── AGENTS.md
├── package.json
├── src/
└── tests/

 

프로젝트 루트에 AGENTS.md를 두면 Codex가 해당 프로젝트를 작업할 때 참고할 수 있다.

예시는 다음과 같다.

# AGENTS.md

## Project overview

This is a Next.js application using TypeScript and Tailwind CSS.

## Commands

- Install dependencies: `pnpm install`
- Run dev server: `pnpm dev`
- Run tests: `pnpm test`
- Run lint: `pnpm lint`

## Coding rules

- Use TypeScript for all new files.
- Prefer functional components.
- Keep server-side logic out of client components.
- Do not introduce new dependencies without explaining why.

## Before finishing

- Run `pnpm lint` when changing TypeScript files.
- Run related tests when modifying business logic.

 

여기서 핵심은 “프로젝트를 설명하는 문서”와 “AI에게 시키는 행동 규칙”을 함께 넣는 것이다.

단, 너무 길게 쓰면 오히려 안 좋다. AI가 읽어야 할 컨텍스트가 늘어나고, 중요한 규칙이 묻힐 수 있다.

 

Claude Code는 CLAUDE.md가 맞다

사용자가 헷갈리기 쉬운 부분이 바로 Claude Code다.

Claude Code는 기본적으로 CLAUDE.md를 사용한다. AGENTS.md가 아니다.

프로젝트 루트에 둘 수 있다.

my-project/
├── CLAUDE.md
├── package.json
├── src/
└── tests/

 

또는 .claude 디렉터리 안에 둘 수도 있다.

my-project/
├── .claude/
│   └── CLAUDE.md
├── src/
└── package.json

 

Claude Code의 CLAUDE.md에는 프로젝트 지침, 빌드 명령어, 테스트 명령어, 코드 스타일, 자주 하는 작업 흐름 등을 넣을 수 있다.

예시는 다음과 같다.

# CLAUDE.md

## Project context

This project is a FastAPI backend application.

## Development commands

- Create virtual environment: `python -m venv .venv`
- Install dependencies: `pip install -r requirements.txt`
- Run server: `fastapi dev main.py`
- Run tests: `pytest`

## Rules

- Use Pydantic v2 style.
- Keep route handlers thin.
- Put business logic in service modules.
- Do not commit secrets or `.env` files.
- Explain before changing authentication or database migration logic.

 

Claude Code에서 이미 AGENTS.md를 쓰고 있는 저장소를 함께 쓰고 싶다면 CLAUDE.md 안에서 가져오는 방식이 현실적이다.

@AGENTS.md

## Claude Code specific rules

- Use Plan Mode before changing authentication logic.
- Ask before running destructive commands.

 

이렇게 하면 공통 지침은 AGENTS.md에 두고, Claude Code에만 필요한 내용은 CLAUDE.md 아래에 추가할 수 있다.

심볼릭 링크를 쓸 수도 있다.

ln -s AGENTS.md CLAUDE.md

 

다만 Windows에서는 심볼릭 링크 생성에 권한 문제가 생길 수 있다. 그럴 때는 CLAUDE.md에서 @AGENTS.md로 가져오는 방식이 더 단순하다.

 

Cursor는 Rules와 AGENTS.md를 함께 봐야 한다

Cursor는 예전부터 프로젝트 지침을 다루는 방식이 여러 번 바뀌었다.

예전에는 .cursorrules 파일을 많이 사용했다. 하지만 현재는 Cursor Rules를 중심으로 보는 것이 더 적합하다. 보통 프로젝트 안의 .cursor/rules 디렉터리에 규칙을 나누어 관리한다.

예시는 다음과 같다.

my-project/
├── .cursor/
│   └── rules/
│       ├── frontend.mdc
│       ├── testing.mdc
│       └── api.mdc
├── src/
└── package.json

 

Cursor Rules는 특정 파일, 디렉터리, 작업 맥락에 맞는 지침을 나눠서 관리하기 좋다.

예를 들어 프론트엔드 규칙은 frontend.mdc, 테스트 규칙은 testing.mdc처럼 나눌 수 있다.

# frontend.mdc

- Use React functional components.
- Prefer existing UI components before creating new ones.
- Keep component files small and focused.
- Do not add new styling libraries.

 

Cursor 공식 문서에서는 Project, Team, User Rules와 함께 AGENTS.md도 언급한다. 그래서 Cursor만 단독으로 쓴다면 Cursor Rules를 우선 정리하고, Codex 같은 다른 도구와 함께 쓴다면 AGENTS.md를 공통 지침 파일로 두는 방식도 고려할 수 있다.

실무적으로는 이렇게 나누면 덜 헷갈린다.

상황	추천 방식
Codex만 사용	AGENTS.md
Claude Code만 사용	CLAUDE.md
Cursor만 사용	.cursor/rules
Codex + Claude Code 같이 사용	AGENTS.md + CLAUDE.md에서 import
Codex + Cursor 같이 사용	AGENTS.md + Cursor Rules
세 도구 모두 사용	공통 규칙은 AGENTS.md, 도구별 규칙은 각 도구 파일에 분리

 

README와 AGENTS.md는 어떻게 다를까

README.md와 AGENTS.md는 비슷해 보이지만 목적이 다르다.

파일	주 독자	목적
README.md	사람	프로젝트 소개, 설치, 실행 방법 설명
AGENTS.md	AI 코딩 에이전트	작업 방식, 코드 수정 규칙, 명령어, 주의사항 전달
CLAUDE.md	Claude Code	Claude Code 세션에서 반복 적용할 프로젝트 지침
.cursor/rules	Cursor	Cursor Agent가 작업할 때 참고할 규칙

 

README는 사람이 프로젝트를 이해하기 위한 문서다. 그래서 배경 설명, 설치 방법, 배포 방법, 기능 소개가 들어간다.

반면 AGENTS.md는 AI가 작업할 때 실수하지 않도록 돕는 문서다.

예를 들어 README에는 이렇게 쓸 수 있다.

## Getting started

Run the development server:

 

pnpm dev

 

하지만 AGENTS.md에는 조금 더 행동 지침처럼 쓰는 편이 낫다.

## Commands

- Use `pnpm dev` for local development.
- Use `pnpm test` before finishing changes that touch business logic.
- Do not use npm or yarn in this repository.

 

차이는 작아 보이지만 중요하다.

AI에게는 “설명”보다 “어떤 상황에서 무엇을 해야 하는지”가 더 도움이 된다.

 

지침 파일에 넣으면 좋은 내용

처음부터 거창하게 쓸 필요는 없다. 실제로 반복해서 설명하게 되는 것부터 넣으면 된다.

1. 프로젝트 개요

AI가 프로젝트의 큰 방향을 이해할 수 있게 짧게 적는다.

## Project overview

This is a FastAPI backend for a personal finance dashboard.
It provides REST APIs for transactions, categories, and monthly reports.

 

너무 긴 서비스 소개는 필요 없다. AI가 코드 수정 방향을 잡을 정도면 충분하다.

2. 기술 스택과 버전

버전 차이로 코드가 달라지는 경우가 많다.

## Tech stack

- Python 3.12
- FastAPI
- Pydantic v2
- SQLAlchemy 2.x
- PostgreSQL
- pytest

 

특히 Pydantic v1과 v2, Next.js App Router와 Pages Router, React Server Components 같은 부분은 명시하는 편이 좋다.

3. 실행 명령어

AI가 테스트나 린트를 실행할 때 헷갈리지 않도록 적는다.

## Commands

- Install dependencies: `pnpm install`
- Run dev server: `pnpm dev`
- Run lint: `pnpm lint`
- Run tests: `pnpm test`

 

Python 프로젝트라면 이렇게 쓸 수 있다.

## Commands

- Create venv: `python -m venv .venv`
- Install dependencies: `pip install -r requirements.txt`
- Run server: `fastapi dev main.py`
- Run tests: `pytest`

 

여기서 중요한 점은 실제로 프로젝트에서 쓰는 명령어만 넣는 것이다. 언젠가 쓸 수도 있는 명령어까지 다 넣으면 오히려 헷갈린다.

4. 디렉터리 구조 규칙

AI가 파일을 잘못된 위치에 만드는 문제를 줄일 수 있다.

## Project structure

- API routes: `src/routes/`
- Business logic: `src/services/`
- Database models: `src/models/`
- Request and response schemas: `src/schemas/`
- Tests: `tests/`

 

프론트엔드 프로젝트라면 이렇게 쓸 수 있다.

## Project structure

- Page routes: `src/app/`
- Shared UI components: `src/components/`
- Feature-specific components: `src/features/{feature}/components/`
- API clients: `src/lib/api/`
- Hooks: `src/hooks/`

 

5. 코드 스타일

막연한 표현보다 검증 가능한 규칙이 좋다.

나쁜 예시는 다음과 같다.

- Write clean code.
- Keep files organized.
- Make good components.

 

이런 문장은 너무 추상적이다. AI도 사람도 해석이 다를 수 있다.

수정하면 이렇게 된다.

- Keep React components under 150 lines when possible.
- Move reusable logic into hooks.
- Use existing UI components before creating new ones.
- Do not add a new dependency without explaining why.

 

6. 보안과 위험한 작업 규칙

AI 코딩 도구는 파일을 수정하고 명령어를 실행할 수 있다. 그래서 위험한 작업은 명확히 제한하는 것이 좋다.

## Safety rules

- Do not modify `.env` files.
- Do not print secrets, API keys, or tokens.
- Ask before changing authentication logic.
- Ask before running database migration commands.
- Do not run destructive commands such as `rm -rf`, `DROP TABLE`, or forced git reset.

 

물론 지침 파일만으로 위험한 작업이 완전히 차단되는 것은 아니다. 도구의 권한 설정, 승인 모드, 훅, 샌드박스 설정도 함께 봐야 한다.

지침 파일은 안전장치라기보다 “작업 전 주의사항”에 가깝다.

 

지침 파일에 넣으면 안 되는 내용

지침 파일은 길수록 좋은 문서가 아니다.

오히려 너무 길면 AI가 중요한 규칙을 놓칠 수 있다.

1. 오래된 규칙

예를 들어 프로젝트가 npm에서 pnpm으로 바뀌었는데 예전 명령어가 남아 있으면 AI가 잘못된 명령어를 실행할 수 있다.

- Run `npm install`
- Run `pnpm install`

 

이렇게 충돌하는 규칙은 피해야 한다.

하나만 남기는 편이 낫다.

- Use `pnpm install`. Do not use npm or yarn.

 

2. 너무 일반적인 원칙

- Write good code.
- Follow best practices.
- Make it scalable.

 

이런 문장은 거의 도움이 되지 않는다.

대신 프로젝트에서 실제로 반복되는 실수로 바꿔야 한다.

- Do not put business logic inside route handlers.
- Add tests for service functions when changing calculation logic.
- Reuse existing error response format from `src/errors/`.

 

3. 비밀 정보

지침 파일은 보통 저장소에 커밋된다. 그래서 API 키, 토큰, 내부 비밀번호, 개인 계정 정보는 절대 넣으면 안 된다.

나쁜 예시는 다음과 같다.

- Use production API key: sk-...
- Admin password is ...

 

대신 이렇게 적어야 한다.

- Read required environment variables from `.env`.
- Do not create or expose real API keys in examples.
- Use placeholder values in documentation and tests.

 

4. 너무 긴 아키텍처 문서

긴 아키텍처 설명은 별도 문서로 분리하는 편이 낫다.

docs/architecture.md
docs/database.md
docs/api-style.md

 

그리고 지침 파일에서는 필요한 문서만 짧게 참조한다.

## References

- Architecture overview: `docs/architecture.md`
- API response format: `docs/api-style.md`

 

AI가 필요할 때 찾아 읽을 수 있도록 길을 알려주는 방식이다.

 

바로 쓸 수 있는 AGENTS.md 예시

아래 예시는 Codex 기준으로 바로 시작할 수 있는 단순한 AGENTS.md 템플릿이다.

# AGENTS.md

## Project overview

This project is a web application maintained by a small development team.
Follow the existing code style and avoid unnecessary rewrites.

## Tech stack

- TypeScript
- React
- Node.js
- pnpm

## Commands

- Install dependencies: `pnpm install`
- Run development server: `pnpm dev`
- Run lint: `pnpm lint`
- Run tests: `pnpm test`
- Do not use npm or yarn in this repository.

## Project structure

- Application code: `src/`
- Shared components: `src/components/`
- Feature modules: `src/features/`
- Utility functions: `src/lib/`
- Tests: `tests/`

## Coding rules

- Use TypeScript for new files.
- Reuse existing components before creating new ones.
- Do not add new dependencies unless necessary.
- Keep changes focused on the requested task.
- Do not perform broad refactoring unless explicitly requested.

## Safety rules

- Do not modify `.env` files.
- Do not expose secrets, tokens, or API keys.
- Ask before changing authentication, payment, or database migration logic.
- Do not run destructive commands without confirmation.

## Before finishing

- Run lint when changing TypeScript files.
- Run relevant tests when changing business logic.
- Summarize what changed and mention any tests that were not run.

 

이 정도면 처음 쓰기에는 충분하다.

중요한 건 처음부터 완성형 문서를 만들려고 하지 않는 것이다. AI가 같은 실수를 반복할 때마다 한 줄씩 추가하는 편이 더 현실적이다.

 

Claude Code용 CLAUDE.md 예시

Claude Code만 쓴다면 CLAUDE.md로 작성한다.

# CLAUDE.md

## Project overview

This is a backend API project.
Keep changes small and explain risky decisions before editing.

## Commands

- Run server: `fastapi dev main.py`
- Run tests: `pytest`
- Run formatter: `ruff format .`
- Run linter: `ruff check .`

## Architecture rules

- Route handlers should stay thin.
- Put business logic in service modules.
- Put request and response models in schema modules.
- Do not mix database models and API schemas.

## Safety rules

- Do not edit `.env` files.
- Do not print secrets or tokens.
- Ask before changing authentication logic.
- Ask before changing migration files.

## Workflow

- First inspect related files.
- Make the smallest change that solves the issue.
- Run relevant tests when possible.
- Explain any skipped tests.

 

이미 AGENTS.md가 있는 프로젝트에서 Claude Code도 같이 쓰려면 이렇게 구성할 수 있다.

@AGENTS.md

## Claude Code specific rules

- Use Plan Mode before large refactors.
- Ask before running database commands.

 

이 방식은 중복을 줄이는 데 좋다.

공통 규칙은 AGENTS.md에 두고, Claude Code 전용 규칙만 CLAUDE.md에 남기면 된다.

 

Cursor Rules 예시

Cursor에서는 .cursor/rules에 주제별 규칙을 나눠 둘 수 있다.

예를 들어 테스트 규칙은 이렇게 분리할 수 있다.

.cursor/rules/testing.mdc

 

# Testing rules

- Add or update tests when changing business logic.
- Prefer existing test helpers.
- Do not introduce a new testing library.
- If tests are not run, explain why.

 

API 규칙은 따로 둘 수 있다.

.cursor/rules/api.mdc

 

# API rules

- Follow the existing error response format.
- Validate input at the boundary.
- Do not return raw database models from API handlers.
- Keep authentication checks explicit.

 

Cursor만 쓴다면 이 방식이 깔끔하다. 여러 도구를 같이 쓴다면 공통 규칙은 AGENTS.md에 두고, Cursor에서만 필요한 규칙은 .cursor/rules에 분리하는 방식이 좋다.

 

도구별 추천 구성

AI 코딩 도구를 하나만 쓸 때는 단순하게 가면 된다.

Codex만 쓰는 경우

my-project/
├── AGENTS.md
├── src/
└── package.json

 

Claude Code만 쓰는 경우

my-project/
├── CLAUDE.md
├── src/
└── package.json

 

또는 다음처럼 둘 수 있다.

my-project/
├── .claude/
│   └── CLAUDE.md
├── src/
└── package.json

 

Cursor만 쓰는 경우

my-project/
├── .cursor/
│   └── rules/
│       ├── coding.mdc
│       ├── testing.mdc
│       └── api.mdc
├── src/
└── package.json

 

Codex와 Claude Code를 같이 쓰는 경우

my-project/
├── AGENTS.md
├── CLAUDE.md
├── src/
└── package.json

 

CLAUDE.md는 이렇게 작성한다.

@AGENTS.md

## Claude Code specific rules

- Use Plan Mode before large refactors.
- Ask before running destructive commands.

 

세 도구를 모두 쓰는 경우

my-project/
├── AGENTS.md
├── CLAUDE.md
├── .cursor/
│   └── rules/
│       ├── coding.mdc
│       └── testing.mdc
├── src/
└── package.json

 

이 구성에서는 AGENTS.md를 공통 기준으로 사용한다.

CLAUDE.md는 Claude Code가 AGENTS.md를 가져오게 만들고, .cursor/rules에는 Cursor에서만 세밀하게 적용할 규칙을 둔다.

예를 들어 공통 규칙은 AGENTS.md에 둔다.

# AGENTS.md

## Common rules

- Use pnpm only.
- Do not edit `.env` files.
- Keep changes focused.
- Run relevant tests after changing business logic.

 

Claude Code 전용 규칙은 CLAUDE.md에 둔다.

@AGENTS.md

## Claude Code specific rules

- Ask before running database commands.
- Explain skipped tests before finishing.

 

Cursor 전용 규칙은 .cursor/rules에 둔다.

# .cursor/rules/testing.mdc

- Prefer existing test helpers.
- Add tests near the changed feature.
- Do not introduce a new testing library.

 

이렇게 나누면 세 도구를 같이 쓰더라도 같은 규칙을 여러 파일에 반복해서 쓰지 않아도 된다.

 

자주 하는 오해

1. AGENTS.md를 만들면 AI가 무조건 그대로 따를까?

아니다.

지침 파일은 강제 설정이 아니라 컨텍스트에 가깝다. AI가 참고할 가능성을 높여주는 문서이지, 보안 정책처럼 무조건 차단하는 장치는 아니다.

정말 막아야 하는 작업이 있다면 도구의 권한 설정, 승인 모드, 훅, CI, 브랜치 보호 규칙 같은 실제 제어 장치가 필요하다.

예를 들어 “DB migration은 확인 없이 실행하지 마”라고 적는 것은 도움이 된다. 하지만 실제 운영 DB 접근 권한을 막는 것은 지침 파일이 아니라 권한 관리에서 해야 한다.

2. README 내용을 그대로 복사하면 될까?

일부는 가능하지만 그대로 복사하는 것은 별로 좋지 않다.

README는 사람을 위한 문서다. AI 지침 파일은 작업을 위한 문서다.

README의 긴 소개보다 다음 같은 짧은 규칙이 더 효과적이다.

- Use existing service patterns from `src/services/`.
- Do not create a new architecture for small changes.
- Run `pnpm test` after changing business logic.

 

3. 규칙을 많이 넣을수록 좋을까?

아니다.

규칙이 많아질수록 중요한 지침이 묻힌다. 서로 충돌하는 규칙이 생길 가능성도 커진다.

처음에는 30~80줄 정도로 시작하는 편이 좋다. 이후 AI가 반복해서 실수하는 부분만 추가한다.

4. 개인 취향도 커밋해야 할까?

팀 공통 규칙과 개인 취향은 분리하는 편이 좋다.

예를 들어 팀 전체가 따라야 하는 규칙은 커밋해도 된다.

- Use pnpm.
- Run tests before finishing backend changes.
- Follow the existing API response format.

 

하지만 개인 로컬 서버 주소, 개인 테스트 계정, 개인 선호 명령어는 커밋하지 않는 편이 안전하다.

Claude Code라면 CLAUDE.local.md 같은 로컬 파일을 쓸 수 있고, Cursor나 Codex도 개인 설정과 팀 공유 파일을 구분하는 방식으로 운영하는 것이 좋다.

 

지침 파일은 한 번에 완성하지 않는 편이 낫다

처음부터 완벽한 AGENTS.md를 만들려고 하면 대부분 너무 길어진다.

더 좋은 방식은 실제로 AI가 실수한 지점을 기준으로 업데이트하는 것이다.

예를 들어 AI가 npm을 사용했다면 이렇게 추가한다.

- Use pnpm in this repository. Do not use npm or yarn.

 

AI가 라우터 안에 비즈니스 로직을 길게 넣었다면 이렇게 추가한다.

- Keep route handlers thin. Move business logic into service modules.

 

AI가 테스트 없이 작업을 끝냈다면 이렇게 추가한다.

- Run relevant tests when changing business logic. If tests cannot be run, explain why.

 

이런 식으로 작성하면 지침 파일이 실제 프로젝트의 문제를 반영하게 된다.

반대로 인터넷에서 복사한 긴 템플릿을 그대로 넣으면 프로젝트와 맞지 않는 규칙이 섞일 수 있다. 이 부분을 오해하기 쉽다. 지침 파일은 많을수록 좋은 게 아니라, 현재 프로젝트에서 반복되는 실수를 줄일수록 좋은 문서다.

 

정리

AGENTS.md는 AI 코딩 에이전트에게 프로젝트의 작업 규칙을 알려주는 파일이다. Codex에서는 핵심 지침 파일로 쓰이며, 프로젝트 구조, 실행 명령어, 코드 스타일, 주의사항을 적어두는 데 적합하다.

다만 Claude Code는 AGENTS.md가 아니라 CLAUDE.md가 기본이다. 이미 AGENTS.md를 쓰는 프로젝트라면 CLAUDE.md에서 @AGENTS.md로 가져오는 방식이 좋다.

Cursor는 Cursor Rules를 중심으로 보는 것이 좋다. .cursor/rules에 규칙을 나눠두면 작업 범위별로 관리하기 쉽다. 여러 도구를 함께 쓴다면 공통 규칙은 AGENTS.md, Claude 전용 규칙은 CLAUDE.md, Cursor 전용 규칙은 .cursor/rules에 나누는 구성이 현실적이다.

지침 파일에 모든 것을 넣을 필요는 없다.

가장 먼저 넣을 내용은 반복해서 설명하게 되는 것들이다.

• 어떤 명령어를 쓰는지
• 파일을 어디에 만들어야 하는지
• 어떤 코드 스타일을 따라야 하는지
• 어떤 작업은 확인 후 진행해야 하는지
• 어떤 파일은 건드리면 안 되는지

특히 Codex나 Claude Code처럼 터미널에서 명령어를 직접 실행할 수 있는 도구를 쓴다면, 실행 명령어와 금지 명령어를 더 명확하게 적어두는 편이 좋다.

결국 좋은 지침 파일은 긴 문서가 아니라, AI가 같은 실수를 반복하지 않게 만드는 짧고 정확한 작업 기준이다.