하네스 엔지니어링 위키

내 패턴 · 확장점: Subagents (에이전트 .md 정의 형식과 모델 라우팅)

15 min read

내 패턴 · 확장점: Subagents (에이전트 .md 정의 형식과 모델 라우팅)

한 줄 요약

서브에이전트는 메인 AI가 잠깐 불러내는 “전문 직원”으로, .md 파일 한 장에 이름표(YAML)와 행동 지침서(XML)를 적어두면 격리된 작업창·전용 역할·어울리는 모델(haiku/sonnet/opus)이 자동으로 배정된다. 왜 배우나: 일을 역할별로 쪼개고 “글 쓴 사람 ≠ 검사하는 사람” 규칙을 강제해야 AI가 자기 실수를 스스로 통과시키는 사고를 막을 수 있기 때문이다.

그림

flowchart TD
    U[오케스트레이터 메인 세션] -->|"Task: 어떤 에이전트, 무슨 작업"| W[작업 설명을 Worker Preamble로 감싸기]
    W --> P["해당 agents/이름.md 파일 읽기"]
    P --> M{frontmatter의 model 값 확인}
    M -->|haiku| H[저비용 모델로 격리 작업창 켜기]
    M -->|sonnet| S[표준 모델로 격리 작업창 켜기]
    M -->|opus| O[고성능 모델로 격리 작업창 켜기]
    H --> X[Agent_Prompt를 전용 업무규정으로 주입]
    S --> X
    O --> X
    X --> R[에이전트가 도구를 직접 써서 작업 수행]
    R --> Y[Output_Format 형식대로 결과 정리]
    Y --> U[마지막 메시지만 메인 세션에 반환]

쉽게 풀기

같은 회사 안에 세 종류의 직원이 있다고 상상하자.

  • 검색 인턴 (haiku): 자료를 빠르게 찾아오는 저렴한 인력. 깊은 판단은 안 시킨다.
  • 실무 담당 (sonnet): 실제로 코드를 짜고 검증하는 표준 인력.
  • 수석 설계자 (opus): 구조 설계와 심층 리뷰를 맡는 비싼 인력.

각 직원에게는 책상에 업무규정 종이 한 장이 붙어 있다. 이 종이가 바로 agents/<이름>.md 파일이다. 종이는 두 부분으로 나뉜다.

  1. 이름표/스펙 (맨 위 YAML): “이름은 executor, 쓰는 모델은 sonnet, 권한 등급은 2” 같은 기본 정보.
  2. 행동 지침서 (아래 XML): “너는 Executor다. 시키는 코드만 정확히 짜라. 설계는 하지 마라” 같은 상세 규칙.

서브에이전트가 강력한 이유는 세 가지를 동시에 못 박기 때문이다.

  • 격리된 작업창: 직원은 자기 칸막이 안에서만 일한다. 메인 대화창(상사의 책상)을 어지럽히지 않는다.
  • 전용 역할: “너는 코드만 짜라”처럼 책임 범위가 종이에 박혀 있어서 직원이 월권하지 않는다.
  • 모델 자동 배정: 단순 조회를 비싼 수석에게 시키지 않도록, 파일이 직접 어울리는 모델을 지정한다.

여기에 회사 전체 규칙이 하나 더 있다. “글 쓴 사람과 검사하는 사람은 반드시 달라야 한다(자기 승인 금지).” 코드를 짠 직원이 자기 코드를 스스로 합격 처리하면 사고가 나기 때문에, 검사는 항상 다른 직원(critic·verifier)에게 맡긴다.

핵심 정리

agents/<name>.md 파일은 YAML 이름표와 XML 행동 지침서 두 구역으로 나뉜다.

A. YAML frontmatter — 파일 맨 위, --- 사이

항목필수핵심 의미
name에이전트 식별자. oh-my-claudecode:<name>으로 호출 (예: executor, critic)
description한 줄 요약. 괄호로 모델/권한 표기 (예: ... (Opus, READ-ONLY))
model모델 라우팅의 핵심. haiku=조회·탐색, sonnet=표준 구현·검증, opus=설계·심층분석
level권한 계층(2~4). 2=실무 작업자, 3=분석·리뷰, 4=planner(최상위 계획)
disallowedTools차단할 도구. 리뷰·분석 계열은 보통 Write, Edit를 막아 읽기 전용으로 만듦

level 관측값과 disallowedTools 패턴

  • level 2(실무 작업자): executor·writer·designer·document-specialist
  • level 3(분석·리뷰): architect·critic·verifier·explore 등 대다수
  • level 4: planner(최상위 계획)
  • disallowedTools: Write, Edit는 리뷰어를 READ-ONLY로 만드는 장치. executor·debugger·writer 같은 쓰기 작업자에는 이 필드가 없다.

B. <Agent_Prompt> XML 본문 — frontmatter 아래 전체

태그빈도역할
<Role>필수정체성 + “무엇을 책임지고 / 무엇은 책임 안 지는지” 경계
<Why_This_Matters>필수이 규칙이 왜 있는지. 실패 비용을 설명해 진지하게 받게 함
<Success_Criteria>필수증거 기반 완료 판정 체크리스트
<Constraints>대부분금지·강제 규칙. 자기승인 금지·READ-ONLY·핸드오프 대상

그 외 자주 쓰이는 본문 태그

  • <Investigation_Protocol>: 단계별 수행 절차
  • <Tool_Usage>: 도구 사용 규칙. <External_Consultation> 하위에서 Task로 다른 에이전트 호출
  • <Execution_Policy>: 효력(effort)은 부모 세션 상속, behavioral effort guidance 명시
  • <Output_Format>: 결과물의 정확한 형태(표·섹션)
  • <Failure_Modes_To_Avoid> / <Examples> / <Final_Checklist>: 반례·예시·최종 점검
  • <Final_Response_Contract>(리뷰계열): “마지막 메시지가 곧 산출물” — 내용 없는 사인오프 금지 (critic/architect)

모델 라우팅 카탈로그 (관측 19종)

  • haiku (조회·저비용): explore(코드베이스 탐색), writer(문서) — 빠른 패턴매칭·문서화
  • sonnet (표준): executor, debugger, verifier, tracer, designer, document-specialist, git-master, qa-tester, scientist, test-engineer, security-reviewer — 일반 구현·검증·도메인 작업
  • opus (설계·심층): analyst, planner, architect, critic, code-reviewer, code-simplifier — 설계·계획·심층 리뷰

파일이 최종 진실

CLAUDE.md 카탈로그는 security-reviewer를 sonnet으로 적지만, 실제 security-reviewer.md의 frontmatter는 model: opus다. 카탈로그와 파일이 다르면 파일을 믿어라.

실제 예시

소스 발췌 1 — executor (쓰기 작업자, sonnet, Worker Preamble 명시)

// /home/seunghyeong/.claude/plugins/marketplaces/omc/agents/executor.md
---
name: executor
description: Focused task executor for implementation work (Sonnet)
model: sonnet
level: 2
---
 
<Agent_Prompt>
  <Role>
    You are Executor. Your mission is to implement code changes precisely as specified...
    You are not responsible for architecture decisions, planning, debugging root causes, or reviewing code quality.
 
    **Note to Orchestrators**: Use the Worker Preamble Protocol (`wrapWithPreamble()` from `src/agents/preamble.ts`) to ensure this agent executes tasks directly without spawning sub-agents.
  </Role>
  ...
  <Constraints>
    - Work ALONE for implementation. READ-ONLY exploration via explore agents (max 3) is permitted...
    - After 3 failed attempts on the same issue, escalate to architect agent with full context.
  </Constraints>

소스 발췌 2 — critic (리뷰어, opus, READ-ONLY + 자기승인 금지)

// /home/seunghyeong/.claude/plugins/marketplaces/omc/agents/critic.md
---
name: critic
description: Work plan and code review expert — thorough, structured, multi-perspective (Opus)
model: opus
level: 3
disallowedTools: Write, Edit
---
 
<Agent_Prompt>
  <Role>
    You are Critic — the final quality gate, not a helpful assistant providing feedback.
    The author is presenting to you for approval. A false approval costs 10-100x more than a false rejection...
  </Role>
  ...
  <Constraints>
    - Read-only: Write and Edit tools are blocked.
    - Hand off to: planner (plan needs revision), analyst (requirements unclear), architect (code analysis needed), executor (code changes needed)...
  </Constraints>

생명주기 — 메인 AI가 위임할 때 벌어지는 일

  1. 트리거: 메인 AI가 Task(subagent_type="oh-my-claudecode:executor", ...)로 위임 결정. delegation_rules에 따라 다중파일·리팩터·리뷰·계획은 위임한다.
  2. Preamble 래핑: 작업 설명을 wrapWithPreamble()로 감싼다. 이게 Worker Preamble Protocol — “직접 도구를 써서 일하라, 또 다른 서브에이전트를 스폰하지 마라”고 못 박아 무한 스폰 폭발을 막는 안전장치다.
  3. 파싱 + 라우팅: <name>.md의 model 값으로 띄울 모델을 결정하고, disallowedTools로 도구를 제한한다.
  4. 컨텍스트 주입: <Agent_Prompt> 전체가 그 서브에이전트의 전용 시스템 프롬프트가 된다. 메인 대화 히스토리는 안 들어간다(격리).
  5. 실행 → 반환: <Output_Format>대로 결과를 내고 마지막 메시지가 호출자에게 반환된다. critic·architect는 <Final_Response_Contract>로 이를 강제한다.

왜 같은 모델인데도 역할을 쪼개나

(a) 컨텍스트 오염 방지, (b) 역할별 비용 최적화(조회를 opus로 하면 낭비), (c) 권력 분립 — 코드를 짠 executor가 자기 코드를 승인하지 못하도록 critic/verifier를 별 컨텍스트로 분리한다.

핵심 계약 — 저자 ≠ 리뷰어 (자기승인 금지): 같은 규칙이 여러 곳에서 반복 강제된다.

  • OMC CLAUDE.md: “Keep authoring and review as separate passes… Never self-approve in the same active context; use code-reviewer or verifier for the approval pass.”
  • verifier.md Constraints: “Never self-approve or bless work produced in the same active context.”
  • writer.md Constraints: “do not self-review, self-approve, or claim reviewer sign-off in the same context.”
  • 다른 리포(/mnt/d/human-token-workflow/AGENTS.md)에서도 한국어로 재강제: “본 리포지토리에서 writer와 reviewer는 반드시 다른 에이전트. 자체 승인 금지.” → 같은 거버넌스가 OMC 플러그인뿐 아니라 사용자 작업 리포에도 퍼져 있다는 증거.

직접 만들 때 템플릿

// agents/my-validator.md  (예시: sonnet 검증 작업자)
---
name: my-validator
description: Schema/spec compliance validator for X (Sonnet, READ-ONLY)
model: sonnet
level: 3
disallowedTools: Write, Edit
---
 
<Agent_Prompt>
  <Role>
    You are MyValidator. Your mission is to verify X against the spec.
    You are responsible for compliance checking.
    You are not responsible for authoring or fixing (hand off to executor).
  </Role>
 
  <Why_This_Matters>
    Unverified compliance claims reach production and cost 10x to fix later.
  </Why_This_Matters>
 
  <Success_Criteria>
    - Every spec item has VERIFIED / PARTIAL / MISSING status with evidence
    - Fresh command output shown (not assumed)
  </Success_Criteria>
 
  <Constraints>
    - Read-only: Write/Edit blocked.
    - Never self-approve work produced in the same active context.
    - Hand off to: executor (fixes needed), critic (deeper review).
  </Constraints>
 
  <Output_Format>
    | # | Requirement | Status | Evidence |
    |---|-------------|--------|----------|
  </Output_Format>
</Agent_Prompt>

만들기 체크리스트

  • frontmatter에 name/description/model/level 4개 다 있나? (model은 haiku|sonnet|opus 중 하나)
  • 모델 선택이 일에 맞나? 조회→haiku, 표준→sonnet, 설계·심층→opus
  • 리뷰·분석 전용이면 disallowedTools: Write, Edit로 READ-ONLY 처리했나?
  • <Role>에 “responsible for / not responsible for”로 경계를 그었나?
  • 검증·리뷰 에이전트라면 “자기승인 금지 / 별 컨텍스트” 문구를 Constraints에 넣었나?
  • 작업자(쓰기)면 오케스트레이터에게 Worker Preamble을 쓰라는 Note를 넣어 재귀 스폰을 막았나?
  • <Output_Format>으로 호출자가 파싱 가능한 결과 형태를 정의했나?
  • 핸드오프 대상(실패 시 누구에게 넘기나)을 명시했나?

요약 & 셀프체크

  • 서브에이전트 = .md 파일 한 장(YAML 이름표 + XML 지침서)으로 정의되는 격리된 전문 직원이다.
  • frontmatter의 model이 라우팅의 핵심(haiku/sonnet/opus), disallowedTools가 READ-ONLY를 만든다.
  • “저자 ≠ 리뷰어(자기승인 금지)“와 “Worker Preamble(재귀 스폰 금지)“가 두 개의 핵심 안전장치다.

스스로 답해보기

  1. 코드베이스를 빠르게 훑는 단순 탐색 에이전트라면 model에 무엇을 넣어야 하고, 그 이유는?
  2. 리뷰어를 읽기 전용으로 만들려면 frontmatter에 어떤 필드를 추가하나?
  3. executor가 자기가 짠 코드를 스스로 합격 처리하지 못하게 막는 규칙의 이름은 무엇인가?

연결

MINE_개요 · _분석축_루브릭

Codex 교차검증 보존

CLAUDE.md 카탈로그는 security-reviewer를 sonnet으로 표기하지만 실제 security-reviewer.md frontmatter는 model: opus다. 카탈로그와 개별 파일이 충돌할 경우 개별 .md 파일이 최종 진실이라는 원칙을 따른다.

근거 파일

  • /home/seunghyeong/.claude/plugins/marketplaces/omc/agents/executor.md (sonnet, level 2, Worker Preamble Note, “Work ALONE”, 3-fail escalation)
  • /home/seunghyeong/.claude/plugins/marketplaces/omc/agents/critic.md (opus, level 3, disallowedTools: Write Edit, Final_Response_Contract, 10-100x 비용 논리)
  • /home/seunghyeong/.claude/plugins/marketplaces/omc/agents/architect.md (opus, level 3, READ-ONLY)
  • /home/seunghyeong/.claude/plugins/marketplaces/omc/agents/explore.md (haiku, level 3, 조회 전용)
  • /home/seunghyeong/.claude/plugins/marketplaces/omc/agents/writer.md (haiku, level 2, “do not self-review/self-approve”)
  • /home/seunghyeong/.claude/plugins/marketplaces/omc/agents/verifier.md (sonnet, level 3, “Never self-approve in the same active context”)
  • /home/seunghyeong/.claude/plugins/marketplaces/omc/agents/ (전체 19종 frontmatter: name/model/level/disallowedTools)
  • /home/seunghyeong/.claude/plugins/marketplaces/omc/CLAUDE.md (model_routing, agent_catalog 19종, “Never self-approve in the same active context”)
  • /home/seunghyeong/.claude/plugins/marketplaces/omc/docs/agent-templates/base-agent.md (“Worker Preamble Protocol”, wrapWithPreamble, “executes tasks directly without spawning sub-agents”)
  • /home/seunghyeong/.claude/plugins/marketplaces/omc/dist/... omcSystemPrompt 내 “Available Subagents (19 Agents)” 카탈로그 + Deprecated Aliases
  • /mnt/d/human-token-workflow/AGENTS.md (라인 21: “writer와 reviewer는 반드시 다른 에이전트. 자체 승인 금지.”)

그래프 뷰

백링크