서브에이전트 패키지를 직접 뜯어보다 — debug-pack 플러그인 해부

GitHub MCP와 Playwright MCP는 도구 목록만 제공한다. 시스템 프롬프트와 트리거는 사용자가 별도로 만들어야 한다. 반면 debug-pack 플러그인은 다르다. 서브에이전트의 3가지 핵심 구성요소(시스템 프롬프트·도구 목록·트리거)가 모두 패키지 안에 들어 있다. 게다가 슬래시 커맨드(/debug-here)까지 묶여 있어, 설치하는 순간 Python 디버깅 전용 에이전트 생태계가 한 번에 세팅된다.

이 플러그인이 흥미로운 이유는 두 가지다. 첫째, 실제 서브에이전트 패키지가 어떻게 구성되는지 가장 완전한 형태로 보여주는 예시다. 둘째, Python 디버깅이라는 구체적인 문제를 풀기 위해 두 개의 MCP 서버(sequential-thinking, fetch)가 함께 포함되어 있어, 단순 역할 정의를 넘어 진짜 전문 도구를 갖춘 에이전트다.

다이어그램에서 주목할 것은 서브에이전트 박스(파란색)에 구성요소 ①과 ②가 함께 들어있다는 점이다. agents/python-debugger.md 파일의 본문이 ① 시스템 프롬프트가 되고, frontmatter의 tools 필드가 ② 도구 목록이 된다. 노란색 스킬 박스가 ③ 트리거를 담당한다. GitHub MCP나 Playwright MCP에서는 사용자가 직접 만들어야 했던 것들이 모두 패키지 안에 이미 들어 있다.

각 자산이 하는 일

python-debugger 서브에이전트는 이 패키지의 핵심이다. 시스템 프롬프트는 "오류 메시지와 스택 트레이스를 꼼꼼히 읽고, 가설을 단계별로 세우고 검증하며, 근본 원인을 고치는 가장 작은 변경만 제안한다"는 지시를 담는다. 모델은 추론 능력이 높은 sonnet으로 고정되어 있다.

sequential-thinking MCP 서버는 이 에이전트의 차별점이다. mcp__sequential-thinking__sequentialthinking이라는 도구를 제공하는데, 이 도구는 LLM이 "가설 → 검증 → 재고 → 재가설" 과정을 명시적인 단계로 기록하게 만든다. 내부적으로 추론하던 것을 도구 호출 로그로 외부화하는 것이다. 덕분에 "왜 이 결론에 도달했는지"를 추적할 수 있다.

fetch MCP 서버는 라이브러리 문서를 직접 조회하는 도구다. 에러가 특정 외부 라이브러리와 관련된 경우, 에이전트가 해당 라이브러리의 GitHub 이슈 목록이나 공식 문서를 직접 읽어서 이미 알려진 버그인지, 해결책이 있는지를 확인할 수 있다.

python-error-patterns 스킬은 자주 발생하는 Python 오류 패턴의 카탈로그다. ImportError, asyncio 관련 오류, pytest fixture 문제, mypy 타입 오류 등이 정리되어 있다. 에이전트가 오류를 처음 보는 게 아니라 이미 알고 있는 패턴과 대조하면서 판단하게 된다.

/debug-here 커맨드는 이 모든 것을 한 번에 트리거하는 원버튼이다. 오류가 발생한 상태에서 /debug-here를 입력하면, 현재 컨텍스트의 오류 정보를 python-debugger 서브에이전트에 즉시 위임한다.

설치 방법

debug-pack은 로컬 플러그인이므로 디렉토리 경로로 설치한다. MCP 서버 두 개는 모두 npx 패키지라 별도 설치 없이 첫 실행 시 자동으로 다운로드된다.

# 로컬 플러그인 설치
/plugin install ~/projects/debug-pack

# 설치 확인
# 대화창에서 /debug-here 커맨드가 나타나면 성공

# 사용 방법 1: 슬래시 커맨드
/debug-here
# → 현재 대화의 오류 정보를 python-debugger에게 즉시 위임

# 사용 방법 2: 자연어 트리거 (SKILL.md triggers)
# 사용자: "pytest tests/ 실행했는데 ImportError 났어"
# → python-error-patterns 스킬이 트리거되어 에이전트가 호출됨

# 사용 방법 3: 명시적 Agent 호출
# "python-debugger 에이전트한테 이 오류 분석 맡겨줘"

설치 후 파일 구조

debug-pack은 로컬 플러그인이라 GitHub MCP나 Playwright MCP와 설치 경로가 다르다. /plugin install ~/projects/debug-pack을 실행하면 다음 구조가 생성된다.

~/.claude/plugins/cache/debug-pack-local/debug-pack/0.1.0/
  .claude-plugin/
    plugin.json                              ← 플러그인 메타데이터
  .mcp.json                                  ← MCP 서버 2종 (sequential-thinking + fetch)
  README.md
  agents/
    python-debugger.md                       ← [구성요소 ①②] 시스템 프롬프트 + 도구 목록
  commands/
    debug-here.md                            ← 슬래시 커맨드 /debug-here
  skills/
    python-error-patterns/
      SKILL.md                               ← [구성요소 ③] 트리거 + 오류 패턴 카탈로그

GitHub MCP(파일 2개)나 Playwright MCP(파일 2개)와 비교하면 파일이 훨씬 많다. 각 파일이 역할을 나눠 맡고 있기 때문이다.

agents/python-debugger.md가 핵심이다. frontmatter의 tools 필드가 ② 도구 목록이고, model: sonnet으로 기본 Claude보다 추론 능력이 높은 모델을 고정한다. 본문 전체가 ① 시스템 프롬프트가 된다.

---
name: python-debugger
description: Use proactively when the user reports a Python error, stack trace,
             pytest failure, or "it broke after X". Root-causes the issue
             and proposes the smallest fix.
tools: Read, Edit, Bash, Grep, Glob,
       mcp__sequential-thinking__sequentialthinking,   ← 단계별 가설 검증 도구
       mcp__fetch__fetch                                ← 외부 문서 조회 도구
model: sonnet                                           ← 추론 능력이 높은 모델로 고정
---

You are a Python debugging specialist.
When invoked:
1. Read the error message or failing test output carefully.
2. Use mcp__sequential-thinking__sequentialthinking to lay out hypotheses step by step.
3. Verify each hypothesis with Read, Grep, or Bash before moving to the next.
4. Propose the smallest fix that addresses the root cause.

Output format: Root cause / Fix / Verification

skills/python-error-patterns/SKILL.md는 ③ 트리거와 오류 패턴 카탈로그가 함께 들어 있다. 트리거가 매칭되면 에이전트가 자동 호출되고, 카탈로그는 에이전트가 첫 번째 판단을 내릴 때 참조한다.

---
triggers:
  - Python 오류
  - 스택 트레이스
  - pytest 실패
  - 왜 안 되지
  - it broke after
---

## 오류 패턴 카탈로그

- ImportError / ModuleNotFoundError: 가상환경 불일치, 패키지 설치 누락
- asyncio RuntimeError: 이벤트 루프 중첩, sync 컨텍스트에서 await 호출
- pytest fixture: scope 불일치, autouse 충돌
- mypy 타입 오류: Optional 처리 누락, Any 타입 전파
- subprocess / File IO: 인코딩 불일치, 경로 오류
- GPU / CUDA: 드라이버 버전 불일치, 메모리 부족

.mcp.json에는 두 개의 로컬 서버가 정의되어 있다. 둘 다 GitHub MCP의 "type": "http"가 아닌 "command": "npx" 방식이다 — Playwright MCP와 같은 로컬 프로세스 실행이다.

// .mcp.json — 실제 파일 전체
{
  "sequential-thinking": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
  },
  "fetch": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-fetch"]
  }
}

commands/debug-here.md는 한 줄짜리 파일이다. 이 한 줄이 /debug-here 커맨드의 전부다.

Invoke @python-debugger to diagnose the failing test or error in the current directory.

세 플러그인의 파일 구조를 놓고 보면 차이가 선명하다. GitHub MCP와 Playwright MCP는 .mcp.json과 plugin.json 두 개뿐 — 도구(②)만 제공한다. debug-pack은 7개 파일로 구성요소 ①②③과 슬래시 커맨드, MCP 서버 2종까지 담았다. 파일 수가 역할의 완성도를 보여준다.

어떤 효과가 있나

debug-pack의 가장 큰 효과는 체계적인 가설 검증이다. 일반적으로 디버깅할 때는 "이게 문제인 것 같다 → 고쳐봄 → 아니면 저게 문제 → 고쳐봄"이라는 시행착오를 거친다. sequential-thinking 도구가 있으면 에이전트가 가설 A, B, C를 먼저 명시적으로 나열하고, 각각을 순서대로 검증한 뒤 근본 원인을 확정한다. 패닉 디버깅이 아니라 시스템적 분석이 된다.

두 번째 효과는 라이브러리 버그와 사용 오류의 구분이다. fetch 도구가 없으면 에이전트는 코드만 보고 판단해야 한다. 하지만 실제로는 외부 라이브러리의 알려진 버그인 경우가 많다. fetch로 라이브러리 GitHub 이슈를 직접 확인해서 "이것은 라이브러리 버전 2.1.3의 알려진 버그입니다. 2.1.4로 업그레이드하세요"라는 결론을 낼 수 있다.

세 번째 효과는 자산 재사용이다. debug-pack을 팀에 배포하면, 팀원 모두가 동일한 python-error-patterns 카탈로그와 동일한 디버깅 절차를 사용하게 된다. 시니어 개발자가 알고 있는 "흔한 오류 패턴"이 패키지 안에 들어 있어서, 주니어 개발자도 같은 수준의 첫 번째 판단을 받게 된다.

GitHub MCP, Playwright MCP, debug-pack 세 가지를 놓고 보면 패턴이 보인다. GitHub와 Playwright는 도구만 제공하고 "어떤 전문가로 만들지"는 사용자 결정이다. debug-pack은 "Python 디버깅 전문가"라는 역할까지 패키지 안에 완성되어 있다. 플러그인을 만들 때 이 중 어느 형태를 선택할지는 목적에 달려 있다. 범용 도구를 팀이 자유롭게 활용하게 하려면 도구만, 특정 전문 역할을 표준화하려면 완전한 패키지로 만드는 것이 맞다.

---

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