AGENTS.md

TMT

https://agents.md/

코딩 에이전트를 안내하는 간단하고 오픈된 포맷으로, 2만 개 이상의 오픈소스 프로젝트에서 사용되고 있습니다.

AGENTS.md를 에이전트용 README라고 생각하세요: AI 코딩 에이전트가 프로젝트 작업을 할 때 필요한 컨텍스트와 지침을 제공하는 전용, 예측 가능한 공간입니다.

# AGENTS.md

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible

Why AGENTS.md

README.md 파일은 사람을 위한 것입니다: 빠른 시작, 프로젝트 설명, 기여 지침 등.

AGENTS.md는 이를 보완하여 코딩 에이전트가 필요로 하는 추가적이고 때로는 상세한 컨텍스트(빌드 단계, 테스트, 규칙 등)를 담습니다. 이는 README에 넣기엔 복잡하거나 사람에게는 필요 없는 내용일 수 있습니다.

별도의 파일로 분리한 이유는 다음과 같습니다:

  • 에이전트에게 명확하고 예측 가능한 지침 제공
  • README를 사람 중심으로 간결하게 유지
  • 기존 README와 문서를 보완하는 정확하고 에이전트 중심의 안내 제공

또 다른 독점 파일을 도입하는 대신, 누구나 사용할 수 있는 이름과 포맷을 선택했습니다. 코딩 에이전트를 만들거나 사용하는 분이라면 자유롭게 활용하세요.

하나의 AGENTS.md로 여러 에이전트에서 사용 가능

여러 AI 코딩 에이전트 및 도구 생태계에서 여러분의 에이전트 정의가 호환됩니다:

Codex(OpenAI), Amp, Jules(Google), Cursor, Factory, RooCode 등

예시

# Sample AGENTS.md file

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.

## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

AGENTS.md 사용 방법

  1. AGENTS.md 추가 저장소 루트에 AGENTS.md 파일을 만드세요. 대부분의 코딩 에이전트는 요청하면 자동으로 생성해줍니다.
  2. 중요한 내용 작성 에이전트가 프로젝트를 효과적으로 다룰 수 있도록 도움이 되는 섹션을 추가하세요. 주요 예시:
  • 프로젝트 개요
  • 빌드 및 테스트 명령어
  • 코드 스타일 가이드라인
  • 테스트 지침
  • 보안 고려사항
  1. 추가 지침 작성 커밋 메시지나 PR 가이드라인, 보안 주의사항, 대용량 데이터셋, 배포 단계 등 새 팀원에게 알려줄 내용도 여기에 포함하세요.
  2. 대형 모노레포? 하위 프로젝트별로 AGENTS.md 파일 추가 각 패키지에 별도의 AGENTS.md를 두세요. 에이전트는 디렉터리 트리에서 가장 가까운 파일을 자동으로 읽으므로, 해당 위치의 파일이 우선 적용되고 각 하위 프로젝트마다 맞춤 지침을 제공할 수 있습니다. 예를 들어, OpenAI의 메인 저장소에는 현재 88개의 AGENTS.md 파일이 있습니다.

About

AGENTS.md는 OpenAI Codex, Amp, Jules(Google), Cursor, Factory 등 AI 소프트웨어 개발 생태계의 협업을 통해 탄생했습니다.

어떤 코딩 에이전트를 사용하든 개발자 커뮤니티 전체에 도움이 되는 오픈 포맷으로 유지·발전시키는 데 힘쓰고 있습니다.

FAQ

필수 항목이 있나요?

아니요. AGENTS.md는 표준 Markdown입니다. 원하는 헤딩을 자유롭게 사용하세요. 에이전트는 제공된 텍스트만 파싱합니다.

지침이 충돌하면 어떻게 되나요?

편집 중인 파일과 가장 가까운 AGENTS.md가 우선 적용되며, 명시적인 사용자 채팅 프롬프트가 모든 것을 덮어씁니다.

에이전트가 AGENTS.md에 있는 테스트 명령을 자동으로 실행하나요?

네, 명령을 기재하면 에이전트가 관련 프로그램 검사를 실행하고 실패 시 수정까지 시도합니다.

나중에 업데이트할 수 있나요?

물론입니다. AGENTS.md는 살아있는 문서로 관리하세요.

기존 문서를 AGENTS.md로 옮기려면 어떻게 하나요?

기존 파일명을 AGENTS.md로 변경하고, 하위 호환을 위해 심볼릭 링크를 만드세요:

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
Edit this page
Index

On this Page