[번역] 훌륭한 agents.md 작성법 - 2,500개 이상의 리포지토리에서 얻은 교훈

작성자: Matt Nigh (2025년 11월 19일 | 업데이트: 2025년 11월 25일)

저희는 최근 GitHub Copilot의 새로운 기능인 agents.md 파일로 정의되는 커스텀 에이전트를 출시했습니다. 이제 하나의 일반적인 어시스턴트 대신, 테크니컬 라이팅을 위한 @docs-agent, 품질 보증(QA)을 위한 @test-agent, 보안 분석을 위한 @security-agent와 같이 전문가 팀을 구축할 수 있습니다. 각 agents.md 파일은 프론트매터(frontmatter)와 사용자 지정 지침으로 정의하는 에이전트의 페르소나 역할을 합니다.

agents.md는 에이전트의 페르소나, 에이전트가 알아야 할 정확한 기술 스택, 프로젝트의 파일 구조, 워크플로우, 그리고 에이전트가 실행할 수 있는 명시적인 명령어 등 모든 세부 사항을 정의하는 곳입니다. 또한 코드 스타일 예시를 제공하고, 가장 중요하게는 '하지 말아야 할 것'에 대한 명확한 경계를 설정하는 곳이기도 합니다.

어려운 점은 무엇일까요? 대부분의 에이전트 파일은 너무 모호해서 실패합니다. "당신은 도움이 되는 코딩 보조자입니다"라는 말은 통하지 않습니다. "당신은 React 컴포넌트 테스트를 작성하는 테스트 엔지니어이며, 다음 예시를 따르고, 절대 소스 코드를 수정하지 않습니다"라고 해야 효과가 있습니다.

저는 개발자들이 agents.md 파일을 어떻게 사용하고 있는지 이해하기 위해 공개 리포지토리에 있는 2,500개 이상의 agents.md 파일을 분석했습니다. 분석 결과 효과적인 패턴이 뚜렷하게 나타났습니다. 에이전트에게 구체적인 직무나 페르소나, 실행할 정확한 명령어, 따라야 할 잘 정의된 경계, 그리고 에이전트가 따라야 할 좋은 출력물의 명확한 예시를 제공해야 한다는 것입니다.

성공적인 파일들이 무엇을 다르게 하고 있는지 소개합니다.

실제 적용 사례: 2,500개 이상의 리포지토리에서 얻은 교훈

2,500개 이상의 agents.md 파일을 분석한 결과, 실패하는 파일과 성공하는 파일 사이에 명확한 차이가 드러났습니다. 성공적인 에이전트는 막연한 도우미가 아니라 전문가입니다. 최상위 성능을 보이는 파일들의 차이점은 다음과 같습니다.

1. 명령어를 앞부분에 배치하세요: npm test, npm run build, pytest -v와 같은 관련 실행 명령어를 앞부분에 배치하세요. 단순히 도구 이름만 적지 말고 플래그와 옵션을 포함하세요. 에이전트는 이를 자주 참조하게 됩니다.
2. 설명보다 코드 예시가 낫습니다: 스타일을 설명하는 세 문단의 글보다 실제 코드 스니펫 하나가 더 낫습니다. 좋은 결과물이 어떤 모습인지 보여주세요.
3. 명확한 경계를 설정하세요: AI에게 절대 건드리지 말아야 할 것(예: 비밀 키(secrets), 벤더(vendor) 디렉터리, 프로덕션 설정, 특정 폴더 등)을 알려주세요. "비밀 키를 절대 커밋하지 말 것"은 가장 흔하면서도 유용한 제약 사항이었습니다.
4. 스택에 대해 구체적으로 명시하세요: 단순히 "React 프로젝트"라고 하지 말고 "React 18, TypeScript, Vite, Tailwind CSS 사용"이라고 말하세요. 버전과 주요 의존성을 포함하세요.
5. 6가지 핵심 영역을 다루세요: 다음 영역들을 다루면 최상위 티어에 속하게 됩니다: 명령어, 테스트, 프로젝트 구조, 코드 스타일, git 워크플로우, 그리고 경계(boundaries).

훌륭한 agent.md 파일 예시

다음은 리포지토리의 .github/agents/docs-agent.md에 문서화 에이전트 페르소나를 추가하는 예시입니다.

이 agent.md 파일이 효과적인 이유

• 명확한 역할 명시: 에이전트가 누구인지(전문 테크니컬 라이터), 어떤 기술을 가졌는지(Markdown, TypeScript), 무엇을 하는지(코드 읽기, 문서 쓰기) 정의합니다.
• 실행 가능한 명령어: AI에게 실행할 수 있는 도구(npm run docs:build 및 npx markdownlint docs/)를 제공합니다. 명령어는 가장 먼저 나옵니다.
• 프로젝트 지식: 기술 스택과 버전(React 18, TypeScript, Vite, Tailwind CSS) 및 정확한 파일 위치를 지정합니다.
• 실제 예시: 추상적인 설명 없이 실제 코드로 좋은 출력물이 어떤 모습인지 보여줍니다.
• 3단계 경계: '항상 수행', '질문 우선', '절대 금지'를 사용하여 명확한 규칙을 설정합니다. 이는 파괴적인 실수를 방지합니다.

첫 번째 에이전트 만드는 법

하나의 간단한 작업을 선택하세요. "일반적인 도우미"를 만들지 마세요. 다음과 같이 구체적인 것을 선택하세요.

• 함수 문서 작성하기
• 유닛 테스트 추가하기
• 린트(linting) 오류 수정하기

최소한으로 시작하세요. 다음 세 가지만 있으면 됩니다.

1. 에이전트 이름: test-agent, docs-agent, lint-agent
2. 설명: "TypeScript 함수에 대한 유닛 테스트 작성"
3. 페르소나: "당신은 포괄적인 테스트를 작성하는 품질 소프트웨어 엔지니어입니다"

Copilot이 에이전트 생성을 도와줄 수도 있습니다. 선호하는 IDE를 사용하여 .github/agents/test-agent.md에 새 파일을 열고 다음 프롬프트를 사용하세요.

Copilot은 여러분의 코드베이스를 기반으로 페르소나, 명령어, 경계가 포함된 완전한 agent.md 파일을 생성할 것입니다. 이를 검토하고, YAML 프론트매터를 추가하고, 프로젝트에 맞게 명령어를 조정하면 @test-agent를 사용할 준비가 됩니다.

만들어 볼 만한 가치가 있는 6가지 에이전트

Copilot에게 아래 에이전트들에 대한 agent.md 파일 생성을 요청해 보세요. 각 에이전트에 대한 예시를 포함했으니, 프로젝트의 실제 상황에 맞게 변경해야 합니다.

@docs-agent

초기 에이전트 중 하나는 문서를 작성해야 합니다. 코드를 읽고 API 문서, 함수 참조 및 튜토리얼을 생성합니다. npm run docs:build 및 markdownlint docs/와 같은 명령어를 주어 자신의 작업을 검증할 수 있게 하세요. docs/에 작성하고 src/는 절대 건드리지 말라고 지시하세요.

• 하는 일: 코드 주석과 함수 시그니처를 Markdown 문서로 변환
• 명령어 예시: npm run docs:build, markdownlint docs/
• 경계 예시: docs/에 작성, 소스 코드 수정 절대 금지

@test-agent

이 에이전트는 테스트를 작성합니다. 테스트 프레임워크(Jest, PyTest, Playwright)를 지정하고 테스트 실행 명령어를 제공하세요. 여기서 경계가 매우 중요합니다: tests에는 쓸 수 있지만, 실패한다고 해서(그리고 에이전트가 고칠 수 없다고 해서) 테스트를 제거해서는 안 됩니다.

• 하는 일: 유닛 테스트, 통합 테스트, 엣지 케이스 커버리지 작성
• 명령어 예시: npm test, pytest -v, cargo test --coverage
• 경계 예시: tests/에 작성, 사용자의 승인 없이 실패하는 테스트 제거 금지

@lint-agent

초기에 만들기 꽤 안전한 에이전트입니다. 코드 스타일과 서식을 수정하지만 로직을 변경해서는 안 됩니다. 스타일 문제를 자동 수정(auto-fix)할 수 있는 명령어를 제공하세요. 린터(linter)는 안전하게 설계되었기 때문에 위험도가 낮습니다.

• 하는 일: 코드 포맷팅, import 순서 수정, 명명 규칙 강제
• 명령어 예시: npm run lint --fix, prettier --write
• 경계 예시: 스타일만 수정, 코드 로직 변경 절대 금지

@api-agent

이 에이전트는 API 엔드포인트를 구축합니다. 프레임워크(Express, FastAPI, Rails)와 라우트가 위치한 곳을 알아야 합니다. 개발 서버를 시작하고 엔드포인트를 테스트할 수 있는 명령어를 제공하세요. 핵심 경계: API 라우트는 수정할 수 있지만 데이터베이스 스키마를 건드리기 전에는 반드시 물어봐야 합니다.

• 하는 일: REST 엔드포인트, GraphQL 리졸버, 에러 핸들러 생성
• 명령어 예시: npm run dev, curl localhost:3000/api, pytest tests/api/
• 경계 예시: 라우트 수정, 스키마 변경 전 질문

@dev-deploy-agent

로컬 개발 환경으로의 빌드와 배포를 처리합니다. 엄격하게 통제하세요: 개발 환경에만 배포하고 명시적인 승인을 요구하세요. 빌드 명령어와 배포 도구를 제공하되 경계를 매우 명확하게 하세요.

• 하는 일: 로컬 또는 개발 빌드 실행, Docker 이미지 생성
• 명령어 예시: npm run test
• 경계 예시: 개발 환경에만 배포, 위험이 따르는 모든 작업에 사용자 승인 필요

시작 템플릿 (Starter template)

핵심 요약

효과적인 커스텀 에이전트를 구축하는 것은 모호한 프롬프트를 작성하는 것이 아니라, 구체적인 페르소나와 명확한 지침을 제공하는 것입니다.

2,500개 이상의 agents.md 파일을 분석한 결과, 최고의 에이전트는 명확한 페르소나와 무엇보다도 상세한 운영 매뉴얼을 부여받았습니다. 이 매뉴얼에는 실행 가능한 명령어, 스타일링을 위한 구체적인 코드 예시, 명시적인 경계(절대 건드리지 말아야 할 파일 등), 그리고 기술 스택에 대한 구체적인 내용이 포함되어야 합니다.

자신만의 agents.md를 만들 때는 6가지 핵심 영역(명령어, 테스트, 프로젝트 구조, 코드 스타일, git 워크플로우, 경계)을 다루세요. 간단하게 시작하세요. 테스트해 보세요. 에이전트가 실수를 하면 세부 사항을 추가하세요. 최고의 에이전트 파일은 사전 계획이 아니라 반복(iteration)을 통해 성장합니다.