AGENTS.md 패턴: 에이전트의 행동을 실제로 바꾸는 것

제가 처음 쓴 AGENTS.md는 팀 스타일 가이드를 200줄 그대로 붙여 넣은 것이었습니다. 명명 규칙, 코드 리뷰 체크리스트, 배포 절차, 아키텍처 원칙까지 다 들어 있었습니다. 에이전트는 그중 대부분을 무시했습니다. 지시가 틀려서가 아니라, 그게 운영이 아니라 문서였기 때문입니다.

AGENTS.md에는 정확한 호출 방식을 담은 커맨드 우선 지시, 작업 단위로 나눈 섹션(코딩, 리뷰, 릴리스), 그리고 에이전트가 스스로 검증할 수 있는 명시적인 “완료” 기준이 들어가야 합니다. 사람이 읽을 문서가 아니라 운영 정책을 쓰세요. 에이전트가 반드시 실행해야 할 셸 커맨드, 린터 설정, 테스트 커맨드를 구체적으로 담으세요. 산문 형태의 문단, “주의하세요” 같은 모호한 지시, 순서를 명시하지 않은 채 서로 충돌하는 우선순위는 피하세요. AGENTS.md는 6만 개가 넘는 프로젝트가 채택한 개방형 표준이고, Codex, Cursor, Copilot을 비롯한 여러 에이전트 도구에서 함께 동작합니다.

이 구분은 이 글에 나오는 어떤 개별 패턴보다도 중요합니다. AGENTS.md는 AI 에이전트를 위한 운영 정책이지, 사람을 위한 README가 아닙니다. 에이전트는 여러분이 컨벤셔널 커밋을 쓰는 이유를 이해할 필요가 없습니다. 실행할 정확한 커맨드와 “완료”가 어떤 상태인지만 알면 됩니다.

핵심 요약

AGENTS.md에서 생기는 문제 대부분은 에이전트의 운영 절차 대신 사람용 문서를 쓰는 데서 나옵니다. 효과적인 파일은 커맨드 우선이고(설명이 아니라 정확한 호출 방식), 작업 단위로 정리돼 있으며(코딩, 리뷰, 릴리스 섹션), 완료 조건이 명시돼 있습니다. 어김없이 무시되는 안티패턴은 산문 문단, 모호한 지시(“주의하세요”), 그리고 서로 충돌하는 우선순위입니다. AGENTS.md는 6만 개가 넘는 프로젝트가 채택한 개방형 표준이고 ¹, Codex, Cursor, Copilot, Amp, Devin Desktop 등에서 동작합니다 ².

배경: AGENTS.md는 Linux Foundation 산하의 Agentic AI Foundation이 관리하고 있고 ³, 플래티넘 멤버로 Anthropic, Google, Microsoft, OpenAI가 참여하고 있습니다. 이 글은 실용적인 패턴을 다룹니다. Codex 전용 설정은 Codex 가이드를, Claude Code의 대응물(CLAUDE.md)은 Claude Code 가이드를 참고하세요.

무시되는 것들

아래 패턴들은 에이전트 행동에서 관측 가능한 변화를 전혀 만들어 내지 못했습니다. 각각은 동일한 작업을 지시가 있을 때와 없을 때로 나눠 실행하고, 패턴당 10회 이상 돌려 작업 완료 정확도를 비교해서 확인했습니다. AGENTS.md 파일이 있는 2,500개 이상의 저장소를 분석한 GitHub도 같은 결론에 도달했습니다. “대부분의 에이전트 파일이 실패하는 이유는 너무 모호하기 때문”이라는 것입니다 ¹¹. 아래 패턴들은 측정 가능한 방식으로 정확도를 개선하지 못했습니다.

커맨드 없는 산문 문단

<!-- BAD: Agent skips this -->
We value clean, well-tested code. Our team follows TDD principles
and believes in comprehensive test coverage. Please ensure all
changes are properly tested before submitting.

에이전트는 이걸 읽고 막연한 선호로 표현한 다음, 테스트 없이 코드를 써 내려갑니다. 실행 가능한 지시도, 돌릴 커맨드도, 충족할 임계값도, “제대로 테스트됐다”는 말의 정의도 없기 때문입니다.

모호한 지시

<!-- BAD: "Careful" means nothing to an agent -->
- Be careful with database migrations
- Optimize queries where possible
- Handle errors gracefully

“주의”는 제약이 아닙니다. “가능한 경우”는 트리거 조건이 아닙니다. “우아하게”는 행동 명세가 아닙니다. 이런 문장은 사람끼리 주고받는 안내로는 통해도 에이전트를 향한 지시는 되지 못합니다. 통하는 표현과 비교해 보세요. “마이그레이션을 적용하기 전에 alembic check를 실행한다. 다운그레이드 경로가 없으면 중단한다.”

서로 충돌하는 우선순위

<!-- BAD: Which one wins? -->
- Move fast and ship quickly
- Ensure comprehensive test coverage
- Keep the runtime budget under 5 minutes
- Run the full integration test suite before every commit

에이전트는 이 네 가지를 동시에 만족시킬 수 없습니다. 우선순위를 명시하지 않은 채 지시가 충돌하면, 모델은 검증 단계를 건너뛰고 코드 생성으로 달려갑니다. ICLR 2026 연구(Ambig-SWE)에 따르면 “명시적으로 유도하지 않으면 모델은 심각하게 명세가 부족한 입력에서조차 거의 상호작용하지 않는다”고 합니다. 에이전트가 확인 질문을 던지는 대신 조용히 진행해 버리는 것입니다. 반대로 상호작용하도록 유도하면 명세가 부족한 작업에서 성능이 최대 74%까지 향상됐습니다 ¹². 충돌하는 지시는 우선순위에 번호를 매겨 정리하세요. “우선순위 1: 테스트 통과. 우선순위 2: 5분 이내. 우선순위 3: 빠른 출시.”

강제 수단 없는 스타일 가이드

<!-- BAD: No way to verify compliance -->
Follow the Google Python Style Guide for all code.
Use numpy-style docstrings for public functions.

그 스타일을 강제하는 정확한 린트 커맨드(ruff check --select D나 pylint --rcfile=.pylintrc 같은)를 넣지 않으면, 에이전트에게는 자기 준수 여부를 검증할 수단이 없습니다. 여기서 드러나는 원리는 보편적입니다. 검증 커맨드가 없는 지시는 규칙이 아니라 제안일 뿐입니다.

통하는 것들

아래 패턴들은 에이전트 행동에 일관되고 측정 가능한 변화를 만들어 냅니다.

커맨드 우선 지시

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

커맨드에는 모호함이 없습니다. 에이전트는 무엇을 실행하고 어떤 인자를 넘길지 정확히 알고, 종료 코드를 확인해 성공 여부를 검증할 수 있습니다. AGENTS.md의 모든 지시는 “이게 제대로 됐다는 걸 증명하는 커맨드는 무엇인가”라는 질문에 답해야 합니다.

완료 조건 정의

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

완료 조건을 명시하면 가장 흔한 실패 유형, 즉 에이전트가 검증도 없이 “완료”라고 보고하는 상황을 없앨 수 있습니다. “완료”가 특정 종료 코드로 정의돼 있으면, 에이전트는 완료를 보고하기 전에 각 검사를 실행합니다. 이 정의가 없으면 “완료”는 “다 한 것 같아요”라는 뜻이 되고, 이는 에이전트가 만들어 내는 버그의 흔한 원인입니다.

작업 단위로 나눈 섹션

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions
- Test command: `pytest tests/ -v -k "test_<module>"`

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`
- List changed files: `git diff --name-only HEAD~1`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`
- Tag: `git tag -a v<version> -m "Release v<version>"`

작업 단위로 정리된 파일이면 에이전트가 지금 하는 일에 맞춰 관련 지시만 골라 쓸 수 있습니다. 평평한 목록은 맥락과 상관없이 모든 지시를 파싱하게 만듭니다. “언제…” 형태의 접두사는 에이전트가 작업 맥락을 추론하는 방식과 그대로 맞물립니다.

에스컬레이션 규칙

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- If you encounter merge conflicts: stop and show the conflicting files
- Never: delete files to resolve errors, force push, or skip tests

에스컬레이션 규칙이 없으면 에이전트는 막혔을 때 점점 더 창의적인 우회로 빠집니다. 락 파일을 지우거나, 검사를 우회하거나, 실패를 조용히 무시하는 식입니다. “절대 하지 말 것” 목록은 에스컬레이션 경로만큼이나 중요합니다. 파괴적인 복구 패턴을 명시적으로 금지해 두면 최악의 실패를 막을 수 있습니다.

모노레포를 위한 디렉터리 스코프

AGENTS.md는 명세의 핵심 기능으로 계층적 스코프를 지원합니다 ². 작업 디렉터리에 더 가까운 파일이 우선합니다.

/repo/AGENTS.md                        ← Project-wide rules
  └─ /repo/services/AGENTS.md          ← Service defaults
      ├─ /repo/services/api/AGENTS.md  ← API-specific rules
      └─ /repo/services/web/AGENTS.md  ← Frontend-specific rules

루트 수준 지시는 더 깊은 파일과 이어 붙여집니다. Codex는 프로젝트 루트에서 현재 작업 디렉터리까지 거슬러 내려가며 경로에서 발견한 모든 AGENTS.md를 결합합니다 ⁴. 다만 명세 자체는 가장 가까운 파일이 우선한다고 규정하므로, 다른 도구는 계층을 다르게 해석할 수도 있습니다 ². OpenAI 자신의 codex 저장소도 이 방식을 실천하고 있습니다. 루트 파일 아래에 중첩된 AGENTS.md를 함께 담고 있습니다 ⁴.

Codex에서는 어느 계층에서든 AGENTS.override.md를 써서 상위 지시를 확장이 아니라 대체할 수도 있습니다 ⁴. 이 오버라이드 메커니즘은 Codex 전용이고, 다른 도구는 구현하지 않습니다.

<!-- /repo/services/payments/AGENTS.override.md (Codex only) -->
# Payment Service Rules (OVERRIDE)

This service has additional security requirements.
All changes require: `bandit -r . -ll` passing with zero findings.
No dependency updates without explicit approval.
Test with: `pytest -v --tb=long -x` (fail fast, full tracebacks)

오버라이드를 쓸 때: 릴리스 프리즈, 인시던트 대응 모드, 또는 프로젝트 전역 기본값보다 우선하는 보안 제약이 걸린 서비스입니다.

도구 간 호환성

AGENTS.md는 6만 개가 넘는 프로젝트에 채택됐고 ¹, 주요 AI 코딩 도구가 모두 인식합니다. 같은 파일이 각 생태계에서 어떻게 동작하는지 아래에 정리했습니다(표는 2026년 8월 기준으로 검증했습니다).

팀에서 여러 도구를 쓴다면: AGENTS.md를 정본으로 쓰세요. 도구별 파일(CLAUDE.md, .cursorrules)은 관련 섹션을 가져오거나 그대로 반영하도록 만드세요. 서로 어긋나기 마련인 병렬 지시 세트를 따로 유지하지 마세요.

작성 순서: 무엇부터 넣을까

AGENTS.md를 처음부터 쓴다면 아래 우선순위대로 섹션을 추가하세요. 각 층은 앞선 층 위에 쌓입니다.

1. 빌드와 테스트 커맨드. 에이전트가 쓸모 있는 일을 하기 전에 먼저 필요합니다
2. 완료의 정의. “다 한 것 같아요” 식의 거짓 완료를 막아 줍니다
3. 에스컬레이션 규칙. 막혔을 때 나오는 파괴적인 우회를 막아 줍니다
4. 작업 단위 섹션. 작업마다 무관한 지시를 파싱하는 부담을 줄여 줍니다
5. 디렉터리 스코프(모노레포 전용). 서비스별 지시를 격리해 줍니다

스타일 취향은 앞의 네 가지가 자리 잡을 때까지 미루세요. 대부분의 AGENTS.md가 실패하는 이유는 스타일 지침으로 시작해서 끝내 커맨드까지 가지 못하기 때문입니다.

AGENTS.md 테스트하기

에이전트가 실제로 지시를 읽고 따르는지 확인해 보세요.

# Codex: Show the full instruction chain
codex --ask-for-approval never "Summarize your current instructions"

# Codex: Generate a scaffold (slash command inside an active session)
# Type /init at the Codex prompt, not as a shell command
codex  # then type: /init

# Claude Code: Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
codex --ask-for-approval never "What is your definition of done?"

결정적인 시험: 에이전트에게 여러분의 빌드 커맨드를 설명해 보라고 하세요. 그대로 재현하지 못한다면 그 지시는 읽히지 않고 있거나, 컨텍스트에 담아 두기엔 너무 장황한 것입니다. 긴 AGENTS.md는 컨텍스트 윈도에 의해 잘려 나갑니다. 각 섹션을 50줄 이내로 유지하고, 가장 중요한 지시를 앞쪽에 배치하세요.

자주 묻는 질문

AGENTS.md 파일은 얼마나 길어야 합니까?

제 경험칙은 각 섹션을 50줄 이내, 파일 전체를 150줄 이내로 유지하는 것입니다. 그 바탕에 있는 원칙은 Marmelab의 에이전트 경험 가이드에서 왔습니다. 코딩 에이전트가 매 세션 시작 때 이 파일을 읽기 때문에 “짧고 요점만” 담아야 한다는 것입니다 ¹³. 다만 구체적인 줄 수는 제 기준이지 그쪽 주장이 아닙니다. Codex는 기본값으로 32 KiB 제한(project_doc_max_bytes)을 적용합니다 ⁴. 긴 파일은 컨텍스트 윈도에 잘려 나가니, 가장 중요한 지시인 커맨드와 완료 조건을 스타일 취향보다 앞에 두세요.

AGENTS.md가 도구별 지시 파일을 대체합니까?

아닙니다. AGENTS.md는 CLAUDE.md, .cursor/rules 같은 도구별 파일과 나란히 동작합니다. AGENTS.md를 정본으로 쓰고, 거기서 관련 섹션을 도구별 파일로 반영하세요. AGENTS.md의 패턴(커맨드 우선, 완료 조건 명시)은 도구와 상관없이 어떤 지시 파일에서도 통합니다.

에이전트가 제 AGENTS.md를 무시하면 어떻게 합니까?

에이전트에게 빌드 커맨드를 설명해 보라고 해서 확인하세요. 그대로 재현하지 못한다면 그 파일은 너무 장황하거나(내용이 컨텍스트 밖으로 밀려남), 너무 모호하거나(에이전트가 실행 가능한 지시를 뽑아내지 못함), 아예 탐색되지 않고 있는 것입니다(파일 위치와 도구 문서를 확인하세요). 2,500개 이상의 저장소를 분석한 GitHub도 대부분의 에이전트 파일이 너무 모호해서 실패한다고 밝혔습니다 ¹¹.

핵심 정리

개인 개발자를 위해:

• 산문을 커맨드로 바꾸세요. 모든 지시는 무언가를 실행해서 검증할 수 있어야 합니다.
• 완료를 명시적으로 정의하세요. “완료”는 특정 종료 코드지 느낌이 아닙니다.
• 에이전트에게 AGENTS.md를 읊어 보게 해서 테스트하세요. 읊지 못하는 건 따르지도 않습니다.

팀을 위해:

• AGENTS.md를 단일 진실 공급원으로 삼으세요. 도구별 파일로는 반영하되, 병렬 사본을 따로 유지하지 마세요.
• 카테고리(스타일, 테스트, 배포)가 아니라 작업(코딩, 리뷰, 릴리스) 단위로 정리하세요.
• 에스컬레이션 규칙을 넣으세요. 없으면 막힌 에이전트가 여러분이 반기지 않을 방식으로 즉흥 대응합니다.
• 모노레포에서는 디렉터리별로 스코프를 나누세요. 서비스별 규칙이 전역 지시를 오염시켜서는 안 됩니다.

참고 자료