AI 코딩 에이전트에게 실제로 도움이 되는 AGENTS.md를 작성하는 방법

실제 프로젝트에서 AI 코딩 에이전트를 써봤다면, 그것이 잘못된 테스트 명령을 실행하거나, 당신의 포매터를 무시하거나, 이미 있는 헬퍼를 다시 발명하는 순간에 부딪혔을 것입니다. 해결책은 보통 더 똑똑한 모델이 아니라 — 에이전트가 추론할 수 없는 프로젝트별 컨텍스트를 주는 것입니다. 그것이 AGENTS.md 파일의 용도입니다.

AGENTS.md가 무엇인가

AGENTS.md는 코딩 에이전트에게 프로젝트 컨텍스트와 지침을 찾을 예측 가능한 장소를 주는 단순한 개방형 Markdown 형식입니다. OpenAI Codex, Amp, Google Jules, Cursor, Factory 간의 협업으로 시작되었고, 지금은 Linux Foundation 산하의 Agentic AI Foundation이 관리합니다. 25개 이상의 도구가 이를 읽습니다 — Codex, Cursor, VS Code, GitHub Copilot, Aider, Windsurf, JetBrains Junie, Zed, goose를 포함해 — 그리고 6만 개 이상의 오픈소스 저장소에 등장합니다.

사람이 아니라 에이전트를 위해 작성된 README라고 생각하세요: README는 새 기여자에게 프로젝트를 설명하고, AGENTS.md는 에이전트가 그렇지 않으면 잘못 추측할 것들을 알려줍니다. (Claude Code 사용자는 CLAUDE.md를 그 동등물로 알아볼 것입니다. 많은 팀이 둘 다 두거나, 하나를 다른 하나로 심링크합니다.)

어디에 두는가

AGENTS.md를 저장소 루트에 두세요. 모노레포에서는 각 패키지 안에 중첩 파일을 추가하세요 — 에이전트는 디렉터리 트리에서 가장 가까운 파일을 읽으므로, 에이전트가 그 폴더에서 작업할 때 packages/api/AGENTS.md가 루트의 것보다 우선합니다. 이를 통해 Python 서비스와 TypeScript 프런트엔드가 각각 맞춤 지침을 받을 수 있습니다.

무엇을 담을 것인가

형식은 그냥 Markdown입니다 — 원하는 헤딩을 쓰세요. 흔히 유용한 섹션은 다음과 같습니다:

• 빌드 및 테스트 명령 — 근사치가 아니라 정확한 명령
• 코드 스타일 — 포매터, 린터, 그리고 린터가 잡지 못할 관례
• 테스트 지침 — 단일 테스트를 실행하는 법, 변경이 완료되기 전에 통과해야 하는 것
• 보안 고려사항 — 절대 건드리지 말아야 할 파일이나 작업
• 커밋 / PR 관례 — 메시지 형식, 브랜치 명명
• 배포 단계 — 에이전트가 그것을 건드릴 것으로 예상될 때만

최소한의 신호 밀도 높은 예시입니다:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (do NOT run in CI)
- Test a single file: `pnpm vitest run path/to/file.test.ts`
- Lint + typecheck before any commit: `pnpm check`

## Conventions
- Use the existing `db()` helper in `src/lib/db.ts`; never open a raw client.
- Dates are stored as UTC ISO strings. Never use `Date.now()` in tests.

## Do not touch
- `src/generated/**` is codegen output. Edit the schema, then run `pnpm gen`.

없는 것에 주목하세요: 아키텍처 강의도, 폴더 구조 재진술도, "이것은 모범 사례로 빌드된 현대적 웹 앱입니다"도 없습니다. 그것은 의도적입니다.

보통 더 짧은 것이 더 낫다

에이전트에게 거대한 AGENTS.md를 생성해 달라고 하고 싶은 유혹이 있습니다. 저항하세요. InfoQ가 보도한 2026년 ETH 취리히 연구는 이 파일들의 실제 영향을 측정했고 그 효과가 미미하고 엇갈린다는 것을 발견했습니다. LLM이 생성한 컨텍스트 파일은 실제로 작업 성공률을 평균 약 3% 떨어뜨리면서 추론 비용을 20% 넘게 올렸습니다. 사람이 작성한 파일은 적당히 도움이 되었으나 — 성공률에서 대략 4% 향상 — 여전히 에이전트가 더 많은 단계를 밟게 밀어 비용을 최대 약 19%까지 올렸습니다.

그 메커니즘은 시사적입니다: 에이전트는 파일이 말하는 무엇이든 충실히 따르므로, 장황한 문서는 그들에게 당면한 작업에 필요 없는 추가 테스트를 실행하고, 더 많은 파일을 읽고, 품질 검사를 수행하라고 시킵니다. 연구자들의 권고: 자동 생성된 컨텍스트 파일은 아예 건너뛰고, 사람이 작성한 지침은 추론할 수 없는 세부사항 — 에이전트가 스스로 정말로 발견할 수 없는 특정 도구와 커스텀 명령 — 으로 한정하라.

다시 말해, 모든 줄은 당신이 실제로 에이전트가 저지르는 것을 본 구체적인 실수를 방지함으로써 자기 자리를 벌어야 합니다.

작동하는 워크플로

1. 빈 채로 시작하세요. 에이전트가 무언가를 잘못하는 것을 볼 때까지 AGENTS.md를 쓰지 마세요.
2. 이론이 아니라 수정을 추가하세요. 잘못된 테스트 명령을 실행하면, 올바른 것을 추가하세요. 파일을 당신 방식으로 다시 포맷해서 린터가 불평하면, 규칙을 추가하세요.
3. 간결하게 유지하세요. 어떤 줄이 그저 에이전트가 package.json이나 폴더 이름에서 읽을 수 있는 것을 재진술할 뿐이라면, 삭제하세요.
4. 모노레포에는 중첩을 사용하세요 — 각 패키지의 파일이 작게 유지되도록요.
5. 매달 다시 읽으세요. 오래된 지침은 없는 것보다 나쁩니다 — 시대에 뒤떨어진 빌드 명령을 따르는 에이전트는 자신만만하게 실패합니다.

최고의 AGENTS.md 파일은 절대 잊지 않지만 또한 절대 추론하지 않는 그 한 명의 팀원을 위한 간결한 온보딩 치트시트처럼 읽힙니다. 그들이 추측할 수 없는 것들을 적고, 그 외에는 아무것도 적지 마세요.