아프니까 개발자다 아프니까 개발자다

서브에이전트를 만드는 방법은 알아도 잘 쓰는 방법은 다르다. 설치했는데 자동으로 호출되지 않거나, 에이전트가 엉뚱한 작업을 하거나, 서로 간섭해서 결과가 망가지는 경우가 생긴다. 이 글은 서브에이전트를 제대로 활용하기 위한 실전 노하우를 정리한다.노하우 1: description은 에이전트의 자동 위임 트리거다이 다이어그램은 사용자가 .py 파일을 편집한 직후 메인 Claude가 어떤 절차로 서브에이전트 자동 호출 여부를 결정하는지 보여준다. 메인은 매 턴마다 "지금 이 상황에 맞는 에이전트가 있는가?"를 묻는데, 그 판단 근거가 바로 등록된 모든 에이전트의 description 필드다. 즉 description은 "이 에이전트가 무슨 일을 하는가"라기보다 "언제 나를 호출해야 하는가"의 트리거 규칙으로..

서브에이전트를 만들고 나면 팀원과 공유하고 싶어진다. 가장 직관적인 방법이 GitHub다. Git을 이미 쓰고 있고, 버전 관리가 되고, URL 하나로 설치할 수 있다. 이 글은 서브에이전트를 GitHub로 배포하는 두 시나리오를 설명한다 — 프로젝트에 포함시켜 자동 공유하는 방법과, 별도 저장소로 플러그인을 배포하는 방법.두 시나리오 선택 기준세 질문을 순서대로 던진다. MCP 도구가 필요한가? 여러 저장소·팀에 배포해야 하는가? 버전 고정이 필요한가? 어느 하나라도 "예"라면 시나리오 2(별도 저장소 플러그인)로 간다. 세 질문 모두 "아니오"라면 시나리오 1(프로젝트에 포함)로 충분하다. MCP가 첫 분기 기준인 이유는 뒤에서 다시 보충하지만, 짧게 말하면 시나리오 1로도 MCP를 동봉할 수는 있어..

서브에이전트 파일을 만들었다면 다음 질문이 온다. 이 파일을 어디에 두어야 하는가? Claude Code는 세 위치를 스캔한다 — 사용자 홈의 전역 디렉토리, 프로젝트의 로컬 디렉토리, 그리고 설치된 플러그인 캐시. 어디에 두느냐에 따라 적용 범위·팀 공유·버전 관리가 달라진다.Claude Code가 에이전트를 찾는 세 경로세 위치 모두 스캔되고 통합된다. 같은 name이 여러 위치에 있으면 프로젝트 에이전트가 전역보다 우선한다. 플러그인 에이전트는 설치된 패키지에서 로드된다.전역 배치 — ~/.claude/agents/▲ 전역 배치 구조 — 한 곳에 두면 모든 프로젝트에 적용된다▲ 전역 배치의 장점 — 중앙 관리와 즉시 적용▲ 전역 배치의 단점 — 팀 공유 불가와 Git 추적 부재전역은 "어떤 프로젝트..

서브에이전트의 tools 필드에는 기본 도구(Read, Edit, Bash, Grep)를 지정한다. 그런데 이 기본 도구만으로 커버되지 않는 능력이 필요할 때가 있다. 웹 페이지를 직접 가져오거나, 가설을 단계별로 구조화해서 추론하거나, 외부 API를 호출하거나. 이런 새 도구는 MCP 서버에서 온다. 어떤 MCP 서버를 쓸지를 정의하는 파일이 .mcp.json이다.MCP(Model Context Protocol)는 AI 모델이 외부 시스템·도구를 표준 방식으로 호출하는 프로토콜이다 — USB-C처럼 다양한 장치를 하나의 표준 포트로 연결하는 것과 같다..mcp.json이 없을 때 vs 있을 때▲ .mcp.json 없음 — 기본 도구만, 외부 능력 없음▲ .mcp.json 있음 — MCP 도구로 외부 능..

에이전트 정의 마크다운 파일 하나만 있으면 서브에이전트로 동작하는데, 왜 plugin.json이 필요한가? 그 답은 하나다. plugin.json이 있어야 Claude Code가 그 디렉토리를 "설치 가능한 패키지"로 인식한다. 이 파일이 없으면 디렉토리는 그냥 폴더일 뿐이고, /plugin install로 설치하거나 팀원과 공유하는 것이 불가능해진다.plugin.json이 하는 단 하나의 일파일 수백 바이트가 에이전트의 지위를 바꾼다. plugin.json이 있는 순간 디렉토리는 설치·배포·버전 관리가 가능한 패키지로 격상된다. 에이전트 자체의 능력은 변하지 않는다 — 단지 그 에이전트를 배포하는 방법이 생기는 것이다.플러그인 디렉토리는 어디에 둬도 된다 — 단 내부 구조는 고정먼저 한 가지 오해를 풀..

지난 글에서 서브에이전트 정의 파일의 frontmatter 8개 필드 중 "핵심 4개"(name·description·tools·model)를 다뤘다. 이번 글은 나머지 "제어 4개"를 파고든다. 핵심 4개가 "이 에이전트를 언제 켜고 무엇을 시킬지"를 정한다면, 제어 4개는 "켜진 에이전트를 어떤 환경에서 어떻게 굴릴지"를 정한다. 평소엔 생략해도 되지만, 한 번 필요해지면 이 필드 없이는 문제를 풀 수 없다.제어 필드 4개가 푸는 4가지 문제네 필드는 각각 권한·기억·공간·시간이라는 서로 다른 축을 다룬다. 하나씩 보면 모두 "기본값으로 두면 안전하지만 답답하고, 바꾸면 강력하지만 조심해야 하는" 트레이드오프를 담고 있다. 어디서 기본값을 깨야 하는지가 이 글의 핵심이다.permissionMode —..

서브에이전트의 모든 것은 마크다운 파일 하나에 담긴다. 이 파일의 윗부분(frontmatter)이 에이전트의 설정이고, 아래 본문이 에이전트의 성격과 행동 규칙이다. Claude Code는 이 파일을 읽고 "언제 이 에이전트를 쓸지", "어떤 도구를 쓸 수 있는지", "어떻게 행동해야 하는지"를 결정한다.파일의 두 구역 — 설정과 지시구분선(---) 위가 설정이고 아래가 지시다. 설정이 맞지 않으면 에이전트가 아예 호출되지 않고, 지시가 나쁘면 호출은 되지만 엉뚱한 결과를 낸다. 두 구역 모두 중요하다.frontmatter 8개 필드 전체 지도▲ 핵심 필드 4개 — 거의 모든 에이전트가 쓰는 필수 설정▲ 제어 필드 4개 — 특수 상황에서만 쓰는 고급 설정description — 자동 위임의 핵심이자 가장..

Claude Code에서 서브에이전트를 만들면 어떤 파일이 어떤 경로에 만들어질까? "마크다운 파일 하나"로 끝나는 단순한 경우도 있고, 네 종류의 파일이 특정 디렉토리 구조로 배치된 플러그인 패키지가 되는 경우도 있다. 이 글은 서브에이전트의 파일 구성 전체 지도를 그린다.두 형태의 갈림길 — 새 도구가 필요한가갈림길은 단순하다. 기존 Claude Code 기본 도구(Read, Edit, Bash, Grep 등)만으로 충분하면 마크다운 파일 하나로 끝난다. 외부 도구가 필요하면 플러그인 패키지로 키운다.단독 에이전트 — 파일 하나의 해부frontmatter가 설정이고 본문이 지시서다. frontmatter가 "이 에이전트를 언제 켜고 어떤 도구를 허용할지"를 정의하고, 시스템 프롬프트가 "켜진 에이전트..