오래된 SW 엔지니어의 평생 공부

Claude Code의 확장 메커니즘들을 비교 분석해봅시다.

Agents, Custom Command(Workflow라고 부르는 분도 있습니다.) 그리고 이것들을 묶어 주는 Plugin이 있습니다. 이 때, Skill도 추가되었는데요. Plugin과 따로 쓸 수도 있다고 합니다.

1. Agents (Sub-agents)

개념

특정 전문 분야에 특화된 AI 페르소나로, Claude Code가 작업을 위임할 수 있는 전문가들입니다.

구조

---
name: bug-analyst
description: Issue triage and classification expert
tools: []
---

# Agent Definition
You are a specialized bug analyst expert...

특징

• 위치: ~/.claude/agents/ 또는 프로젝트 내 .claude/agents/
• 자동 감지: Claude Code가 자동으로 로드
• 동적 호출:
  • 자동: Claude가 컨텍스트 분석 후 적절한 agent 선택
  • 수동: "Use the bug-analyst agent to..."
• 병렬 실행: 여러 agent를 동시에 실행 가능
• 토큰 사용: 각 agent가 독립적인 컨텍스트를 가지므로 토큰 사용량 증가

사용 예시

# 자동 선택
"Analyze this bug and suggest a fix"
→ Claude가 bug-analyst 선택

# 명시적 호출
"Have the backend-architect review this API design"

장점

• ✅ 전문성 분리 (separation of concerns)
• ✅ 컨텍스트 격리로 명확한 역할 구분
• ✅ 재사용성 높음
• ✅ 팀 간 공유 가능

단점

• ❌ 높은 토큰 소비
• ❌ 각 agent마다 컨텍스트 로딩 필요
• ❌ Agent 간 통신 오버헤드

2. Custom Commands (Workflows)

개념

미리 정의된 작업 시퀀스를 슬래시 명령어로 실행하는 워크플로우 자동화 도구입니다.

구조

---
name: bug-fix-workflow
description: Systematic bug investigation and resolution
---

# Bug Fix Workflow

When this command is invoked with /bug-fix-workflow [description]:

1. **Bug Analysis Phase**
   - Use QA Test Engineer to reproduce the bug
   - Document the reproduction steps

2. **Implementation Phase**
   - Use Implementation Engineer to fix the bug

3. **Validation Phase**
   - Use QA Test Engineer to validate the fix

특징

• 위치: ~/.claude/commands/ 또는 .claude/commands/
• 호출 방식: /command-name [arguments]
• 순차 실행: 정해진 순서대로 agent들을 오케스트레이션
• 워크플로우 정의: 복잡한 다단계 프로세스 자동화
• 품질 게이트: 각 단계별 검증 포인트 설정 가능

사용 예시

/bug-fix-workflow "User login fails with 500 error"

/feature-workflow "Create user authentication with JWT"

/code-review-workflow src/components/

장점

• ✅ 복잡한 워크플로우 자동화
• ✅ 일관된 프로세스 보장
• ✅ 여러 agent를 조율하는 오케스트레이션
• ✅ 재현 가능한 작업 흐름

단점

• ❌ 유연성 부족 (미리 정의된 순서)
• ❌ 수정하려면 파일 편집 필요
• ❌ 조건부 분기 구현이 복잡

3. Claude Code Plugins (최신 추가)

개념

모듈식 패키지 시스템으로, agents + commands + skills를 하나의 논리적 단위로 묶어 관리합니다.

구조

plugin-name/
├── agents/           # 관련 agents
│   ├── agent1.md
│   └── agent2.md
├── commands/         # 관련 commands
│   └── workflow.md
├── skills/           # 지식 패키지
│   ├── skill1.md
│   └── skill2.md
└── plugin.json       # 메타데이터

특징

• 위치: ~/.claude/plugins/ 또는 프로젝트 내
• 설치 방식:
• /plugin install python-development/plugin install kubernetes-operations
• 점진적 로딩: 필요할 때만 활성화 (progressive disclosure)
• 스킬 시스템: 자동 활성화되는 전문 지식 패키지
• 의존성 관리: 플러그인 간 의존성 정의 가능
• 마켓플레이스: 중앙화된 플러그인 저장소

Skills의 개념

---
name: kubernetes-deployment
type: skill
activates_on: ["kubernetes", "k8s", "deployment"]
---

# Kubernetes Deployment Skill
This skill provides specialized knowledge about...

• 특정 키워드나 컨텍스트에서 자동 활성화
• Agent에게 전문 지식을 "주입"
• 토큰 효율적 (필요할 때만 로드)

사용 예시

# 플러그인 설치
/plugin install python-development

# 자동 활성화
"Create a FastAPI microservice"
→ python-development 플러그인의 agents, skills 활성화
→ 관련 commands 사용 가능

# 플러그인 전용 명령어
/python-development:python-scaffold fastapi-microservice

장점

• ✅ 모듈화: 관련 기능을 논리적으로 그룹화
• ✅ 토큰 효율성: 필요한 것만 로드 (최소 토큰 사용)
• ✅ 버전 관리: 플러그인 단위로 업데이트
• ✅ 의존성 해결: 자동으로 필요한 플러그인 설치
• ✅ 컴포저빌리티: 여러 플러그인 조합 가능
• ✅ 배포 용이성: 팀 전체에 표준화된 도구 배포

단점

• ❌ 최신 기능 (일부 도구만 지원)
• ❌ 설정 복잡도 증가
• ❌ 플러그인 간 충돌 가능성

비교표

실제 사용 시나리오

Scenario 1: 단순 전문가 자문

"Review this code for security issues"

최적: Agent (security-auditor)

• 단일 전문가의 의견만 필요
• 빠르고 직접적

Scenario 2: 복잡한 다단계 프로세스

/feature-workflow "User authentication system"

최적: Command (workflow)

• 여러 단계를 거쳐야 함
• 품질 게이트 필요
• 일관된 프로세스 보장

Scenario 3: 특정 기술 스택 작업

/plugin install python-development
"Create a FastAPI app with SQLAlchemy"

최적: Plugin

• 관련된 모든 도구 한번에 활성화
• 자동으로 적절한 skills 로드
• 토큰 효율적

아키텍처 관점

Layer 구조

┌─────────────────────────────────────┐
│         Plugins (최상위)             │
│  - python-development                │
│  - kubernetes-operations             │
└────────────┬────────────────────────┘
             │ contains
    ┌────────┴─────────┐
    │                  │
┌───▼──────────┐  ┌───▼──────────┐
│   Agents     │  │  Commands    │
│  (전문가)     │  │ (워크플로우)  │
└──────────────┘  └──────────────┘
         │              │
         └──────┬───────┘
                │ uses
         ┌──────▼──────┐
         │   Skills    │
         │ (지식 패키지) │
         └─────────────┘

권장 사항

언제 Agent를 사용할까?

• ✅ 단일 전문가의 의견이 필요할 때
• ✅ 유연한 대화형 상호작용이 필요할 때
• ✅ 빠른 프로토타이핑

언제 Command를 사용할까?

• ✅ 반복적인 다단계 프로세스
• ✅ 팀 전체가 따라야 하는 표준 워크플로우
• ✅ 품질 게이트가 필요한 프로세스

언제 Plugin을 사용할까?

• ✅ 관련 기능을 패키지로 배포
• ✅ 토큰 효율성이 중요할 때
• ✅ 버전 관리와 의존성 해결이 필요할 때
• ✅ 대규모 팀에서 표준화된 도구 배포

진화 경로

2024 초반: Agents만 존재
    ↓
2024 중반: Commands 추가 (워크플로우 오케스트레이션)
    ↓
2024 후반/2025: Plugins 도입 (모듈화 + 토큰 효율성)

Plugins는 Agents와 Commands의 장점을 결합하면서 토큰 효율성과 배포 편의성을 크게 개선한 최신 접근 방식입니다.

첨부하신 bug-analyst.md는 Agent 형식이므로, Plugin 시스템으로 마이그레이션하면 다음과 같은 구조가 될 것입니다:

bug-analysis-plugin/
├── agents/
│   ├── bug-analyst.md
│   ├── error-detective.md
│   ├── code-diagnostician.md
│   └── fix-architect.md
├── commands/
│   └── bug-fix-workflow.md
├── skills/
│   ├── python-debugging.md
│   └── react-debugging.md
└── plugin.json

이렇게 구조화하면 /plugin install bug-analysis로 한번에 모든 버그 분석 도구를 활성화할 수 있습니다! 아참, Plugin은 Maketplace로 만들어야 됩니다. 다른 plugin 참고하세요.