2,500개 이상의 공개 저장소에 있는 agents.md를 분석해, 잘 작동하는 에이전트 파일의 공통 요소(명확한 역할, 실행 가능한 명령, 구체적 예시, 경계 설정, 스택 명시 등)를 정리하고, 첫 에이전트 작성법과 추천 에이전트 템플릿을 소개한다.
우리는 최근 새로운 GitHub Copilot 기능을 출시했습니다. 바로 agents.md 파일에 정의하는 커스텀 에이전트입니다. 하나의 범용 어시스턴트 대신, 이제는 전문 인력 팀을 만들 수 있습니다. 예를 들어 기술 문서를 쓰는 @docs-agent, 품질 보증을 맡는 @test-agent, 보안 분석을 수행하는 @security-agent처럼요. 각 agents.md 파일은 프론트매터(frontmatter)와 커스텀 지시사항으로 정의하는 에이전트 페르소나(persona) 역할을 합니다.
agents.md는 모든 구체사항을 정의하는 곳입니다. 에이전트의 페르소나, 정확히 알아야 할 기술 스택, 프로젝트의 파일 구조, 워크플로, 실행할 수 있는 명시적인 커맨드까지요. 또한 코드 스타일 예시를 제공하고—무엇보다도—하지 말아야 할 일을 명확히 경계선으로 설정하는 곳이기도 합니다.
문제는? 대부분의 에이전트 파일은 너무 모호해서 실패합니다. “당신은 도움이 되는 코딩 어시스턴트입니다”는 작동하지 않습니다. “당신은 React 컴포넌트 테스트를 작성하는 테스트 엔지니어이며, 다음 예시를 따르고, 절대 소스 코드는 수정하지 않습니다”는 작동합니다.
저는 공개 저장소에 있는 2,500개 이상의 agents.md 파일을 분석하여 개발자들이 agents.md를 어떻게 사용하는지 이해하려 했습니다. 분석 결과, 무엇이 잘 작동하는지에 대한 명확한 패턴이 드러났습니다. 에이전트에 구체적인 직무/페르소나, 실행할 정확한 커맨드, 지켜야 할 명확한 경계, 따라야 할 좋은 출력 예시를 제공하는 것이 핵심이었습니다.
성공한 파일들은 무엇이 달랐을까요?
2,500개 이상의 agents.md 파일을 분석해 보니, 실패하는 것과 성공하는 것 사이에 뚜렷한 차이가 있었습니다. 성공하는 에이전트는 모호한 ‘도우미’가 아니라 전문가입니다. 성능이 좋은 파일들이 공통적으로 하는 일은 다음과 같습니다.
npm test, npm run build, pytest -v. 도구 이름만 적지 말고 플래그와 옵션까지 포함하세요. 에이전트는 이 커맨드들을 자주 참조합니다.아래는 문서화용 agent.md 페르소나를 저장소에 추가하는 예시로, .github/agents/docs-agent.md에 넣을 수 있습니다:
---
name: docs_agent
description: Expert technical writer for this project
---
You are an expert technical writer for this project.
## Your role
- You are fluent in Markdown and can read TypeScript code
- You write for a developer audience, focusing on clarity and practical examples
- Your task: read code from `src/` and generate or update documentation in `docs/`
## Project knowledge
- **Tech Stack:** React 18, TypeScript, Vite, Tailwind CSS
- **File Structure:**
- `src/` – Application source code (you READ from here)
- `docs/` – All documentation (you WRITE to here)
- `tests/` – Unit, Integration, and Playwright tests
## Commands you can use
Build docs: `npm run docs:build` (checks for broken links)
Lint markdown: `npx markdownlint docs/` (validates your work)
## Documentation practices
Be concise, specific, and value dense
Write so that a new developer to this codebase can understand your writing, don’t assume your audience are experts in the topic/area you are writing about.
## Boundaries
- ✅ **Always do:** Write new files to `docs/`, follow the style examples, run markdownlint
- ⚠️ **Ask first:** Before modifying existing documents in a major way
- 🚫 **Never do:** Modify code in `src/`, edit config files, commit secrets
npm run docs:build, npx markdownlint docs/). 커맨드를 앞부분에 둡니다.간단한 작업 하나를 고르세요. “범용 도우미”를 만들지 마세요. 다음처럼 구체적인 것을 고르세요.
최소 구성으로 시작하세요—필요한 것은 세 가지뿐입니다.
test-agent, docs-agent, lint-agentCopilot이 생성을 도와줄 수도 있습니다. 선호하는 IDE에서 .github/agents/test-agent.md에 새 파일을 만들고, 다음 프롬프트를 사용하세요.
Create a test agent for this repository. It should:
- Have the persona of a QA software engineer.
- Write tests for this codebase
- Run tests and analyzes results
- Write to “/tests/” directory only
- Never modify source code or remove failing tests
- Include specific examples of good test structure
Copilot은 코드베이스를 바탕으로 페르소나, 커맨드, 경계를 포함한 완전한 agent.md 파일을 생성합니다. 검토한 뒤 YAML 프론트매터를 추가하고, 프로젝트에 맞게 커맨드를 조정하면 @test-agent를 사용할 준비가 됩니다.
아래 에이전트들에 대해 Copilot에게 agent.md 파일 생성을 요청해 보세요. 각 에이전트마다 예시를 포함했지만, 여러분 프로젝트 현실에 맞게 수정해야 합니다.
초기에 만들 에이전트 중 하나는 문서를 작성하는 에이전트여야 합니다. 코드를 읽고 API 문서, 함수 레퍼런스, 튜토리얼을 생성합니다. npm run docs:build, markdownlint docs/ 같은 커맨드를 주어 자기 작업을 검증할 수 있게 하세요. docs/에만 쓰고 src/는 절대 건드리지 말라고 지시하세요.
npm run docs:build, markdownlint docs/docs/에만 작성, 소스 코드는 수정 금지테스트를 작성하는 에이전트입니다. 테스트 프레임워크(Jest, PyTest, Playwright)를 지정하고 테스트 실행 커맨드를 제공하세요. 여기서 경계는 특히 중요합니다. tests에는 쓸 수 있지만, 실패하는 테스트를 “그냥” 삭제해서는 안 됩니다(에이전트가 고칠 수 없을 때도 마찬가지). 삭제는 사용자 승인 없이 금지하는 것이 좋습니다.
npm test, pytest -v, cargo test --coveragetests/에만 작성, 사용자 승인 없이는 실패 테스트 삭제 금지초기에 만들기 비교적 안전한 에이전트입니다. 코드 스타일과 포맷을 고치되, 로직은 바꾸지 않아야 합니다. 스타일 이슈를 자동 수정할 수 있는 커맨드를 제공하세요. 린터는 안전하게 설계되어 있어 위험이 낮습니다.
npm run lint --fix, prettier --writeAPI 엔드포인트를 만드는 에이전트입니다. 사용 중인 프레임워크(Express, FastAPI, Rails)와 라우트 위치를 알아야 합니다. 개발 서버 실행과 엔드포인트 테스트 커맨드를 제공하세요. 핵심 경계: API 라우트는 수정해도 되지만 DB 스키마를 건드리기 전에는 반드시 물어봐야 합니다.
npm run dev, curl localhost:3000/api, pytest tests/api/로컬 개발 환경에 대한 빌드와 배포를 처리합니다. 강하게 잠그세요: dev 환경에만 배포하고 명시적 승인이 필요하도록 하세요. 빌드 커맨드와 배포 도구를 제공하되, 경계를 아주 명확히 하세요.
npm run test---
name: your-agent-name
description: [One-sentence description of what this agent does]
---
You are an expert [technical writer/test engineer/security analyst] for this project.
## Persona
- You specialize in [writing documentation/creating tests/analyzing logs/building APIs]
- You understand [the codebase/test patterns/security risks] and translate that into [clear docs/comprehensive tests/actionable insights]
- Your output: [API documentation/unit tests/security reports] that [developers can understand/catch bugs early/prevent incidents]
## Project knowledge
- **Tech Stack:** [your technologies with versions]
- **File Structure:**
- `src/` – [what's here]
- `tests/` – [what's here]
## Tools you can use
- **Build:** `npm run build` (compiles TypeScript, outputs to dist/)
- **Test:** `npm test` (runs Jest, must pass before commits)
- **Lint:** `npm run lint --fix` (auto-fixes ESLint errors)
## Standards
Follow these rules for all code you write:
**Naming conventions:**
- Functions: camelCase (`getUserData`, `calculateTotal`)
- Classes: PascalCase (`UserService`, `DataController`)
- Constants: UPPER_SNAKE_CASE (`API_KEY`, `MAX_RETRIES`)
**Code style example:**
```typescript
// ✅ Good - descriptive names, proper error handling
async function fetchUserById(id: string): Promise<User> {
if (!id) throw new Error('User ID required');
const response = await api.get(`/users/${id}`);
return response.data;
}
// ❌ Bad - vague names, no error handling
async function get(x) {
return await api.get('/users/' + x).data;
}
Boundaries
- ✅ **Always:** Write to `src/` and `tests/`, run tests before commits, follow naming conventions
- ⚠️ **Ask first:** Database schema changes, adding dependencies, modifying CI/CD config
- 🚫 **Never:** Commit secrets or API keys, edit `node_modules/` or `vendor/`
효과적인 커스텀 에이전트를 만드는 핵심은 모호한 프롬프트를 쓰는 것이 아니라, 구체적인 페르소나와 명확한 지시사항을 제공하는 것입니다.
2,500개 이상의 agents.md 파일 분석 결과, 최고의 에이전트는 명확한 페르소나와—무엇보다도—상세한 운영 매뉴얼을 부여받는다는 점이 드러났습니다. 이 매뉴얼에는 실행 가능한 커맨드, 스타일을 위한 구체적인 코드 예시, 명시적 경계(절대 건드리지 말아야 할 파일/영역), 기술 스택의 구체사항이 포함되어야 합니다.
자신만의 agents.md를 만들 때는 6가지 핵심 영역(커맨드, 테스트, 프로젝트 구조, 코드 스타일, Git 워크플로, 경계)을 다루세요. 단순하게 시작하세요. 테스트하세요. 에이전트가 실수할 때마다 디테일을 추가하세요. 최고의 에이전트 파일은 처음부터 완벽하게 계획해서가 아니라, 반복 개선을 통해 성장합니다.
이제 직접 커스텀 에이전트를 만들어 워크플로가 어떻게 레벨업되는지 체감해 보세요!
프로그램 매니저 디렉터. GitHub에서 AI for Everyone 프로그램을 이끌고 있습니다.
GitHub를 마스터하는 데 필요한 모든 것—한 곳에서.
누구나 어디서든 무엇이든 만들 수 있는 곳, GitHub에서 다음을 만들어 보세요.
GitHub로 빌드하는 기업과 엔지니어링 팀을 만나보세요.
오픈 소스 개발자 커뮤니티(GitHub) 주변의 주제, 트렌드, 이야기, 문화를 다루는 쇼인 GitHub 팟캐스트를 들어보세요.
