AGENTS.md 가이드: 코딩 에이전트(AI 에이전트)를 위한 오픈 소스 "프로젝트 설명" 형식입니다. AGENTS.md 는 "AI 코딩 에이전트"를 위한 오픈 소스 명령 형식입니다. 이는 README의 "에이전트 버전"과 유사하며, 에이전트에게 빌드, 테스트, 코드 사양 및 고려 사항과 같은 주요 정보를 제공하여 에이전트가 코드베이스에서 작업을 보다 안정적으로 수행할 수 있도록 도와줍니다. 사이트에 따르면 많은 오픈 소스 프로젝트가 이 형식을 채택했습니다. 설계 목표는 여러 에이전트와 도구에서 공통적이며 팀과 오픈 소스 리포지토리가 신속하게 구현하는 데 적합합니다.
1. AGENTS.md 란 무엇입니까
1) 포지셔닝: README에 대한 기능 보완 기능인 AI 코딩 에이전트를 위한 문서 문서입니다.
2) 목표: 상담원에게 고정되고 예측 가능한 입구를 제공하여 "상담원이 효율적으로 일하도록 하도록" 컨텍스트와 지침을 중앙 집중화합니다.
3) 형태: 순수 Markdown, 강제 필드 없음; 장기 유지 관리 및 버전 관리를 위해 요청 시 작성합니다.
2. AGENTS.md 가 필요한 이유(README와의 관계)
1) README는 제품 설명, 빠른 시작, 기여 가이드를 강조하는 인간 독자를 대상으로 합니다.
2) AGENTS.md 에이전트 지향적이며 빌드/테스트 명령, 코드 스타일, CI 요구 사항 및 보안 포인트를 강조합니다.
3) 분리의 이점: README를 간결하게 유지하면서 상담원에게 "이것을 보면 작업을 수행할 수 있다"는 전용 문서를 제공합니다.
3. 핵심 디자인 및 생태학적 호환성
1) 개방형 형식: 하위 섹션 제목 및 콘텐츠 구조를 사용하고, 텍스트로 프록시 구문을 분석하고, 독점 구문을 사용하지 않습니다.
2) 다중 에이전트 호환성: 여러 에이전트/도구(예: Codex, Amp, Jules, Cursor, Factory, RooCode 등)에 대한 공식 적응 방향 목록입니다.
3) 우선 순위 규칙: 명령 충돌이 발생하면 대상 파일에 가장 가까운 AGENTS.md 가 적용됩니다. 명시적 사용자 대화 지침은 일반 지침보다 우선합니다.
4) 모노레포 친화적: 하위 팩에 "근처" AGENTS.md 배치하는 것을 지원합니다. 대규모 창고는 레이어의 다양한 하위 프로젝트에 대한 에이전트 설명을 관리할 수 있습니다.
4. 채택 방법(4단계)
1) 파일 추가: 코드베이스의 루트 디렉토리에 AGENTS.md 만듭니다. 필요한 경우 하위 팩에 사본을 넣으십시오.
2) 적용 범위 초점: 프로젝트 개요, 빌드 및 테스트 명령, 코드 스타일, 테스트 사양, 보안 및 규정 준수 포인트.
3) 보충 규칙: 제출 정보 및 PR 사양, 데이터 및 모델 리소스 다운로드, 배포 단계 및 일반적인 함정.
4) 반복 유지 관리: 이를 "살아있는 문서"로 취급하고 CI/종속성/디렉터리 구조가 업데이트되면 업데이트합니다.
5. 사용 가능한 최소 템플릿<
pre class="ql-syntax" spellcheck="false"> # AGENTS.md ## 프로젝트 개요 - 모노레포 + PNPM 작업 공간。 주요 언어는 TypeScript입니다. ## 설정 &; 빌드 - 설치: pnpm install - 개발: pnpm dev - 테스트: pnpm 테스트 - 보푸라기: pnpm 보푸라기 ## 코드 스타일 - TS 엄격 모드; 작은따옴표, 세미콜론 없음; 함수 표현식이 우선합니다. ## 테스트 - .github/workflows의 CI; 모든 사용 사례는 커밋하기 전에 로컬로 전달되어야 합니다. ## PR 규칙 - 제목: [<pkg>] <제목>; 커밋하기 전에 lint를 실행하고 테스트해야 합니다. ## 보안 - .env를 제출하지 마십시오. 키는 웨어하우스 시크릿 또는 로컬 주입을 사용하여 주입됩니다.6. 일반적인 사용 사례
1) 오픈 소스 저장소: 접촉하는 에이전트가 "즉시 테스트"하고 자동으로 빌드/단일 테스트/정적 검사를 수행하도록 합니다.
2) 팀 협업: 에이전트와 사람 간의 마찰을 줄이기 위한 명시적인 "암시적 규칙"(코딩 스타일, 제출 프로세스).
3) 대규모 창고 거버넌스: 하위 프로젝트별로 AGENTS.md 분할하여 가까운 지침과 차별화된 프로세스를 달성합니다.
4) 보안 및 규정 준수: 자동화된 운영의 위험을 줄이기 위해 "업로드 불가능한 데이터/모델"과 보안 레드라인을 명확하게 작성합니다.
7. 구현 제안 및 위험 경고
1) "최소 템플릿"으로 시작하여 빌드, 테스트, 스타일 및 PR 규칙만 작성한 다음 점진적으로 개선합니다.
2) CI에 맞추기: CI에서 AGENTS.md 로 키 명령을 동기화하여 "에이전트는 실행되지만 CI는 실행할 수 없음"을 방지합니다.
3) 명시적 충돌 처리: 파일 상단에 "사용자 명령과 충돌이 있는 경우 사용자 명령이 우선한다"고 작성합니다.
4) 불확실한 진술: "얼마나 많은 프로젝트가 채택되었는지"와 같은 지표에 관해서는 데이터 오독을 방지하기 위해 "사이트의 자체 진술에 따라"를 표시하는 것이 좋습니다.
Q&A 자주 묻는 질문
Q: AGENTS.md 에 대한 필수 필드나 표준 템플릿이 있습니까?
답: 아니요. 프로젝트의 실제 필요에 따라 챕터를 구성하도록 권장하는 일반적인 Markdown 지침입니다.
Q: README로 작업을 어떻게 나누나요?
A: README는 사람들을 위한 것입니다. AGENTS.md 에이전트 지향. 전자는 "무엇/어떻게 시작해야 하는지"에 대해 이야기하고 후자는 "에이전트가 빌드/테스트/사양을 실행하는 방법"에 대해 이야기합니다.
Q: 모노레포는 여러 AGENTS.md 를 어떻게 구성하나요?
A: 일반 설명을 루트 디렉토리에 넣고 가장 가까운 설명을 하위 패키지에 넣습니다. 에이전트는 일반적으로 대상 파일의 가장 가까운 복사본을 읽는 데 우선순위를 둡니다.
Q: 여러 프록시 도구를 지원합니까?
A: 프로젝트 페이지에 따르면 여러 에이전트 및 도구와 호환되도록 설계되었으며 원칙적으로 "하나의 문서, 여러 에이전트 사용 가능"입니다.
