AI로 코딩 작업을 할 때 서브-에이전트 활용은 이제 필수가 되었습니다.
하지만 무작정 agents만 만든다고 능사는 아닌데요.
일 잘하는 서브 에이전트를 만들기위해 agents.md 파일을 어떻게 적어야하는지에 대해
GitHub Program Manager Director인 Matt Nigh가 정리해둔 글이 흥미로워
전문 번역·해석한 글입니다!
2,500개 이상의 레포지토리에서 얻은 교훈
훌륭한 에이전트를 작성하는 방법, 2500개가 넘는 저장소의 MD 강의
GitHub Copilot에 agents.md를 활용한 커스텀 에이전트 기능이 새로 추가되었다.
이제 하나의 범용 AI가 아니라, 역할이 명확히 분리된 여러 명의 “전문가 에이전트”를 만들 수 있다.
예를 들어 문서 작성을 담당하는 @docs-agent, 테스트를 담당하는 @test-agent, 보안을 담당하는 @security-agent처럼 말이다.
agents.md 파일은 단순한 설정 파일이 아니다.
이 파일은 에이전트의 정체성(persona)이자 운영 매뉴얼이다.
여기에는 다음과 같은 내용이 들어간다.
에이전트의 역할과 성격
반드시 알고 있어야 할 기술 스택
프로젝트의 디렉토리 구조
실행 가능한 명령어
코드 스타일 예시
그리고 무엇보다 절대 하지 말아야 할 것들
문제는 대부분의 agents.md가 실패한다는 점이다.
“당신은 도움이 되는 코딩 어시스턴트입니다” 같은 지시는 아무 의미가 없다.
반면 잘 작동하는 지시는 이렇다.
“당신은 React 컴포넌트 테스트만 작성하는 테스트 엔지니어입니다.
기존 소스 코드는 절대 수정하지 마세요.”
나는 공개 저장소에 있는 2,500개 이상의 agents.md 파일을 분석했고,
성공하는 파일들에는 명확한 공통 패턴이 있었다.
실제로 효과 있었던 agents.md의 공통점 5가지
1. 실행 가능한 명령어를 앞에 둔다
에이전트가 실제로 사용할 명령어를 초반에 명시한다.
npm testnpm run buildpytest -v
툴 이름만 적지 말고 옵션까지 포함한 실제 커맨드를 적는 것이 중요하다.
에이전트는 이 명령어를 계속 참조한다.
2. 설명보다 코드 예제가 우선이다
스타일을 장황하게 설명하는 것보다 실제 코드 예제 하나가 훨씬 효과적이다.
“이게 좋은 출력이다”를 눈으로 보여줘야 한다.
3. 명확한 금지 구역(boundary)을 설정한다
AI가 절대 건드리면 안 되는 영역을 분명히 해야 한다.
예시:
시크릿
vendor 디렉토리
production 설정
특정 폴더
“절대 시크릿을 커밋하지 마라”는 가장 많이 등장했고, 가장 효과적인 제약 조건이었다.
4. 기술 스택은 최대한 구체적으로 쓴다
❌ “React 프로젝트”
✅ “React 18 + TypeScript + Vite + Tailwind CSS”
버전과 핵심 라이브러리를 명확히 적을수록 결과가 좋아진다.
5. 반드시 포함해야 할 6가지 핵심 영역
상위권 agents.md는 공통적으로 아래 6가지를 모두 포함한다.
실행 명령어
테스트 방식
프로젝트 구조
코드 스타일
Git 워크플로우
명확한 경계(boundaries)
좋은 agents.md 예시 (문서 작성 에이전트)
이 예시는 .github/agents/docs-agent.md에 들어갈 수 있는 문서 전용 에이전트다.
역할: 기술 문서 작성 전문가
읽는 위치:
src/쓰는 위치:
docs/실행 명령어: 문서 빌드, markdown lint
금지 사항: 소스 코드 수정 금지
이 파일이 잘 작동하는 이유는 다음과 같다.
역할이 명확하다
실제 실행 가능한 명령어가 있다
프로젝트 구조를 정확히 알고 있다
추상적 설명이 아니라 실제 예시가 있다
Always / Ask first / Never의 3단계 규칙으로 사고를 통제한다
첫 번째 에이전트는 이렇게 시작하라
처음부터 “만능 에이전트”를 만들지 마라.
하나의 아주 구체적인 작업만 맡겨라.
예시:
함수 문서 작성
테스트 코드 작성
린트 오류 수정
최소 구성은 이 3가지면 충분하다.
에이전트 이름 (
test-agent)한 줄 설명 (“TypeScript 테스트를 작성하는 QA 엔지니어”)
페르소나 정의
Copilot에게 초안 생성을 시킨 뒤, 사람이 검토하고 다듬는 방식이 가장 좋았다.
만들어볼 만한 6가지 에이전트
docs-agent: 문서 자동 생성
test-agent: 테스트 작성 전용
lint-agent: 포맷·스타일 수정만 담당
api-agent: API 엔드포인트 구현
dev-deploy-agent: 로컬/개발 배포
security-agent: 취약점 분석
중요한 건, 권한은 최소화하고 책임은 명확히 하는 것이다.
핵심 정리
좋은 agents.md는 “프롬프트”가 아니라 운영 매뉴얼에 가깝다.
성공하는 파일들은 공통적으로 다 음을 갖는다.
명확한 페르소나
실행 가능한 명령어
실제 코드 예시
절대 침범하지 말아야 할 경계
구체적인 기술 스택
agents.md는 한 번에 완성되지 않는다.
에이전트가 실수할 때마다 조금씩 규칙을 추가하며 진화한다.
잘 만든 에이전트는 단순한 보조 도구가 아니라
팀의 생산성을 구조적으로 끌어올리는 디지털 팀원이 된다.
원문: 〈How to write a great agents.md: Lessons from over 2,500 repositories〉
