04 에이전트 Markdown

Skill 아키텍처 분석 — 중첩 호출 vs 인라인

오케스트레이터 스킬의 중첩 호출 구조를 토큰 흐름으로 추적하고 인라인 절충안을 도출한 분석

Source: src/content/docs/skill-architecture-analysis.md
Order: 58

한눈에 보기

/team 같은 오케스트레이터 스킬이 하위 스킬을 중첩 호출할 때 발생하는 죽은 토큰 문제를 정량 추적하고, 세 가지 구조의 트레이드오프를 비교한 분석입니다.

핵심 질문: 스킬을 중첩 호출할 것인가, 인라인할 것인가, 서브에이전트로 위임할 것인가?
읽는 대상: 스킬/오케스트레이터 구조를 설계하는 사람
연결 문서: Agent 위임 구조 비교 분석, Agent Orchestration

중첩 스킬 호출 vs 개별 호출 효율성 비교 및 최적화 권장안

1. 현재 아키텍처

호출 체인

/team (slash command)
  ├─ Skill("superpowers:brainstorming")     ← 1단계: 설계
  │    └─ 출력: docs/plans/설계문서.md
  ├─ Skill("superpowers:writing-plans")     ← 2단계: 계획
  │    └─ 출력: docs/plans/구현계획.md
  └─ Agent("team-orchestrator")             ← 3단계: 실행
       ├─ team-lead (opus)
       ├─ architect (sonnet)
       ├─ db-admin (sonnet)
       ├─ frontend-dev (sonnet)
       ├─ backend-dev (sonnet, worktree)
       └─ qa-tester (sonnet)

Phase 흐름

Brainstorming → Plan → Phase 0 (분석) → Phase 1 (설계) → Phase 2 (DB)
→ Phase 3 (구현) → Phase 4 (QA) → Phase 5 (마무리)

2. 토큰 흐름 상세 추적

현재 구조의 토큰 누적

시점	이벤트	추가 토큰	누적 토큰	비고
T1	`/team` 로드	500	500	스킬 내용 로드
T2	brainstorming 스킬 로드	2,000	2,500	Skill() 호출 결과
T3-T6	사용자 대화 (설계)	8,000	10,500	질문-응답 4~5턴
T7	writing-plans 스킬 로드	2,000	12,500	Skill() 호출 결과
T8-T10	계획 작성	3,000	15,500	구현 계획 생성
T11	Agent() 호출	200	15,700	orchestrator 시작

핵심 문제: brainstorming 스킬 내용(2,000t)은 T2 로드 후 T3~T11까지 죽은 토큰으로 잔존. writing-plans도 동일(T7 이후). 총 ~4,000t의 스킬 내용이 불필요하게 모든 후속 턴에서 반복 전송.

서브에이전트 컨텍스트

team-orchestrator는 독립 서브에이전트로 실행되므로 **깨끗한 컨텍스트(~3,500t)**에서 시작. 메인 스레드의 누적 토큰과 무관.

3. 핸드오프 메커니즘 분석

단계	입력	출력	핸드오프 방식
brainstorming	사용자 요구사항	`docs/plans/설계문서.md`	파일
writing-plans	설계문서.md	`docs/plans/구현계획.md`	파일
team-orchestrator	구현계획.md	코드, 커밋	파일

모든 핸드오프가 파일 기반 → 대화 컨텍스트 자체는 핸드오프에 불필요

4. 세 가지 접근법 비교

방안 A: 전부 orchestrator에 통합

/team → Agent("team-orchestrator")  (1회 호출)
         ├─ Phase 0: brainstorming (내부)
         ├─ Phase 1: plan 수립 (내부)
         └─ Phase 2-5: 구현

리스크	심각도	상세
사용자 인터랙션 품질 저하	HIGH	서브에이전트의 AskUserQuestion은 메인 스레드보다 제한적
승인 게이트 우회 위험	HIGH	서브에이전트가 자체 승인 후 구현 돌입 가능
에이전트 프롬프트 매 턴 비용	MEDIUM	5,000t 프롬프트가 수십~수백 턴에서 반복
디버깅 불투명성	MEDIUM	전환점이 서브에이전트 트랜스크립트에 묻힘
실패 시 전체 재시작	HIGH	brainstorming 방향 수정 → orchestrator 전체 재시작

방안 B: 현재 구조 유지 (3단계 순차 호출)

리스크	심각도	상세
죽은 토큰 누적	MEDIUM	~4,000t 스킬 내용이 후속 턴에 잔존
Skill 호출 오버헤드	LOW	2회 추가 Skill 호출 = ~100t
메인 스레드 컨텍스트 점유	MEDIUM	brainstorming 대화(~8K)가 후속 작업 공간 제한
순차 실행 지연	LOW	실제 체감은 Skill 로드 시간(~2초) 정도

방안 C: 절충안 (brainstorming 인라인 + plan은 orchestrator)

/team (메인 스레드에서 brainstorming 직접 실행)
  ├─ 사용자와 대화 (설계 확정)
  ├─ 설계문서 파일 저장
  └─ Agent("team-orchestrator")  ← plan + 구현
       ├─ Phase 0: 설계문서 읽기
       ├─ Phase 1: plan 수립 (writing-plans 로직 내장)
       └─ Phase 2-5: 구현

리스크	심각도	상세
brainstorming 스킬과 내용 중복	LOW	핵심 체크리스트만 인라인 (~500t)
orchestrator 프롬프트 증가	LOW	writing-plans 핵심만 추가 = ~500-800t
plan 승인 게이트 약화	MEDIUM	orchestrator 내부에서 만들면 사용자 승인 없이 진행 가능

5. 컨텍스트 윈도우 비교

방안 B (현재):
메인   ████████████████░░░░░░░░░░░░░░  ~15.7K (orchestrator 시작 전)
orch   ████░░░░░░░░░░░░░░░░░░░░░░░░░░  ~3.5K  (깨끗한 시작)

방안 C (절충안):
메인   ██████████░░░░░░░░░░░░░░░░░░░░  ~9.7K  (skill 1개 + 대화)
orch   █████░░░░░░░░░░░░░░░░░░░░░░░░░  ~4.0K  (plan 로직 포함)

방안 A (전통합):
메인   █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  ~0.3K  (거의 비어있음)
orch   ██████░░░░░░░░░░░░░░░░░░░░░░░░  ~5.0K  (모든 로직 포함)

6. 숨겨진 구조적 문제

6-1. using-superpowers 메타스킬 충돌

using-superpowers 규칙은 “1%라도 관련 스킬이 있으면 반드시 호출”을 강제. /team이 brainstorming을 Skill()로 호출하면, using-superpowers도 별도로 brainstorming을 호출하려 해서 중복 호출 위험 발생.

방안 C 해결: brainstorming이 인라인되면 중복 호출 필요성이 명확히 제거됨.

6-2. 서브에이전트 중첩 제한

메인 → team-orchestrator (서브에이전트)
         → frontend-dev (서브-서브에이전트)

orchestrator 내부에서 brainstorming까지 하면 에이전트 중첩 깊이가 증가할 수 있음.

6-3. 실패 복구 비용 차이

시나리오	현재 (B)	전통합 (A)	절충안 (C)
brainstorming 방향 전환	스킬 재호출	orchestrator 전체 재시작	대화 이어서 수정
plan 수정 필요	스킬 재호출	서브에이전트 내부 수정	서브에이전트 내부 수정
구현 단계 실패	orchestrator 내부 처리	orchestrator 내부 처리	orchestrator 내부 처리

7. 최종 권장 설계

권장: 방안 C (절충안)

┌──────────────────────────────────────────────┐
│  /team SKILL.md (~1,200t)                    │
│                                              │
│  ■ brainstorming 체크리스트 (인라인)          │
│    1. 요구사항 탐색 질문                      │
│    2. 접근법 제시 → 사용자 선택               │
│    3. 설계문서 작성 → docs/plans/에 저장       │
│    4. 사용자 승인 (하드 게이트)                │
│                                              │
│  ■ 승인 후 → Agent("team-orchestrator")      │
│    plan 경로를 프롬프트에 포함                 │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  team-orchestrator.md (~3,800t)              │
│                                              │
│  ■ Phase 0: 설계문서 읽기 + 구현계획 수립     │
│    (writing-plans 핵심 로직 내장)             │
│  ■ Phase 1-5: 기존과 동일                    │
└──────────────────────────────────────────────┘

효과 요약

측면	현재 (B)	권장안 (C)	개선폭
Skill 호출 횟수	2회	0회	-2회
메인 스레드 죽은 토큰	~4,000t	0t	-4,000t
사용자 인터랙션	자연스러움	자연스러움	유지
설계 승인 게이트	있음	있음	유지
brainstorming 재사용	독립 스킬	독립 스킬 유지	유지
실패 복구 비용	스킬 재호출	대화 이어서 수정	개선
orchestrator 프롬프트	3,000t	3,800t	+800t

순 절감: ~3,200t + Skill 호출 지연 2회 제거

8. 일반 원칙: 스킬 호출 패턴 가이드

중첩 호출이 적합한 경우

상위 스킬이 조건부 분기로 하위 스킬을 선택할 때
하위 스킬 실행 결과에 따라 다른 스킬을 동적으로 선택할 때

개별 호출 / 인라인이 적합한 경우

항상 같은 순서로 같은 스킬을 호출할 때 → 인라인
각 스킬이 독립적 작업 단위일 때 → 개별 호출
사용자 인터랙션이 필요한 스킬 → 메인 스레드 인라인

토큰 절약 체크리스트

Skill() 호출로 로드된 내용은 대화가 끝날 때까지 컨텍스트에 잔존
자주 함께 쓰는 스킬은 하나로 합치기 (핵심만 추출)
파일 기반 핸드오프가 가능하면 대화 컨텍스트 공유 불필요
서브에이전트는 독립 컨텍스트이므로 메인 스레드 부담 없음
context: fork 활용 시 메인 컨텍스트 오염 방지 가능

Source Notes

이 문서는 KeystoneHub /team 오케스트레이터 스킬의 구조 분석을 공개용으로 정리한 것입니다. 토큰 수치는 분석 당시 측정 기준 추정값입니다. Provenance: keystone-native.