agents.md
무엇인가
AGENTS.md는 저장소에 두는 에이전트용 안내 문서 형식이다. 사람이 읽는 README와 별도로, 코딩 에이전트가 프로젝트 맥락과 작업 지침을 예측 가능한 위치에서 찾도록 만든다. 개발 환경, 테스트, PR처럼 반복되는 작업 영역을 규율한다.
어떻게 동작하나
동작 방식은 파일 기반이다. 저장소에 AGENTS.md를 두고 마크다운 섹션으로 규칙을 적는다. README 예시는 Dev environment tips, Testing instructions, PR instructions를 포함하며, 패키지 탐색·설치·테스트·린트·PR 제목 형식 같은 구체 명령과 절차를 담는다. README는 훅이나 슬래시 명령을 정의하지 않고, 에이전트가 참조하는 규칙 파일 자체로 동작한다.
무엇과 다른가
프롬프트를 매번 직접 작성하거나 도구별 설정 파일에 분산하는 방식과 달리, AGENTS.md는 단순하고 공개된 공통 형식이다. 프로젝트 루트의 한 파일에 개발 환경·테스트·PR 규칙을 모아 두므로, 에이전트가 매 작업마다 같은 맥락을 다시 설명받지 않아도 된다. 특정 에이전트 전용 형식이 아니라 여러 코딩 에이전트가 읽을 수 있는 안내 문서를 지향한다.
어떻게 쓰나
사용하려면 프로젝트에 AGENTS.md 파일을 추가하고 마크다운으로 규칙을 작성한다. README의 최소 예시처럼 Dev environment tips, Testing instructions, PR instructions 섹션을 두고 실제 명령과 조건을 적는다. 별도 설치 명령은 필요하지 않으며, 저장소에 파일을 두는 것이 첫 사용이다.
전제와 한계
AGENTS.md를 인식하는 코딩 에이전트에서 동작한다. 지원 범위와 로드 방식은 각 에이전트 구현에 달려 있으며, 이 형식 자체가 규칙 준수를 강제하는 실행 엔진은 아니다. README는 웹사이트 실행을 위한 pnpm install과 pnpm run dev를 안내하지만, 이는 AGENTS.md 규칙 적용과 별개다.
유사 스킬
- agents-mdAGENTS.md 한 파일로 시니어 엔지니어 행동 규율을 주입한다. 아첨 억제, 범위 밖 리팩터링 금지, 검증 루프 강제 규칙을 담는다.
- doxAGENTS.md 계층을 루트부터 편집 대상 영역까지 순회해 지역 규칙을 읽고, 수정 후 해당 문서를 갱신하도록 절차를 주입하는 규칙 파일이다.
- CLAUDE.md코딩 에이전트가 추측 대신 코드를 쓰고, 테스트를 건너뛰지 않으며, 완료 기준과 보고 화법을 지키도록 세션 시작마다 주입되는 단일 CLAUDE.md 규칙 파일이다.
- SwiftAgentsSwift·SwiftUI 프로젝트에서 AI가 생성한 코드가 구식 API를 쓰거나 반복되는 실수를 저지르지 않도록 AGENTS.md에 규칙을 담아 주입하는 스킬 파일이다.
- guard-skills코딩 에이전트가 만든 코드·테스트·문서를 커밋 전에 검토하는 가드 스킬 묶음이다. Skills CLI로 설치해 diff 단위로 적용한다.