코딩 에이전트는 코드를 작성하기 전에 레포지토리를 읽으며, 가장 먼저 읽는 파일은 AGENTS.md입니다. 이는 Codex CLI, Cursor, Aider, OpenHands 및 점점 더 많은 다른 도구들이 동의한 공개 컨벤션으로, 단일 컨텍스트 파일이 모든 에이전트에서 작동하도록 합니다. API 개발 팀의 경우, 이 파일은 실제 로컬 서버에서 올바른 테스트를 실행하는 에이전트와 엔드포인트를 환각하고 손상된 클라이언트를 배송하는 에이전트의 차이를 만듭니다.
이 가이드에서는 AGENTS.md가 무엇인지, API 팀이 이를 프로덕션 코드처럼 취급해야 하는 이유, OpenAPI 우선 레포지토리에 중요한 섹션, 구체적인 예시, 그리고 API가 발전함에 따라 파일을 최신 상태로 유지하는 방법을 다룹니다. 마지막에는 에이전트의 계약 테스트 흐름이 실제 사양에 기반을 두도록 Apidog와 함께 사용합니다.
TL;DR
AGENTS.md는 레포지토리 루트에 있는 일반 마크다운 파일로, 코딩 에이전트에게 프로젝트에서 코드를 탐색, 빌드, 테스트 및 배포하는 방법을 알려줍니다.- 이 컨벤션은 개방적이며 Codex CLI, Cursor, OpenHands, Aider, Claude Code 및 기타 에이전트 도구에서 지원됩니다.
- API 팀의 경우, 가장 효과적인 섹션은 빌드 명령, OpenAPI 사양 경로, 목업 서버 엔드포인트, 계약 테스트 명령, 인증 설정 및 "건드리지 말아야 할" 영역입니다.
- 짧게 유지하세요. 200~400줄이면 충분합니다. 이보다 길면 에이전트가 중요한 부분을 건너뛸 것입니다.
- 에이전트가 컨텍스트(
AGENTS.md)와 실행 가능한 계약(OpenAPI 사양)을 모두 갖도록 Apidog 컬렉션과 함께 사용하세요.
AGENTS.md의 실제 모습
AGENTS.md는 레포지토리 루트에 커밋하는 마크다운 파일입니다. 코딩 에이전트는 코드베이스와 처음 접촉할 때 이 파일을 찾고, 그 내용을 프로젝트 작동 방식에 대한 권위 있는 브리핑으로 취급합니다. 이 컨벤션은 OpenAI의 Codex CLI 내부에서 시작되었으며, 다른 도구들도 동일한 파일을 읽을 수 있도록 공개 표준으로 발표되었습니다. 올해 기준으로 Codex CLI, Cursor, Aider, Claude Code, OpenHands, Sourcegraph Cody 및 여러 소규모 에이전트가 모두 이 파일을 읽습니다.
세 가지가 이 파일을 유용하게 만듭니다:
- 하나의 파일, 모든 에이전트. 컨텍스트를 한 번 작성하면 팀의 모든 에이전트가 이를 사용합니다. 도구별 설정 불일치가 없습니다.
- 일반 마크다운. DSL, 스키마, 빌드 단계가 없습니다. 엔지니어는 다른 문서처럼 편집합니다.
- 설명하는 코드 옆에 존재합니다. 빌드 스크립트가 변경될 때, 파일도 동일한 PR에서 변경됩니다. 변경 사항은 diff를 통해 리뷰어와 에이전트에게 가시화됩니다.
가장 가까운 사촌은 Anthropic의 Claude Code가 읽는 CLAUDE.md입니다. 두 형식은 크게 중복되며, 많은 프로젝트에서 AGENTS.md를 CLAUDE.md에 심볼릭 링크하여 두 도구가 추가 설정 없이 작동하도록 합니다. Codex 팀과 Anthropic은 향후 형식 호환성을 유지하기로 공개적으로 합의했습니다.
API 개발 팀이 다른 팀보다 이 파일을 더 필요로 하는 이유
API 팀은 어색한 교차점에 있습니다. 코드는 작고, 계약은 방대하며, 둘 중 하나라도 잘못되면 모든 다운스트림 클라이언트에게 그 결과가 즉시 나타납니다. openapi.yaml에 사양이 있다는 것을 모르는 에이전트는 훈련 데이터에서 기억하는 응답 형태로부터 타입을 다시 작성할 것입니다. 계약 테스트 명령을 모르는 에이전트는 컴파일은 되지만 클라이언트 SDK 파이프라인을 깨뜨리는 코드를 커밋할 것입니다.
API 레포지토리를 위한 잘 작성된 AGENTS.md는 네 가지 역할을 합니다:
- 사양을 진실의 원천으로 고정합니다. 모든 변경 사항은 OpenAPI 또는 GraphQL 스키마에서 시작하여 끝납니다. 에이전트는 사양을 먼저 업데이트하고, 그 다음 타입을 재생성하는 법을 배웁니다.
- 로컬 서버의 이름을 지정합니다. 로컬 목업 서버나 실제 서버를 부팅하는 에이전트는 Stack Overflow 스니펫이 아닌 테스트를 위한 올바른 URL을 선택합니다.
- 의도별 테스트 명령을 나열합니다. "단위 테스트 실행"은 "계약 테스트 실행"이나 "스테이징 환경에 대한 통합 테스트 실행"과 같지 않습니다.
- 금지된 경로를 명시합니다. 생성된 SDK 코드, 서드파티 클라이언트 래퍼 및 마이그레이션 파일은 종종 편집 가능해 보이지만 실제로는 그렇지 않습니다.
이 파일이 이 네 가지 역할을 수행할 때, 에이전트의 결과물은 README를 건너뛴 주니어 개발자처럼 보이지 않고, 팀원처럼 보이기 시작합니다.
API 레포지토리에 적합한 구조
AGENTS.md는 필수 스키마가 없습니다. 커뮤니티는 잘 조정된 대부분의 파일에 나타나는 몇 가지 섹션에 대해 합의했습니다. API 팀의 경우, 아래 순서가 강력한 기본값입니다.
1. 프로젝트 요약 (3-5줄)
API가 무엇을 하는지, 누가 소비자인지, 그리고 서버가 어떤 언어와 프레임워크에서 실행되는지 명시합니다. 사실에 기반하여 작성합니다.
# Project: Payments API
Internal payments service for the Acme product line. Customers are
mobile, web, and partner backends. Server is Go 1.23 on Echo, Postgres
17 for storage, and a Redis-backed idempotency layer.
이 블록은 에이전트에게 어떤 언어를 기본으로 할지, 어떤 관용구를 따를지, 그리고 잘못된 응답 형태를 배포했을 때 어떤 클라이언트가 깨질지를 알려줍니다.
2. 빠른 시작 명령
에이전트가 지속적으로 실행할 5~10가지 명령입니다. 항상 명령을 포함하고, 위키로 연결하지 마세요.
## Commands
| Intent | Command |
|--------|---------|
| Install deps | `make deps` |
| Run server locally | `make dev` (binds 127.0.0.1:8080) |
| Run unit tests | `make test` |
| Run contract tests against the local mock | `make contract` |
| Lint | `make lint` |
| Regenerate clients from spec | `make codegen` |
| Apply migrations | `make migrate` |
명령이 작동하기 위해 환경 변수가 필요한 경우, 환경 변수 이름을 옆에 작성하세요. 에이전트는 변수를 내보내는 데 능숙하지만, 추측하는 데는 서툽니다.
3. OpenAPI / GraphQL 사양 섹션
이 섹션은 API 레포지토리에서 가장 중요한 부분입니다. 사양이 어디에 있는지, 사양이 생성된 코드와 어떻게 관련되는지, 그리고 편집 흐름의 방향을 에이전트에게 알려줍니다.
## Source of truth
- The spec is at `apis/payments/openapi.yaml`.
- Generated clients live in `gen/clients/{go,ts,python}` and MUST NOT be hand-edited.
- The generation pipeline is `make codegen`. Run it after every spec change
and commit the regenerated clients in the same PR.
- Spec changes flow: spec -> `make codegen` -> server handler updates ->
contract tests -> ship.
이 블록 하나만으로 에이전트가 타입 불일치를 "수정"하기 위해 생성된 클라이언트를 편집하고, 다음 코드 생성 실행 시 변경 사항이 지워지며, 며칠 후 빌드가 알 수 없는 이유로 중단되는 종류의 버그를 제거할 수 있습니다.
4. 목업 서버 및 Apidog 연결
목업 서버를 실행한다면 (그리고 실행해야 합니다), 그 이름을 지정하세요. URL, 읽어오는 사양, 그리고 시작 방법을 나열하세요.
## Local servers
- Real server: `make dev` -> `http://127.0.0.1:8080`
- Apidog mock server: `make mock` -> `http://127.0.0.1:4010`
- The mock reads from the same `openapi.yaml` and replays saved examples
from the Apidog collection at `apis/payments/apidog/`.
여기가 Apidog가 파일 내에서 그 자리를 차지하는 곳입니다. 목업 서버, 사양, 저장된 요청 예시가 합쳐져 에이전트가 실제 백엔드에 호출을 소모하지 않고도 실행할 수 있는 계약을 형성합니다. 기본 워크플로우에 대해서는 Postman 없이 API 테스트 가이드와 함께 사용하세요.
5. 인증 및 비밀
에이전트에게 API가 어떻게 인증하는지, 어떤 환경 변수가 무엇을 포함하는지 알려줍니다. 실제 비밀 정보를 파일에 절대 넣지 마세요.
## Auth
- Production uses OAuth 2 client credentials issued by Auth0.
- Local dev uses a static dev token; export `DEV_TOKEN` from `.env.local`.
- The Apidog collection uses the same env var names so the mock and the
real client behave identically.
- Tokens MUST NOT be committed; `.env.local` is in `.gitignore`.
6. 테스트 전략
테스트 계층의 순위를 매기세요. 에이전트는 나열된 순서대로 테스트를 실행할 것입니다.
## Testing
1. `make test` for unit tests. Fast, run on every change.
2. `make contract` for OpenAPI contract tests against the mock. Run before
any spec change is merged.
3. `make integration` for end-to-end tests against a local server with a
real Postgres. Run before merging to main.
4. Staging soak runs nightly via GitHub Actions; not a local command.
7. 건드리지 말아야 할 목록
생성된 코드, 벤더링된 종속성, 마이그레이션은 거의 항상 여기에 속합니다.
## Do not edit by hand
- `gen/**` (regenerated by `make codegen`)
- `vendor/**` (managed by `go mod vendor`)
- `migrations/*.up.sql` past the first unapplied migration
- `apis/payments/openapi.yaml` schema field names without owner sign-off
8. 내부 스타일
3~5가지 규칙을 작성합니다. 그 이상이면 에이전트가 잘못된 규칙을 선택할 것입니다.
## Conventions
- Errors return RFC 7807 problem JSON; never bare strings.
- Use snake_case in JSON, camelCase in Go, PascalCase in TS clients.
Codegen handles the mapping.
- Idempotency keys are required on all POST endpoints that create resources.
- New endpoints require a contract test that exercises both 200 and 4xx paths.
구체적인 예시: 90줄로 작업을 처리하는 파일
800줄을 작성하고 싶은 유혹을 참으세요. 아래 파일은 실제 API 서비스를 90줄의 마크다운으로 다루며, 어떤 주요 에이전트라도 생산적으로 작업하기에 충분합니다.
# Project: Payments API
Internal payments service for the Acme product line. Go 1.23, Echo,
Postgres 17, Redis for idempotency. Consumers are mobile, web,
and partner backends.
## Commands
| Intent | Command |
|--------|---------|
| Install | `make deps` |
| Run server | `make dev` |
| Unit tests | `make test` |
| Contract tests | `make contract` |
| Lint | `make lint` |
| Regen clients | `make codegen` |
| Migrate DB | `make migrate` |
## Source of truth
- Spec: `apis/payments/openapi.yaml`
- Generated clients: `gen/clients/{go,ts,python}` (do not edit)
- Edit flow: spec -> `make codegen` -> handler -> contract tests -> ship
## Local servers
- Real server: `make dev` (`http://127.0.0.1:8080`)
- Apidog mock: `make mock` (`http://127.0.0.1:4010`)
- Apidog collection: `apis/payments/apidog/`
## Auth
- Production: Auth0 OAuth 2 client credentials.
- Local dev: static `DEV_TOKEN` from `.env.local`.
## Testing order
1. `make test`
2. `make contract`
3. `make integration`
## Do not edit by hand
- `gen/**`, `vendor/**`
- Applied migrations in `migrations/`
- Spec field names without owner approval
## Conventions
- RFC 7807 problem JSON for errors
- snake_case JSON, codegen handles language mapping
- Idempotency keys required on POST creates
- Every new endpoint ships with a contract test
이 정도면 충분합니다. 에이전트가 동일한 잘못된 선택을 두 번 할 때만 섹션을 추가하세요.
파일을 최신 상태로 유지하기
오래된 AGENTS.md는 파일이 없는 것보다 더 나쁩니다. 에이전트는 그것을 믿고 더 이상 작동하지 않는 빌드 명령에 기반하여 코드를 배포할 것입니다.
세 가지 습관이 파일을 최신 상태로 유지합니다:
- 프로덕션 코드처럼 다루세요. 변경 사항은 다른 PR과 동일한 검토 과정을 거칩니다. 리뷰어는 명령 목록이 실제
Makefile과 일치하는지 확인합니다. - CI에 연결하세요. 명령 테이블을 파싱하고 각 명령을 새로 체크아웃된 환경에서 실행하는 짧은 스크립트는 불일치를 빠르게 잡아냅니다. 대부분의 팀은 이 스크립트를 Bash 30줄 정도로 작성합니다.
- 동일한 PR에서 업데이트하세요. 새로운 테스트 명령을 추가할 때, 나중에
AGENTS.md를 업데이트하겠다고 약속하지 마세요. 지금 업데이트하세요. 비용은 2분이지만, 건너뛸 경우 에이전트 혼란으로 2주가 걸릴 수 있습니다.
AGENTS.md를 위한 런타임 계약으로서의 Apidog
AGENTS.md는 에이전트에게 컨텍스트를 제공합니다. OpenAPI 사양은 에이전트에게 계약을 제공합니다. Apidog는 이 둘을 연결합니다. 사양을 읽고, AGENTS.md에 나열된 URL에서 로컬 목업을 실행하며, 테스트를 위해 저장된 요청 예시를 재생하고, 에이전트가 실제 백엔드에 크레딧을 소모하지 않고 실제 응답을 볼 수 있도록 합니다.
작동하는 패턴:
apis/<서비스>/openapi.yaml및apis/<서비스>/apidog/(내보내진 컬렉션)를 커밋합니다.AGENTS.md에 목업 URL과make mock명령을 나열합니다.- 에이전트는 저장된 예시에 대한 빠른 테스트를 위해
make contract를 실행합니다. - 사양이 변경되면 에이전트는 클라이언트를 재생성하고, 계약 스위트를 실행한 다음 실제 서버를 건드립니다.
실제 API를 사용한 Apidog 목업 워크플로우에 대한 더 심층적인 설명은 서비스 API 대신 모델 API에 동일한 패턴을 적용한 DeepSeek V4 API 가이드를 참조하세요.
API 팀이 흔히 저지르는 실수
수십 개의 파일을 검토한 결과, 동일한 다섯 가지 문제가 나타납니다:
- 나열하는 대신 링크하기. "빌드 명령은 위키를 참조하세요." 에이전트는 위키를 탐색하지 않습니다. 명령을 인라인으로 넣으세요.
- 마케팅성 문구. "저희의 세계적 수준의 API 플랫폼은 ...을 가능하게 합니다." 에이전트에게 홍보가 필요하지 않습니다. 사실을 명시하세요.
- 오래된 명령. 3월에 고장 난 명령이 4월에도 파일에 남아 있습니다. CI를 연결하여 이를 잡아내세요.
- 사양 섹션 누락. 가장 유용한 단일 블록입니다. 항상 포함하세요.
- 건드리지 말아야 할 목록 부재. 에이전트가 생성된 코드를 편집합니다. 다음 코드 생성 실행 시 편집 내용이 지워집니다. 빌드가 중단됩니다. 반복됩니다.
시작할 기준선이 필요하다면, 위 예시를 레포지토리에 복사하고, 프로젝트 요약을 편집하고, 명령 테이블을 조정하세요. 20분 안에 사용 가능한 파일을 배포할 수 있습니다.
FAQ
AGENTS.md와 CLAUDE.md는 동일한가요? 형식은 호환됩니다. 대부분의 팀은 둘 중 하나를 진실의 원천으로 삼고 다른 하나를 심볼릭 링크합니다. Anthropic과 OpenAI는 컨벤션의 상호 운용성을 유지하기 위해 공개적으로 합의했습니다.
파일을 어디에 두어야 하나요? 항상 레포지토리 루트에 두세요. 일부 에이전트는 하위 디렉토리 내의 중첩된 AGENTS.md 파일도 읽으며, 이는 모노레포에 유용합니다. 하나의 루트 레벨 파일로 시작하고, 단일 루트 파일이 너무 길어질 때만 하위 디렉토리 파일을 추가하세요.
길이는 얼마나 되어야 하나요? 200~400줄이 적절합니다. 그 이상이면 에이전트가 섹션을 건너뛰기 시작합니다. 더 깊은 내용이 필요하다면, 한 줄 요약과 함께 별도의 문서로 연결하세요.
코드 샘플을 포함해야 하나요? 짧은 것은 예, 긴 것은 아니요. 전체 예시는 테스트용으로 남겨두세요. 에이전트도 테스트를 읽습니다. GPT-5.5 무료 Codex 가이드는 Codex가 예시 테스트를 추가적인 신호로 어떻게 활용하는지 다룹니다.
에이전트는 매 차례마다 파일을 다시 읽나요? 대부분의 에이전트는 세션 시작 시 읽고 캐시합니다. 일부는 큰 파일 변경 후에 다시 읽습니다. 주요 편집을 한 경우 에이전트 세션을 다시 시작하는 것이 가장 안전한 방법입니다.
파일이 작동하는지 어떻게 테스트하나요? 다른 컨텍스트 없이 새 에이전트 세션을 실행하고, 작은 작업("POST /payments에 422 응답 추가")을 주고, 에이전트가 무엇을 하는지 관찰하세요. 사양을 읽고, make codegen을 실행하고, 계약 테스트를 작성한다면 파일은 제 역할을 하는 것입니다.