훌륭한 Agent.md 작성 방법: 2,500개 이상의 저장소에서 얻은 교훈
우리는 최근 새로운 GitHub Copilot 기능을 출시했습니다. agents.md 파일. 이제 한 명의 일반 보조원 대신 전문가 팀을 구성할 수 있습니다. @docs-agent 기술 문서 작성의 경우 @test-agent 품질 보증을 위해 @security-agent 보안 분석을 위해. 각 agents.md 파일은 머리말과 사용자 지정 지침을 통해 정의하는 상담원 페르소나 역할을 합니다.
agents.md 에이전트의 페르소나, 알아야 할 정확한 기술 스택, 프로젝트의 파일 구조, 워크플로, 실행할 수 있는 명시적 명령 등 모든 세부 사항을 정의하는 곳입니다. 또한 코드 스타일 예제를 제공하고 가장 중요하게는 하지 말아야 할 작업에 대한 명확한 경계를 설정하는 곳이기도 합니다.
도전? 대부분의 에이전트 파일은 너무 모호하기 때문에 실패합니다. “당신은 도움이 되는 코딩 도우미입니다”가 작동하지 않습니다. “당신은 React 구성 요소에 대한 테스트를 작성하고 이러한 예제를 따르며 소스 코드를 절대 수정하지 않는 테스트 엔지니어입니다.”
2,500개가 넘게 분석했어요 agents.md 개발자가 어떻게 사용하고 있는지 이해하기 위해 공개 저장소에 파일을 저장합니다. agents.md 파일. 분석에서는 에이전트에게 특정 작업 또는 페르소나를 제공하고, 실행할 정확한 명령을 제공하고, 따라야 할 잘 정의된 경계, 에이전트가 따라야 할 좋은 출력의 명확한 예 등 작동 방식에 대한 명확한 패턴이 나타났습니다.
성공한 사람들의 행동은 다음과 같습니다.
실제 작동 방식: 2,500개 이상의 저장소에서 얻은 교훈
2,500개가 넘는 항목에 대한 내 분석 agents.md 파일을 보면 실패한 것과 작동하는 것 사이의 명확한 구분이 드러났습니다. 성공적인 에이전트는 막연한 도우미가 아닙니다. 그들은 전문가입니다. 성능이 가장 좋은 파일의 차이점은 다음과 같습니다.
- 명령을 일찍 넣으세요: 관련 실행 가능 명령을 초기 섹션에 배치하십시오.
npm test,npm run build,pytest -v. 도구 이름뿐만 아니라 플래그와 옵션도 포함하세요. 귀하의 상담원은 이러한 내용을 자주 참조할 것입니다. - 설명에 대한 코드 예제: 스타일을 보여주는 하나의 실제 코드 조각이 스타일을 설명하는 세 문단보다 낫습니다. 좋은 결과가 어떤 것인지 보여주세요.
- 명확한 경계를 설정하십시오. 절대 건드리지 말아야 할 사항(예: 비밀, 공급업체 디렉터리, 프로덕션 구성 또는 특정 폴더)을 AI에 알려줍니다. “비밀을 커밋하지 마십시오”는 가장 일반적으로 도움이 되는 제약 조건이었습니다.
- 스택에 대해 구체적으로 설명하세요. “React 프로젝트”가 아닌 “React 18 with TypeScript, Vite 및 Tailwind CSS”라고 말하세요. 버전 및 주요 종속성을 포함합니다.
- 6가지 핵심 영역을 다룹니다. 이러한 영역에 도달하면 명령, 테스트, 프로젝트 구조, 코드 스타일, git 워크플로 및 경계 등 최상위 계층에 속하게 됩니다.
훌륭한 Agent.md 파일의 예
아래는 문서를 추가하는 예입니다. 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이 Agent.md 파일이 잘 작동하는 이유
- 명확한 역할을 명시합니다. 에이전트가 누구인지(전문 기술 작가), 어떤 기술을 보유하고 있는지(Markdown, TypeScript), 에이전트가 수행하는 작업(코드 읽기, 문서 작성)을 정의합니다.
- 실행 가능한 명령: 실행할 수 있는 AI 도구 제공(
npm run docs:build그리고npx markdownlint docs/). 명령이 우선입니다. - 프로젝트 지식: 버전(React 18, TypeScript, Vite, Tailwind CSS) 및 정확한 파일 위치로 기술 스택을 지정합니다.
- 실제 예: 실제 코드로 좋은 출력이 어떻게 보이는지 보여줍니다. 추상적인 설명이 없습니다.
- 3계층 경계: 항상 하라, 먼저 물어라, 절대 하지 말라 등을 사용하여 명확한 규칙을 설정하세요. 파괴적인 실수를 방지합니다.
첫 번째 에이전트를 구축하는 방법
간단한 작업을 하나 선택하세요. “일반 도우미”를 만들지 마십시오. 다음과 같은 구체적인 항목을 선택하세요.
- 함수 문서 작성
- 단위 테스트 추가
- 린팅 오류 수정
최소한으로 시작하세요. 다음 세 가지만 있으면 됩니다.
- 대리인 이름:
test-agent,docs-agent,lint-agent - 설명: “TypeScript 함수에 대한 단위 테스트를 작성합니다”
- 페르소나: “당신은 포괄적인 테스트를 작성하는 우수한 소프트웨어 엔지니어입니다.”
Copilot은 귀하를 위해 생성하는 데 도움을 줄 수도 있습니다. 선호하는 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 structureCopilot은 완전한 agent.md 코드베이스를 기반으로 한 페르소나, 명령 및 경계가 포함된 파일입니다. 검토하고, YAML 머리말을 추가하고, 프로젝트에 대한 명령을 조정하면 사용할 준비가 됩니다. @test-agent.
구축할 가치가 있는 에이전트 6개
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 --coverage - 경계 예시: 쓰기 대상
tests/사용자가 승인하지 않는 한 실패한 테스트를 절대 제거하지 마십시오.
@lint-agent
초기에 생성하기에 상당히 안전한 에이전트입니다. 코드 스타일과 형식을 수정하지만 논리를 변경해서는 안 됩니다. 스타일 문제를 자동으로 수정할 수 있는 명령을 제공하세요. 린터는 안전하도록 설계되었기 때문에 위험이 낮습니다.
- 기능: 코드 형식 지정, 가져오기 순서 수정, 명명 규칙 적용
- 예제 명령:
npm run lint --fix,prettier --write - 경계 예: 스타일만 수정하고 코드 논리는 변경하지 않음
@api-에이전트
이 에이전트는 API 엔드포인트를 구축합니다. 프레임워크(Express, FastAPI, Rails)와 경로가 어디에 있는지 알아야 합니다. 개발 서버 및 테스트 엔드포인트를 시작하는 명령을 제공합니다. 주요 경계: API 경로를 수정할 수 있지만 데이터베이스 스키마를 건드리기 전에 물어봐야 합니다.
- 기능: REST 엔드포인트, GraphQL 해석기, 오류 핸들러 생성
- 예제 명령:
npm run dev,curl localhost:3000/api,pytest tests/api/ - 경계 예: 경로 수정, 스키마 변경 전에 확인
@dev-배포-에이전트
로컬 개발 환경에 대한 빌드 및 배포를 처리합니다. 잠금 상태를 유지하세요. 개발 환경에만 배포하고 명시적인 승인이 필요합니다. 빌드 명령과 배포 도구를 제공하되 경계를 매우 명확하게 만드세요.
- 기능: 로컬 또는 개발 빌드를 실행하고 Docker 이미지를 생성합니다.
- 예제 명령:
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 {
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 명령, 테스트, 프로젝트 구조, 코드 스타일, Git 워크플로 및 경계 등 6가지 핵심 영역을 다룹니다. 간단하게 시작하세요. 테스트해보세요. 상담원이 실수를 하면 세부정보를 추가하세요. 최고의 에이전트 파일은 사전 계획이 아닌 반복을 통해 성장합니다.
이제 직접 사용자 정의 에이전트를 구축하여 워크플로우 수준을 어떻게 향상시키는지 직접 확인하십시오!
작성자:
Post Comment