🦞 13. Subagents 설계와 프롬프트

Subagent는 “에이전트를 많이 띄우는 기능”이 아니라, 메인 대화가 붙잡히지 않게 무거운 일을 옆방으로 잠깐 분리하는 방법에 가깝다. 그래서 처음 설계할 때 가장 중요한 질문도 단순하다. 이 일은 지금 메인이 바로 답해야 하는가, 아니면 백그라운드에서 따로 끝내고 가져오면 되는가? 이 기준만 잡히면 subagent는 복잡한 기능이 아니라 운영 정리 도구가 된다.

실무에서는 특히 아래 3가지에서 체감이 크다.

• 리서치가 길어서 메인 응답을 붙잡아 둘 때
• 문서 검수·코드 생성처럼 한 번에 끝나지 않는 작업이 생길 때
• 메인은 사용자와 대화하고, 서브는 자료 수집·초안 제작을 맡겨야 할 때

먼저 흐름만 빨리 잡고 싶다면 10. OpenCode와 17. 실패패턴도 같이 보면 좋다.

결론 먼저

Subagent 설계의 핵심은 화려한 프롬프트보다 출력 계약을 먼저 고정하는 것이다. 무엇을 받아오면 성공인지, 어디까지 하고 끝내야 하는지, 막히면 무엇으로 우회할지를 먼저 써 두면 품질이 급격히 안정된다.

칠판 판서형 치트시트

1. 메인은 사용자 응답과 최종 판단을 맡는다.
2. subagent는 무거운 조사·검수·초안 작업만 분리한다.
3. 프롬프트보다 먼저 목표/범위/출력형식/완료기준을 고정한다.
4. 결과는 바로 보내지 말고 메인이 검수 후 통합한다.
5. 반복 실패 패턴은 다음 프롬프트 버전에 규칙으로 흡수한다.

30초 판단: 지금 subagent가 필요한가

• 바로 답해야 하는 짧은 설명이면 메인이 직접 처리한다.
• 5분 넘게 걸릴 조사·수집·검수면 subagent를 붙인다.
• 코드 수정·실행·테스트가 핵심이면 OpenCode나 ACP 경로를 먼저 본다.
• 같은 실패가 반복되는 작업이면 subagent보다 출력 계약부터 다시 설계한다.

0) OpenClaw Subagents 기능/정의 (먼저 알아야 할 핵심)

Subagents는 메인 실행 중 백그라운드로 띄우는 분리 세션 실행기다.

• 생성 도구: sessions_spawn
• 세션 형태: agent:<agentId>:subagent:<uuid>
• 동작: 비동기(non-blocking)로 시작되고, 끝나면 결과를 메인 채팅에 announce
• 목적: 느린 작업/긴 리서치/병렬 처리 분리
• 제약: subagent가 또 다른 subagent를 spawn할 수는 없음

flowchart LR
A[메인 에이전트 요청 수신] --> B{작업이 무겁거나 오래 걸리는가?}
B -->|No| C[메인이 직접 처리]
B -->|Yes| D[sessions_spawn으로 Subagent 실행]
D --> E[분리 세션에서 실행]
E --> F[announce 결과]
F --> G[메인이 검수/통합 후 전달]

1) 우리가 실제로 쓰는 구조 (교과서형 X)

운영 구조

1. 메인 직접 처리를 기본값으로 둔다.
2. 길거나 무거운 작업만 단일 subagent를 붙인다.
3. 결과를 메인이 검수해 최종 응답한다.

이 방식의 장점

• 대화 속도가 떨어지지 않음
• “지금 답해야 하는 것”과 “백그라운드 일”을 분리 가능
• 품질 기준을 메인에서 일관되게 유지 가능

현장 미니 사례 2개

사례 A. 잘된 사용

사용자가 “정부지원사업 이번 달 것만 공식 링크로 정리해줘”라고 했을 때, 메인은 범위와 결과 형식을 먼저 정하고 subagent에는 공식 사이트 스캔 + 표 작성만 맡긴다. 그러면 메인은 사용자와 대화를 이어 가면서도, 나중에 결과만 검수해 깔끔하게 통합할 수 있다.

사례 B. 잘 안 되는 사용

사용자가 그냥 “좋게 정리해줘”라고 했는데, 메인이 목표·범위·형식을 안 준 채 subagent를 띄우면 결과가 길고 애매해진다. 이 경우 문제는 subagent 성능보다 계약 없는 요청에 있다.

1-1) 실제로 구성해 쓴 Subagent 예시

아래는 이 문서를 만들 때 기준으로 삼은 실제 운영 케이스다.

• llm-4h-course-builder
  • 목적: 4시간 LLM 교육안 병렬 설계
  • 산출물: 시간표/실습/평가 프롬프트 패키지
• startup-support-march-scan
  • 목적: 3월 정부지원사업 공식 소스 스캔
  • 산출물: 공공기관 중심 후보 리스트 + 링크
• 야간조-EP03-검수루프
  • 목적: 소설 에피소드 다중 검수(문제찾기→수정)
  • 산출물: 라운드별 수정본 + 검수 로그
• 교육요청메일-모니터 (isolated cron)
  • 목적: 신규 교육요청 메일 감시
  • 산출물: 조건 충족 시 즉시 알림 메시지

핵심은 “서브에이전트를 많이 두는 것”이 아니라, 작업 단위별로 짧게 띄우고 종료하는 방식이다.

2) Subagent 프롬프트 설계 방식 (핵심은 ‘계약’)

좋은 프롬프트 1개보다 중요한 건 **출력 계약(Output Contract)**이다.

항목	설계 질문	예시
목표	무엇을 끝내면 완료인가?	3월 지원사업 공식 소스만 스캔
범위	무엇을 포함/제외할까?	공식 사이트 포함, 블로그 제외
입력	어떤 파일/기간/조건을 쓸까?	최근 30일, 서울/중기 키워드
출력 계약	어떤 형식으로 낼까?	표 + 링크 + 요약 3줄
완료 기준	합격 조건을 수치화했나?	최소 5건, 중복 0건
실패 시 규칙	막히면 어떻게 우회할까?	Browser 실패 시 API fallback
주의사항	반드시 피할 것	추측 작성, 형식 이탈, 민감정보 노출

3) Subagent를 ‘키우는’ 방법 (피드백 반영 루프)

실전에서는 아래 루프로 안정화한다.

1. 작성
2. 문제찾기
3. 수정
4. 실패 패턴을 다음 프롬프트에 규칙으로 흡수

flowchart TD
A[1차 실행] --> B[문제 수집]
B --> C[프롬프트 계약 패치]
C --> D[재실행]
D --> E{기준 통과?}
E -->|No| B
E -->|Yes| F[운영 템플릿으로 고정]

실제로 품질이 좋아지는 지점

• “잘 해줘”를 버리고 형식/판정/예외처리를 고정할 때
• 실패 원인을 다음 버전에 바로 반영할 때
• 최종 의사결정을 사람이 한 번 더 검토할 때

4) 활용 도구 맵 (Subagents + OpenCode)

기본 도구 조합

• 조사/수집: web_search, web_fetch, read
• 로컬 실행/검증: exec, process
• 세션 분리: sessions_spawn, sessions_list, sessions_history
• 자동화: cron (isolated agentTurn)

OpenCode 연계 포인트

• 코드 생성/수정/테스트가 필요한 구간은 OpenCode를 함께 사용한다.
• 운영 흐름:
  1. Subagent가 요구사항/검증기준 정리
  2. OpenCode에서 코드 작성·실행
  3. 메인이 결과를 검수해 최종 전달

5) 바로 쓰는 템플릿

A) Subagent 작업 지시 템플릿

목표: [한 줄]
범위: [포함/제외]
입력: [파일/링크/기간]
출력형식: [고정 포맷]
완료기준: [정량]
실패시: [fallback]
주의: [추측/형식이탈/민감정보]

B) 문제찾기 템플릿

아래 결과에서 문제만 찾아라.
형식:
- 문제
- 영향
- 수정안
최소 5개, 중요도(Critical/Major/Minor) 표시

C) OpenCode 연계 템플릿

작업요청: 코드 구현 및 검증
목표: [기능]
입력: [파일/환경]
성공판정:
1) 테스트 통과
2) 에러 0개
3) 실행 로그 요약 5줄
실패시 우회:
- 원인 1줄
- 다음조치 1줄

6) 영상 훅으로 쓰는 방법 (실전)

• 훅 메시지: “설치보다 운영이 진짜다”
• 데모 구성:
  1. 메인에서 요청 수신
  2. subagent 백그라운드 실행
  3. OpenCode로 코드 작업 처리
  4. 메인이 통합 결과를 깔끔히 보고

이렇게 보여주면 단순 설치 영상과 달리 “실무 운영 역량”이 보인다.

7) 목적형 Subagent 재사용 아키텍처

일회성 실행만 반복하면 품질이 매번 흔들린다. 그래서 목적별로 Subagent를 묶어 재사용하는 방식이 효율적이다.

7-1) 운영 구조

flowchart LR
A[요청 접수] --> B{목적 분류}
B --> C[Research Agent]
B --> D[Validation Agent]
B --> E[Builder Agent]
B --> F[Monitor Agent]
C --> G[표준 출력 계약]
D --> G
E --> G
F --> G
G --> H[메인 통합 보고]

7-2) 목적별 카탈로그(예시 4종)

• 리서치 스캔 → research-scan
  • 입력 템플릿: 기간/키워드/소스범위
  • 출력 계약: 링크 포함 요약표 + 우선순위
• 문서 검수 → doc-validator
  • 입력 템플릿: 초안 본문/검수기준
  • 출력 계약: Critical/Major/Minor 이슈 목록
• 산출물 제작 → course-builder
  • 입력 템플릿: 요구사항/시간/대상자
  • 출력 계약: 커리큘럼+실습안+평가기준
• 모니터링 → mail-monitor
  • 입력 템플릿: 계정/필터/주기
  • 출력 계약: 신규 이벤트 알림(조건충족만)

7-3) 재사용 규칙

1. 목적별로 입력/출력/성공기준을 문서에 고정한다.
2. 실행 시에는 변수(기간, 키워드, 대상)만 바꿔 호출한다.
3. 실패 패턴은 다음 버전에 즉시 반영해 템플릿을 업데이트한다.
4. 최종 전달 형식은 메인이 일관되게 유지한다.

7-4) 바로 쓰는 목적형 템플릿

(1) Research Agent

목표: 공식 소스 기반 이슈 스캔
입력: 기간={기간}, 키워드={키워드}, 소스={공식 사이트 목록}
출력: [항목명|요약|링크|상태] 표 5건 이상
성공기준: 중복 0건, 링크 누락 0건

(2) Validation Agent

목표: 초안 품질 검수
입력: 본문={문서}, 기준={정확성/가독성/누락}
출력: Critical/Major/Minor 이슈 목록 + 수정 제안
성공기준: 재현 가능한 지적 최소 5건

(3) Builder Agent

목표: 요구사항 기반 산출물 제작
입력: 요구사항={목표/대상/시간}
출력: 구조화된 결과물(목차+실행안+체크리스트)
성공기준: 즉시 실행 가능한 단계형 문서

(4) Monitor Agent

목표: 조건 기반 이벤트 감지
입력: 필터={발신자/주제/기간}, 주기={n분}
출력: 조건 충족 이벤트만 간결 알림
성공기준: 오탐 최소화, 동일 이벤트 중복 알림 방지

다음에 같이 보면 좋은 문서

• 10. OpenCode — 코드 실행·수정 작업을 어디서 분리할지 판단할 때
• 17. Subagents 실패패턴 5가지 — 왜 결과가 흔들리는지 빠르게 잡을 때
• 25. 크론·서브에이전트 분산운영 — 정기 실행과 세션 분리를 함께 설계할 때

AI 활용 고지

이 문서는 생성형 AI를 활용해 초안을 구성했고, 실제 운영 사례 기준으로 사람 검토 후 정리했다.