GitHub Copilot `agents.md` 잘 쓰는 법 ("How to write a great agents.md: Lessons from over 2,500 repositories")

2,500개 저장소 분석으로 드러난 실전 패턴 정리

들어가며

GitHub는 최근 GitHub Copilot Custom Agents 기능을 공개했다.
이제 하나의 범용 AI가 아니라, 역할이 분리된 여러 에이전트를 프로젝트에 둘 수 있다.

• @docs-agent → 문서 전용
• @test-agent → 테스트 전용
• @lint-agent → 스타일/포맷 전용

핵심은 단순하다.

AI를 똑똑하게 만들려 하지 말고,
무엇을 하면 안 되는지 명확히 적어라.

GitHub는 실제로 2,500개 이상의 공개 저장소에 있는 agents.md 파일을 분석했고,
그 결과 “되는 파일”과 “망하는 파일”의 차이가 분명하게 갈렸다.

이 글은 그 핵심만 정리한 실전 가이드다.

---

agents.md는 무엇인가

agents.md는 단순한 프롬프트 파일이 아니다.
AI 에이전트의 운영 매뉴얼이다.

여기에 정의되는 것:

• 에이전트의 직무(페르소나)
• 알고 있어야 할 기술 스택
• 프로젝트 디렉터리 구조
• 실행 가능한 명령어
• 그리고 가장 중요한 경계(Boundaries)

❌ “You are a helpful coding assistant”
✅ “You are a test engineer who writes tests and never modifies source code”

이 차이가 곧 에이전트 품질 차이다.

---

2,500개 repo 분석 결과: 잘 되는 agents.md의 공통점

1️⃣ 명령어를 가장 먼저 쓴다

성공한 agents.md는 설명보다 실행 가능한 커맨드를 앞에 둔다.

npm test
npm run build
pytest -v

• 도구 이름 ❌
• 실제 실행 가능한 명령 + 옵션 ✅

AI는 추상 설명보다 반복 호출 가능한 명령을 기준으로 행동한다.

---

2️⃣ 설명보다 코드 예제가 우선이다

3문단 설명보다 한 개의 실제 코드 예제가 더 효과적이다.

• 좋은 코드 예
• 나쁜 코드 예

AI는 규칙을 “이해”하는 게 아니라 패턴을 모방한다.

---

3️⃣ 경계(Boundaries)가 명확하다

가장 많이 등장했고, 가장 효과적인 패턴은 3단계 경계다.

✅ Always do
⚠️ Ask first
🚫 Never do

예:

• 🚫 src/ 수정 금지
• 🚫 secrets, config, vendor 디렉터리 수정 금지
• ⚠️ DB 스키마 변경은 사전 승인

좋은 에이전트는 자유로운 에이전트가 아니라
잘 묶여 있는 에이전트다.

---

4️⃣ 기술 스택은 반드시 구체적으로

❌ React 프로젝트
✅ React 18 + TypeScript + Vite + Tailwind CSS

버전과 핵심 의존성을 명시하지 않으면
AI는 다른 프로젝트 문맥을 섞어버린다.

---

5️⃣ 상위권 agents.md가 공통으로 다루는 6가지

GitHub 분석 기준, 이 6가지를 다루면 “잘 쓴 파일” 영역에 들어간다.

1. Commands
2. Testing
3. Project structure
4. Code style
5. Git workflow
6. Boundaries

---

GitHub가 권장하는 기본 에이전트 6종

에이전트	역할
docs-agent	문서 생성
test-agent	테스트 작성
lint-agent	스타일/포맷
api-agent	API 엔드포인트
dev-deploy-agent	개발 환경 배포
(확장)	보안, 성능, 로그 분석

공통 원칙:

• 하나의 책임
• 쓰기 가능한 디렉터리 명시
• 절대 건드리면 안 되는 영역 고정

---

핵심 결론

이 문서의 결론은 명확하다.

Copilot 에이전트 품질은
모델 성능이 아니라 agents.md 설계 수준에서 갈린다.

• 프롬프트를 길게 쓰는 게 핵심 ❌
• AI에게 자유를 주는 게 핵심 ❌
• 역할·명령·경계를 명확히 하는 게 핵심 ✅

잘 되는 agents.md는 한 번에 완성되지 않는다.
실패 → 수정 → 구체화를 반복하면서 진화한다.

---

마무리

AI 에이전트는 “대체자”가 아니다.
잘 정의된 자동화된 팀원이다.

가장 먼저 할 일은 단 하나다.

“이 에이전트는
무엇을 절대 하면 안 되는가?”

그 질문에 답하는 순간,
Copilot은 비로소 쓸 만해진다.

---

• 참고 링크: How to write a great agents.md: Lessons from over 2,500 repositories