• 에이전트 정의 파일을 ‘설정 파일’이 아닌 ‘역할 계약서’로 바라보는 관점을 갖고 name, descrfiption, model, tools 필드와 본문 7섹션을 올바르게 채우는 방법을 익힌다.
  • 어떤 모델을 고를지, 어떤 도구를 허용할지를 결정하는 기준도 함께 살펴본다.

어제 잘 굴러가던 팀이 오늘 아침 사라지는 이유

  • 모든 에이전트는 반드시 .claude/agents/{name}.md 파일로 정의한다. 파일 없이 프롬프트 파라미터에 역할을 직접 넣는 것을 금지한다.
    • 없으면, 다음 날 다시 팀을 소환할 떄 역할을 처음부터 다시 서명해야 한다.
    • 없으면, 두 세션이 같은 기준으로 판단했는지 검즈할 길이 없다.
    • 팀 멤버가 늘면 누가 무엇을 하는지 설명을 계속 반복해야 한다.
  • 프론트매터 5개 필드: name, description, model, tools, 선택 필드
  • 본문 7개 섹션: 핵심 역할, 작업 원칙, 입출력 프로토콜, 팀 통신 프로토콜, 에러 핸들링, 협업, 품질 자체 검증

본문 7개 섹션 - 왜 필요하고 어떻게 쓰는가

핵심 역할 - 범위 결정

  • 하는 일을 1~3로 명시하고, 하지 않은 일도 함께 경계를 짓는다.

작업 원칙 - 판단 기준 결정

  • 두 선택지가 충돌할 때 어느 쪽을 택할지 알 수 있어야 한다.

입출력 프로토콜 - 에이전트 간 API 계약

  • 다른 에이전트가 이 에이전트의 산출물을 읽을 경로와 형식을 정한다.

팀 통신 프로토콜 - 누구에게, 무엇을, 언제

  • SendMessage 도구로 주고받을 정보의 세 요소, 누구에게/무엇을/언제를 명시한다.
  • 메시지 작성할 떄 원칙
    • 좋은 메시지 = 발견 사실 + 수신자에게 취해야 할 행동
    • “완료했습니다"로 끝나는 메시지는 수신자에게 아무 행동도 요청하지 않는다.
    • “~에 반영해 주세요"로 끝나야 수신자가 다음에 무엇을 해야 할지 분명해진다.

에러 핸들링 - 종료 조건 명시

  • 구체적인 실패 시나리오, 각 시나리오에서의 행동, 최대 재시도 횟수를 정해둔다.

협업 - 팀 안에서의 위치 결정

  • 이 에이전트가 누구와 어떤 순서로 연결되는지 명시한다.

품질 자체 검증 - 제출 전 자기 점검

  • 출력을 반환하기 위해 에이전트가 스스로 거쳐야 할 체크리스트.
  • 후속 리뷰어가 잡을 것을 에이전특라먼저 잡으면 루프 횟수가 줄어든다.

가드레일 - 에이전트가 할 수 없는 것을 파일로 정하기

  • ‘품질 자체 검증’이 에이전트가 스스로 점검하는 층이라면, 그 바깥에 한 층이 더 있다.
    • 에이전특라 아예 실행할 수 없도록 파일 자체에 막아두는 층이다.
    • 프론트매터의 tools 필드가 그 역할을 한다.
  • tools 필드는 같은 원칙을 세 가지 방식으로 적용한다.
    • 최소 권한: 작업에 필요한 최소한의 도구만 준다.
    • 도구 최소화: 도구 선택지가 너무 많으면 오히려 판단이 흐려지는 ‘토큰 마비’가 생긴다.
    • 명시적 제외: 상속된 도구 집합에서 특정 도구만 빼고 싶을 때는 disallowedTools를 쓴다.
  • tools 필드는 ‘이 에이전트 하나’의 경계를 정하는 파일 수준 가드레일이다.

프론트매터 다섯 필드와 16개 공식 필드

  • 에이전트 파일에 type: general-purpose라는 키가 자주 보이는데, 이 키는 공슥 스펙에 없는, 파서가 읽지 않는 문서화용 키이다.
  • name: 파일명과 반드시 일치시켜야 한다.
  • description: 오케스트레이터가 ‘이 에이전트를 언제 쓸지’판단한느 근거이다.
  • model: 비용, 모델 등급, 응답속도를 한번에 결정한다.
    • 기본값은 inherit, 즉 부모 세션의 모델을 상속한다.
  • tools: 에이전트가 일으킬 수 있는 부작용의 범위이다.
    • tools와 disallowedTools를 함께 쓸 때, disallowedTools가 먼저 적용되어 상속 목록에서 해당 도구를 제거하고, 남은 집합에 tools 필터가 적용된다.

안티패턴

  • 무엇이든 다 하는 에이전트
    • 단일 에이전트가 자기 실수를 잘 보지 못하는 문제가 재현된다.
  • 도구를 너무 많이 줬을 때
    • 모든 도구 설명이 시스템 프롬프트에 상속되어 토큰이 불필요하게 늘어나고 실행 경로가 많아진다.
    • 검토 역할 에이전트에 Edit가 남아 있으면 검토자가 본문을 직접 수정하면서 검증 루프가 무너진다.
  • model 필드를 비워두는 경우
    • model 필드를 생략하면 기본값 inherit이 적용되어 부모 세션에 따라 에이전트의 동작이 달라진다.
    • 상속을 의도했다면 model: inherit으로 명확히 적어라.
  • description이 너무 막연할 때
    • 오케스트레이터가 어떤 에이전트를 호출할지 제대로 판단하지 못하게 된다.
    • 팀에 리뷰어가 두 명 이상일 때 특히 치명적이다.