서브에이전트 정의 파일(.md) 완전 해부 — frontmatter 8개 필드와 시스템 프롬프트

서브에이전트의 모든 것은 마크다운 파일 하나에 담긴다. 이 파일의 윗부분(frontmatter)이 에이전트의 설정이고, 아래 본문이 에이전트의 성격과 행동 규칙이다. Claude Code는 이 파일을 읽고 "언제 이 에이전트를 쓸지", "어떤 도구를 쓸 수 있는지", "어떻게 행동해야 하는지"를 결정한다.

파일의 두 구역 — 설정과 지시

구분선(---) 위가 설정이고 아래가 지시다. 설정이 맞지 않으면 에이전트가 아예 호출되지 않고, 지시가 나쁘면 호출은 되지만 엉뚱한 결과를 낸다. 두 구역 모두 중요하다.

frontmatter 8개 필드 전체 지도

▲ 핵심 필드 4개 — 거의 모든 에이전트가 쓰는 필수 설정

▲ 제어 필드 4개 — 특수 상황에서만 쓰는 고급 설정

description — 자동 위임의 핵심이자 가장 중요한 필드

description이 모호하면 에이전트가 전혀 자동으로 호출되지 않는다. Claude가 이 필드를 읽고 "지금 이 상황에 이 에이전트를 써야 할까?"를 판단하기 때문에, 트리거 조건을 구체적으로 써야 한다.

▲ 나쁜 description — 조건·구체성·트리거가 빠져 자동 호출 실패

▲ 좋은 description — 언제·무엇을 구체적으로, 영어로 명시

좋은 description의 3가지 공통점: ① "언제" 써야 하는지 구체적 상황 명시 (파일 편집 후, 에러 보고 시), ② "무엇을" 하는지 동사로 설명 (reviews, root-causes), ③ 영어로 작성 (메인 Claude가 영어 description을 더 정확하게 판단).

tools — 에이전트의 보안 경계

▲ 읽기 전용 리뷰어 — Edit 없이 읽기·검색만 허용

▲ 수정 가능한 디버거 — Edit 포함, 코드 고치고 테스트까지

▲ MCP 도구 포함 에이전트 — 명시한 MCP 도구만 추가 허용

tools에 명시되지 않은 도구는 절대 쓸 수 없다. 이것이 서브에이전트의 보안 경계다. 코드 리뷰어에게 Edit 권한을 주지 않으면 리뷰만 하고 파일을 수정하는 실수를 원천 차단한다.

model — 작업 성격에 맞는 모델 선택

▲ haiku — 빠르고 저렴, 단순 반복 작업에 적합

▲ sonnet — 균형형, 대부분의 실무 에이전트 기본값

▲ opus — 깊은 추론, 복잡한 설계 판단 전용

model 필드를 생략하면 메인 세션과 동일한 모델을 사용한다. 대부분의 실무 에이전트는 sonnet이 적합하다. 빠른 반복 작업에는 haiku로 절약하고, 복잡한 설계 판단에만 opus를 쓰는 전략이 효과적이다.

시스템 프롬프트 — 잘 쓰는 4가지 구조

절차 섹션이 핵심이다. "잘 해줘"처럼 모호한 지시 대신, 에이전트가 따라야 할 체크리스트를 번호 있는 목록으로 명시한다. 에이전트는 메인 Claude의 감독 없이 독립적으로 작업하기 때문에, 절차가 명확할수록 결과가 일관된다.

description의 트리거 패턴 — 자동 위임을 잘 작동시키는 공식

공식은 단순하다. [언제] + [무엇을] + [제약]. 이 세 요소가 갖춰지면 메인 Claude가 상황을 보고 정확하게 에이전트를 자동 호출한다. 영어로 작성하는 것이 한국어보다 트리거 정확도가 높다.

파일 하나로 결정되는 에이전트의 행동 전체

에이전트 .md 파일 하나가 서브에이전트의 모든 것을 결정한다. 이 파일이 핵심이고, 플러그인의 나머지 파일들(plugin.json, .mcp.json)은 이 파일을 감싸는 포장지에 불과하다. 좋은 에이전트는 좋은 .md 파일에서 시작한다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.