OMC - Agent System

시리즈: oh-my-claudecode 내부 구조부터 플러그인 개발까지

이 시리즈는 Claude Code 플러그인 시스템의 내부 동작을 단계별로 해부하고, 최종적으로 나만의 플러그인을 직접 개발하는 것까지 도달하는 과정이다.

편	내용	핵심
1편	Plugin Anatomy	plugin.json 하나로 시작하는 플러그인 뼈대
2편	Hook System	이벤트 → stdin JSON → 스크립트 → stdout JSON
3편	Skill System	SKILL.md로 워크플로우를 정의하는 방법
4편 (본문)	Agent System	Task tool로 위임되는 실제 작업 수행자
5편	MCP Tools Bridge	LSP, AST 등 커스텀 도구 서버
6편	State & Lifecycle	.omc/ 상태 관리와 모드 지속
7편	Parallel Orchestration	Ultrawork, Team, Autopilot, Ralph 패턴

---

• OMC의 Agent는 특정 역할에 전문화된 서브에이전트 정의 단위
• Claude Code의 Task tool로 생성되며, 각 에이전트는 자신만의 프롬프트(agents/*.md), 모델, 도구 제한을 가지는 구조
• 공식 Agent 시스템(YAML frontmatter + 마크다운 본문) 위에 OMC가 19개 전문 에이전트와 3-Tier 모델 라우팅을 얹은 확장 패턴

해당 개념이 필요한 이유

• 3편(Skill System)에서 Skill이 “병렬로 에이전트를 활용하라”고 Claude에게 지시하는 것까지 학습
• 하지만 **“어떤 에이전트가 있고, 각각 뭘 할 수 있고, 어떤 모델을 쓰는지”**가 빠져 있음
• Agent System이 이 빈 칸을 채움 — Skill이 지침서라면 Agent는 전문화된 실행자

AS-IS

sequenceDiagram
    autonumber
    participant SK as Skill (ultrawork)
    participant CC as Claude Code

    SK-->>CC: "독립 작업은 병렬로 에이전트를 활용하라"
    CC->>CC: "에이전트가 뭔데? 어떤 걸 골라야 하지?"
    Note over CC: 에이전트 정의가 없으므로<br/>기본 Claude 하나로 모든 작업 처리

TO-BE

sequenceDiagram
    autonumber
    participant SK as Skill (ultrawork)
    participant CC as Claude (Orchestrator)
    participant TT as Task Tool
    participant AG as executor Agent

    SK-->>CC: "독립 작업은 병렬로 에이전트를 활용하라"
    CC->>CC: 작업 분석 → executor 에이전트 선택
    CC->>TT: Task(subagent_type="oh-my-claudecode:executor", model="sonnet")
    TT->>AG: agents/executor.md 프롬프트 + 도구 제한 주입
    AG->>AG: 독립적으로 작업 수행
    AG-->>CC: 결과 반환
    Note over CC: 여러 에이전트를 병렬로 실행하여<br/>처리 시간 단축

공식 Agent 시스템 vs OMC 확장

OMC의 Agent는 공식 Agent 시스템 위에 구축된다. 공식 기능과 OMC 고유 기능을 구분하는 것이 중요하다.

구분	공식 Claude Code	OMC 확장
파일 구조	YAML frontmatter + 마크다운 본문 (agents/*.md)	동일 구조에 역할별 19개 에이전트 사전 정의
호출 방식	Task(subagent_type="plugin:agent-name")	동일 (Skill이 자동으로 적절한 에이전트 선택 지시)
모델 지정	frontmatter model 필드	3-Tier 라우팅 (opus/sonnet/haiku)
도구 제한	disallowedTools	에이전트별 역할 기반 제한 (explore는 Read-only 등)
메타데이터	없음	src/agents/definitions.ts에 TypeScript 정의

Agent 정의 구조 — 2가지 레이어

각 에이전트는 마크다운 프롬프트와 TypeScript 메타데이터 두 레이어로 정의된다.

레이어 1: agents/*.md — 프롬프트 파일

---
name: executor
model: claude-sonnet-4-6
description: "Focused task executor for implementation work (Sonnet)"
---
 
## Role
Implement code changes precisely.
 
## Success Criteria
- Minimal viable diffs
- Zero LSP errors
- Passing tests
- Code pattern matching

YAML frontmatter에 name, model, description이 있고, 본문이 에이전트의 행동 지침이 된다. 공식 Skill의 frontmatter 구조와 동일한 패턴.

레이어 2: src/agents/definitions.ts — 메타데이터

const executorAgent = {
  name: 'executor',
  model: 'claude-sonnet-4-6',
  description: 'Focused task executor for implementation work',
  prompt: loadAgentPrompt('executor'),  // agents/executor.md 로드
  disallowedTools: [],                  // 사용 불가 도구
};

마크다운만으로는 표현하기 어려운 disallowedTools 같은 런타임 제약을 TypeScript로 관리한다.

19개 에이전트와 3-Tier 모델 라우팅

OMC는 작업 복잡도에 따라 3개 모델 티어로 에이전트를 분류한다:

graph LR
    subgraph HIGH["HIGH (opus) — 깊은 분석"]
        A1["architect"]
        A2["analyst"]
        A3["planner"]
        A4["critic"]
        A5["code-reviewer"]
        A6["code-simplifier"]
    end

    subgraph MEDIUM["MEDIUM (sonnet) — 표준 작업"]
        B1["executor"]
        B2["debugger"]
        B3["verifier"]
        B4["tracer"]
        B5["security-reviewer"]
        B6["test-engineer"]
        B7["designer"]
        B8["qa-tester"]
        B9["scientist"]
        B10["document-specialist"]
        B11["git-master"]
    end

    subgraph LOW["LOW (haiku) — 빠른 조회"]
        C1["explore"]
        C2["writer"]
    end

전체 에이전트 목록

에이전트	모델	역할	핵심 특징
explore	haiku	파일/코드 탐색	Read-only. Write, Edit 사용 금지
executor	sonnet	코드 구현	서브에이전트 생성 금지
architect	opus	아키텍처 설계	전략적 판단, 검증
planner	opus	작업 분해/계획	단계별 계획 수립
analyst	opus	깊은 분석	다각도 분석
critic	opus	비판적 검토	코드 리뷰, 약점 발견
debugger	sonnet	버그 추적	에러 원인 분석
verifier	sonnet	결과 검증	테스트 실행, 증거 수집
test-engineer	sonnet	테스트 작성	TDD, 테스트 전략
designer	sonnet	UI/프론트엔드	프론트엔드 구현
document-specialist	sonnet	문서 조사	API 문서, 라이브러리 레퍼런스
writer	haiku	문서 작성	마크다운, README
git-master	sonnet	Git 작업	커밋, PR, 브랜치 관리
security-reviewer	sonnet	보안 검토	OWASP, 취약점 분석
code-reviewer	opus	코드 리뷰	종합적 리뷰
code-simplifier	opus	코드 단순화	복잡도 감소, 리팩터
qa-tester	sonnet	QA 테스트	통합 테스트, E2E
scientist	sonnet	실험/검증	가설 검증, A/B 비교
tracer	sonnet	추적/디버그	실행 흐름 추적

모델 선택 기준

티어	모델	사용 기준	비용/속도
HIGH	opus	설계, 분석, 비판적 판단 등 깊은 사고가 필요한 작업	비용 높음, 느림
MEDIUM	sonnet	구현, 디버그, 테스트 등 표준 실행 작업	중간
LOW	haiku	탐색, 문서 작성 등 빠른 조회/출력 작업	비용 낮음, 빠름

Delegation Protocol — 위임 프로토콜

Orchestrator(Claude)가 에이전트에게 작업을 위임하는 흐름:

sequenceDiagram
    autonumber
    participant O as Orchestrator (Claude)
    participant T as Task Tool
    participant A as Agent

    O->>O: 1. 작업 분석: 어떤 에이전트가 적합한가?
    Note over O: explore=탐색, executor=구현,<br/>architect=설계, planner=계획
    O->>O: 2. 모델 선택: 작업 복잡도에 따라
    Note over O: haiku=빠른조회, sonnet=표준, opus=깊은분석
    O->>T: 3. Task(subagent_type, model, prompt, run_in_background?)
    T->>A: agents/*.md 프롬프트 주입 + 도구 제한 적용
    A->>A: 4. 독립적으로 작업 수행
    A-->>O: 5. 결과 반환

도구 제한 (disallowedTools)

에이전트마다 사용 가능한 도구가 다르다. disallowedTools로 역할 범위를 강제한다:

에이전트	제한	이유
explore	Write, Edit 사용 금지 (YAML disallowedTools)	읽기 전용 — 탐색만 수행
architect, analyst, critic, code-reviewer, scientist, document-specialist	Write, Edit 사용 금지 (YAML disallowedTools)	분석/리뷰 전용 — 코드 변경 차단
executor	프롬프트 지침: “Work ALONE”	직접 실행만 — 재위임 자제 (소프트 제한)

YAML disallowedTools는 하드 제한(도구 자체가 차단), 프롬프트 지침은 소프트 제한(LLM이 따르도록 유도)이다. 두 방식을 조합하여 에이전트 역할을 강제한다.

나만의 플러그인을 만든다면

커스텀 에이전트 정의:

my-plugin/
└── agents/
    └── my-agent.md

---
name: my-agent
model: claude-sonnet-4-6
description: My custom agent for code review automation
---
 
## Role
너는 코드 리뷰에 전문화된 에이전트다.
 
## Rules
- 항상 변경된 파일의 diff를 먼저 분석하라
- 보안 이슈는 반드시 경고하라
- 변경 사항은 최소화하라

Claude가 Task(subagent_type="my-plugin:my-agent")로 호출한다. (OMC의 경우 접두사가 oh-my-claudecode:) plugin.json에 "agents": "./agents/" 설정이 있으면 자동 인식.

Deep Dive 토픽

• Agent Definition & Config — agents/*.md 구조, YAML frontmatter, AgentConfig 타입
• Agent Tiering — 3-Tier 모델 라우팅, 비용/품질 트레이드오프
• Delegation Protocol — Task tool, subagent_type, run_in_background, 도구 제한

참고 문서

• Claude Code Agents 공식 문서
• OMC - Skill System — Skill이 Agent를 호출하는 흐름 (3편)
• OMC - Parallel Orchestration — 여러 Agent를 병렬 실행하는 패턴 (7편)

---

다음: 5편 MCP Tools Bridge — 에이전트가 실행 중에 기본 도구(Read, Write, Bash)로는 부족한 작업이 있다. MCP 서버가 어떤 커스텀 도구를 제공하고, 어떻게 등록되는지를 다음 파트에서 다룬다.