GitHub Copilot 커스텀 에이전트: 2,500개 이상의 저장소 분석을 통해 얻은 성공 전략

효과적인 agents.md 파일 작성 원칙 2,500개 이상의 agents.md 파일 분석 결과, 성공적인 에이전트는 다음과 같은 특징을 가집니다. * 명확한 역할 및 페르소나 부여: “유용한 코딩 도우미”와 같은 모호한 설명 대신, “React 컴포넌트 테스트를 작성하고 소스 코드를 수정하지 않는 테스트 엔지니어”처럼 구체적인 역할을 정의해야 합니다. * 실행 가능한 명령 조기 배치: npm test, npm run build, pytest -v와 같이 에이전트가 직접 실행할 수 있는 명령어를 파일 초반에 명확한 플래그 및 옵션과 함께 제시합니다. * 코드 예시를 통한 스타일 제시: 코드 스타일을 설명하는 긴 문장보다 실제 코드 스니펫을 통해 좋은 결과물의 형태를 직접 보여주는 것이 효과적입니다. * 명확한 경계 설정: 에이전트가 절대 수정해서는 안 되는 부분(예: 비밀 정보, 벤더 디렉토리, 프로덕션 설정)을 “절대 비밀 정보를 커밋하지 마라”와 같이 구체적으로 명시합니다. * 기술 스택 상세 명시: “React 프로젝트” 대신 “React 18 with TypeScript, Vite, and Tailwind CSS”처럼 버전과 주요 의존성을 포함하여 기술 스택을 구체적으로 설명합니다. * 6가지 핵심 영역 포함: 명령, 테스트, 프로젝트 구조, 코드 스타일, Git 워크플로, 경계의 6가지 핵심 영역을 다루는 것이 중요합니다. ## 성공적인 docs-agent.md 예시 분석 제시된 docs-agent.md 예시는 다음과 같은 이유로 효과적입니다. * 명확한 역할 정의: “이 프로젝트의 전문 기술 문서 작성자”로 역할을 명확히 하고, Markdown 및 TypeScript 코드 이해 능력을 명시합니다. * 실행 가능한 명령 포함: npm run docs:build, npx markdownlint docs/와 같은 도구 사용법을 제공합니다. * 프로젝트 지식 구체화: React 18, TypeScript 등의 기술 스택과 src/에서 읽고 docs/에 쓰는 파일 구조를 명시합니다. * 3단계 경계 설정: “항상 할 일(✅)”, “먼저 물어볼 일(⚠️)”, “절대 하지 않을 일(🚫)”로 구분하여 에이전트의 행동 규칙을 명확히 합니다. ## 에이전트 구축 및 추천 유형 첫 에이전트는 “함수 문서 작성”, “단위 테스트 추가”, “린트 오류 수정”과 같이 간단하고 구체적인 작업으로 시작해야 합니다. 최소한의 정보(에이전트 이름, 설명, 페르소나)로 시작하여 반복적으로 개선하는 것이 중요합니다. 추천하는 6가지 에이전트 유형은 다음과 같습니다. * @docs-agent: 코드 문서화 * @test-agent: 단위 및 통합 테스트 작성 * @lint-agent: 코드 스타일 및 포맷팅 수정 * @api-agent: API 엔드포인트 구축 * @dev-deploy-agent: 개발 환경 빌드 및 배포 * @security-agent: (본문에는 없지만 예시에서 언급) 보안 분석 각 에이전트는 명확한 “수행할 작업”, “예시 명령”, “예시 경계”를 정의하여 효과를 극대화할 수 있습니다.