AI 코딩 에이전트 제대로 쓰기: AGENTS.md 작성법

최근 개발 방식은 빠르게 바뀌고 있다. 이전에는 ChatGPT에게 코드를 물어보고, 답변을 복사해서 프로젝트에 붙여 넣는 방식이 많았다.
하지만 이제는 Cursor, Claude Code, GitHub Copilot, Codex 같은 AI 코딩 에이전트가 실제 코드베이스를 읽고, 파일을 수정하고, 테스트를 실행하고, PR 단위 작업까지 수행하는 방향으로 발전하고 있다. 이때 중요한 문제가 생긴다

AI는 우리 프로젝트의 규칙을 어떻게 알 수 있을까?

사람 개발자는 README를 읽고, 기존 코드를 보고, 팀 컨벤션을 파악하면서 작업한다.
하지만 AI 에이전트에게는 프로젝트 규칙을 더 명확하게 알려줘야 한다.

이때 사용하는 파일이 바로 `AGENTS.md`다. 쉽게 말해 AI 에이전트를 위한 작업 지침서다.

README에는 보통 프로젝트 소개, 설치 방법, 실행 방법이 들어간다.
반면 AGENTS.md에는 AI가 코드를 수정할 때 지켜야 할 규칙을 적는다.

 

예를 들면 다음과 같다.

- 패키지 매니저는 pnpm을 사용한다.
- 새 파일은 TypeScript로 작성한다.
- any 타입은 되도록 사용하지 않는다.
- 코드 수정 후 pnpm typecheck, pnpm lint, pnpm test를 실행한다.
- 기존 테스트를 삭제하지 않는다.

 

즉, AGENTS.md는 AI에게 “이 프로젝트에서는 이렇게 일해줘”라고 알려주는 문서다.

 

왜 AGENTS.md가 필요할까?

AI 코딩 도구는 점점 똑똑해지고 있지만, 프로젝트마다 다른 규칙까지 자동으로 정확히 알지는 못한다.

예를 들어 어떤 프로젝트는 npm을 쓰고, 어떤 프로젝트는 pnpm을 쓴다.

npm install
// or
pnpm install

둘 다 의존성을 설치하는 명령어지만, 프로젝트에 따라 하나만 맞는 경우가 많다.

또 어떤 팀은 default export를 선호할 수 있고, 다른 팀은 named export만 사용할 수도 있다.

 

AI가 이런 규칙을 모르면 기존 코드 스타일과 다른 코드를 만들 수 있다. 결과적으로 다음과 같은 문제가 생긴다.

• 실행되지 않는 명령어를 사용한다.
• 기존 코드 스타일과 다른 코드를 만든다.
• 테스트 없이 코드를 수정한다.
• 프로젝트 구조와 다른 위치에 파일을 만든다.
• 사용하지 않는 라이브러리를 새로 추가한다.
• 실패하는 테스트를 삭제하려고 한다.

AGENTS.md는 이런 실수를 줄이기 위한 최소한의 안전장치다.

 

AGENTS.md에 무엇을 적어야 할까?

처음부터 길고 복잡하게 작성할 필요는 없다. 오히려 짧고 구체적인 문서가 더 좋다.

AGENTS.md에는 최소한 다음 항목을 넣는 것이 좋다.

1. 프로젝트 개요
2. 기술 스택
3. 자주 사용하는 명령어
4. 코드 작성 규칙
5. 테스트 규칙
6. 금지 사항
7. 작업 완료 전 체크리스트

각 항목은 AI가 실제로 작업할 때 판단 기준으로 사용할 수 있어야 한다.

 

기본 AGENTS.md 예시

프로젝트 루트에 AGENTS.md 파일을 만든다.

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

그리고 다음처럼 작성할 수 있다.

# AGENTS.md
## Project Overview
This project is a TypeScript-based web application.

## Tech Stack
- TypeScript
- React
- pnpm
- Vitest

## Commands
- Install dependencies: `pnpm install`
- Start dev server: `pnpm dev`
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`
- Test: `pnpm test`

## Coding Rules
- Use TypeScript for all new files.
- Do not use `any` unless necessary.
- Follow the existing folder structure.
- Reuse existing components before creating new ones.
- Keep changes focused on the requested task.

## Testing Rules
- Add tests when changing business logic.
- Update tests when behavior changes.
- Do not remove tests just to make the test suite pass.

## Do Not
- Do not use `npm install` or `yarn add`.
- Do not add new dependencies without approval.
- Do not modify generated files.
- Do not change public API contracts without updating tests.

 

좋은 AGENTS.md는 길지 않아도 된다. 대신 구체적이어야 한다.

 

작성시 주의할점

첫 번째, 너무 길게 쓰지 않는다.
처음에는 명령어, 코드 스타일, 테스트 규칙, 금지 사항 정도만 작성해도 충분하다.

 

두 번째, 추상적인 표현을 피한다.

좋은 코드를 작성하세요. ❌

대신 이렇게 적는다.

Do not use `any` unless necessary. ✅

 

세 번째, AI가 마음대로 판단하면 안 되는 부분을 명시한다.

 

네 번째, 실제로 존재하는 명령어만 적는다.

 

AI 코딩 에이전트는 앞으로 개발 과정에서 더 많이 사용될 가능성이 높다.

하지만 AI에게 아무런 지침 없이 작업을 맡기면 프로젝트 규칙과 맞지 않는 코드가 나올 수 있다.

AGENTS.md는 이런 문제를 줄이기 위한 간단하지만 효과적인 방법이다.

정리하면 다음과 같다.

- AGENTS.md는 AI 에이전트를 위한 작업 지침서다.
- README.md와 역할이 다르다.
- 명령어, 코드 스타일, 테스트 규칙, 금지 사항을 구체적으로 적어야 한다.
- 너무 길게 쓰기보다 짧고 명확하게 작성하는 것이 좋다.
- AGENTS.md는 테스트, 린트, CI와 함께 사용할 때 더 효과적이다.

 

AI 코딩 도구를 제대로 쓰고 싶다면, 먼저 프로젝트 루트에 AGENTS.md 파일 하나를 추가해보자.

작은 문서 하나가 AI가 작성하는 코드의 품질을 꽤 많이 바꿀 수 있다.

 

참고자료

 

• https://agents.md/
• https://developers.openai.com/codex/guides/agents-md
• https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot