[opencode 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기] 1/12화: opencode 에이전트 아키텍처 완전 해부 — 2026 Primary·Subagent 5계층 구조

2026년 07월 28일 9 Min Read

시즌 2가 시작됩니다 — 이번엔 에이전트를 직접 빚습니다

이 글은 「opencode 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기」 1일차입니다.

시즌 1에서 우리는 opencode의 설치부터 멀티모달 활용, MCP 연동까지 12일에 걸쳐 ‘사용법’을 익혔습니다. 터미널에서 AI 코딩 에이전트를 자유자재로 다루는 수준까지 왔죠. 하지만 매번 같은 질문이 돌아왔습니다. “이 에이전트가 우리 팀 컨벤션을 알면 좋겠는데”, “코드 리뷰할 때 보안 체크리스트를 자동으로 돌리고 싶은데”, “금융 규제 문서를 참조해서 답변하게 만들 수 없나”. 시즌 2는 바로 그 답입니다.

시즌 1이 ‘완성된 에이전트를 타는 법’이었다면, 시즌 2는 ‘에이전트를 직접 설계하고 조립하는 법’입니다. 12일 뒤에는 여러분만의 도메인 특화 opencode 에이전트 팀을 구축하게 됩니다. 오늘은 그 첫걸음으로, 에이전트 아키텍처의 뼈대를 해부합니다.

시즌 2 로드맵 한눈에 보기

12일간의 여정을 다섯 단계로 나눠 진행합니다.

Phase A — 에이전트 기초 (1~3일차): 아키텍처 이해 → 에이전트 정의 방식 → 시스템 프롬프트 설계
Phase B — 제어·라우팅 (4~5일차): 권한 매트릭스 설계 → 모델 라우팅 전략
Phase C — 오케스트레이션 (6~7일차): 서브에이전트 위임 패턴 → 컨텍스트 엔지니어링
Phase D — 확장 개발 (8~10일차): 슬래시 커맨드 → 플러그인 개발 → MCP 통합
Phase E — 시스템 통합 (11~12일차): 멀티 에이전트 시스템 → 도메인 특화 종합 프로젝트

매일 동작하는 설정 파일이나 코드를 하나 이상 직접 제공합니다. 12일째에는 처음부터 끝까지 통합된 에이전트 팀을 완성하는 핸즈온을 진행할 예정이니, 하루도 빠짐없이 따라오시길 권합니다.

오늘의 핵심 3가지

Primary 에이전트와 Subagent는 역할이 근본적으로 다르다 — Primary는 대화를 이끌고, Subagent는 위임받은 작업을 수행한다
opencode는 5개의 내장 에이전트로 구성된다 — Primary 2개(Build, Plan) + Subagent 3개(General, Explore, Scout)
이 계층 구조를 이해해야 커스텀 에이전트를 올바르게 설계할 수 있다 — 어떤 역할을 Primary에 두고 어떤 역할을 Subagent에 둘지가 시스템 전체 품질을 결정한다

opencode 에이전트 Primary Subagent 아키텍처 다이어그램

opencode 에이전트란 정확히 무엇인가

먼저 용어부터 정리합니다. opencode에서 ‘에이전트(Agent)’란, 특정 시스템 프롬프트·권한·모델 설정을 하나로 묶은 실행 단위입니다. 같은 LLM을 사용하더라도 시스템 프롬프트가 다르면 완전히 다른 에이전트가 됩니다. 에이전트는 단순한 프롬프트 템플릿이 아니라, 어떤 도구(tool)를 쓸 수 있는지, 어떤 파일에 접근할 수 있는지, 어떤 모델로 추론하는지까지 포함하는 완결된 실행 프로파일입니다.

이 개념을 잡아야 시즌 2 전체가 매끄럽게 이어집니다. opencode 공식 에이전트 문서에서도 에이전트를 “a set of instructions, permissions, and model configurations”으로 정의하고 있습니다.

Primary 에이전트 — 대화의 주인공

Primary 에이전트는 사용자와 직접 대화하는 에이전트입니다. 터미널에서 opencode를 실행하고 프롬프트를 입력하면, 그 입력을 받아 처리하는 것이 바로 Primary 에이전트입니다. opencode에는 두 개의 Primary 에이전트가 내장되어 있습니다.

Build — opencode의 기본 에이전트입니다. 코드를 읽고, 수정하고, 파일을 만들고, 테스트를 돌리는 등 실제 ‘구현’ 작업을 수행합니다. 터미널을 열고 opencode를 치면 기본으로 Build 에이전트가 응답합니다.

Plan — 구현 전에 설계를 잡아주는 에이전트입니다. 코드를 직접 수정하지 않고, 현재 코드베이스를 분석해서 작업 계획을 세워줍니다. Build가 “만드는 사람”이라면, Plan은 “설계하는 사람”입니다. /plan 명령이나 에이전트 전환으로 활성화됩니다.

핵심은 이겁니다: Primary 에이전트는 한 번에 하나만 활성화됩니다. Build와 Plan이 동시에 대화에 참여하지 않습니다. 사용자가 명시적으로 전환하거나, 특정 명령을 통해 바꿔야 합니다. 이건 마치 한 명의 팀 리더가 프로젝트를 이끄는 것과 같습니다 — 리더가 둘이면 혼란이 오니까요.

Subagent — 위임받는 전문가들

Subagent는 Primary 에이전트가 특정 작업을 위임할 때 호출되는 에이전트입니다. 사용자와 직접 대화하지 않고, Primary 에이전트의 요청을 받아 결과를 돌려줍니다. 세 개의 내장 Subagent가 있습니다.

General — 범용 서브에이전트입니다. Primary가 “이 부분은 네가 처리해”라고 넘기면 General이 받아서 수행합니다. 별도의 컨텍스트에서 독립적으로 작업하므로, Primary의 컨텍스트 윈도우를 소비하지 않는다는 장점이 있습니다.

Explore — 코드베이스 탐색 전문가입니다. 파일 구조를 파악하고, 특정 함수나 클래스를 찾고, 코드 간의 관계를 추적합니다. “이 프로젝트에서 인증 관련 코드가 어디 있어?”라는 질문에 가장 적합한 에이전트입니다. 읽기 전용에 가깝고, 코드를 수정하지 않습니다.

Scout — 가장 가벼운 서브에이전트입니다. 빠른 검색, 간단한 정보 조회에 특화되어 있습니다. Explore보다 더 좁은 범위의 작업을 빠르게 처리합니다.

Primary와 Subagent의 5가지 핵심 차이

단순히 “하나는 대화하고 하나는 위임받는다”를 넘어, 아키텍처 관점에서 다섯 가지 구조적 차이를 이해해야 합니다. 이 차이가 나중에 커스텀 에이전트를 설계할 때 “이 역할은 Primary에 넣을까, Subagent로 뺄까”를 결정하는 기준이 됩니다.

1. 컨텍스트 윈도우 소유권

Primary 에이전트는 사용자와의 전체 대화 히스토리를 가지고 있습니다. 세션이 시작된 이후의 모든 메시지가 Primary의 컨텍스트에 쌓입니다. 반면 Subagent는 위임받은 그 작업에 필요한 정보만 전달받아 별도의 컨텍스트에서 실행됩니다.

이게 왜 중요한가요? 컨텍스트 윈도우는 유한합니다. 대화가 길어질수록 Primary의 컨텍스트가 차오르고, 초기 대화 내용이 밀려나기 시작합니다. Subagent에 작업을 위임하면 Primary의 컨텍스트를 절약할 수 있습니다. 이 원리를 이해하면, “긴 파일을 분석하는 작업”은 Subagent에 맡기고 Primary는 결과 요약만 받는 식으로 설계할 수 있습니다.

2. 도구(Tool) 접근 범위

Primary 에이전트는 opencode가 제공하는 모든 도구에 접근할 수 있습니다 — 파일 읽기, 쓰기, 터미널 실행, 웹 검색 등. Subagent는 자신에게 허용된 도구만 사용할 수 있습니다. 예를 들어 Explore 서브에이전트는 파일 읽기와 검색은 되지만, 파일 쓰기나 터미널 명령 실행은 제한됩니다.

이 제한은 의도적인 설계입니다. “코드를 분석해줘”라고 시킨 에이전트가 갑자기 파일을 수정하면 안 되니까요. 4일차에서 권한 매트릭스를 다룰 때 이 부분을 훨씬 깊이 파고들 예정입니다.

3. 생명주기(Lifecycle)

Primary 에이전트는 세션이 살아 있는 동안 계속 존재합니다. 사용자가 터미널을 닫거나 세션을 종료할 때까지 유지됩니다. Subagent는 위임받은 작업이 끝나면 종료됩니다. 작업 결과를 Primary에 반환하고 사라집니다.

이 차이 때문에 Subagent는 ‘상태(state)’를 유지하지 않습니다. 같은 Subagent를 두 번 호출해도, 두 번째 호출은 첫 번째의 결과를 기억하지 못합니다. 상태가 필요하면 Primary가 관리하거나, 파일 시스템에 기록해야 합니다. 이건 11일차 ‘공유 영속 메모리’ 주제에서 해결 방법을 다룹니다.

4. 위임 방향

위임은 항상 위에서 아래로 흐릅니다. Primary가 Subagent를 호출하지, Subagent가 Primary를 호출하지 않습니다. Subagent끼리 서로를 호출하는 것도 기본적으로 일어나지 않습니다. 이건 트리 구조입니다 — Primary가 루트 노드이고, Subagent들이 자식 노드입니다.

물론 커스텀 에이전트를 설계할 때 Subagent가 다른 Subagent를 호출하게 만들 수도 있습니다. 하지만 기본 아키텍처는 단방향 위임이고, 이 원칙을 지키는 것이 시스템을 예측 가능하게 유지하는 핵심입니다.

5. 모델 독립성

Primary와 Subagent는 서로 다른 LLM 모델을 사용할 수 있습니다. 예를 들어 Primary(Build)는 가장 강력한 모델을 쓰고, Scout 서브에이전트는 빠르고 저렴한 모델을 쓰는 식입니다. 이 구조 덕분에 비용과 성능을 세밀하게 조절할 수 있습니다. 5일차 모델 라우팅에서 이 전략을 깊이 다룹니다.

opencode 에이전트 계층 다이어그램

지금까지 설명한 구조를 하나의 다이어그램으로 정리합니다. 이 그림을 머릿속에 새겨두세요 — 시즌 2 전체를 관통하는 기본 뼈대입니다.


┌─────────────────────────────────────────────────┐
│                   사용자 (터미널)                  │
│              프롬프트 입력 / 결과 수신              │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────┐
│            ★ Primary 에이전트 계층 ★              │
│                                                 │
│  ┌──────────────┐      ┌──────────────┐         │
│  │    Build     │ ◄──► │     Plan     │         │
│  │  (기본 구현)  │      │  (설계·계획)  │         │
│  │  기본 활성화   │      │  /plan 전환   │         │
│  └──────┬───────┘      └──────────────┘         │
│         │  한 번에 하나만 활성                      │
└─────────┼───────────────────────────────────────┘
          │ 위임 (단방향)
          ▼
┌─────────────────────────────────────────────────┐
│            ◆ Subagent 계층 ◆                     │
│                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │ General  │  │ Explore  │  │  Scout   │      │
│  │ 범용 작업  │  │ 코드 탐색  │  │ 빠른 검색 │      │
│  │ 독립 실행  │  │ 읽기 전용  │  │ 경량 조회  │      │
│  └──────────┘  └──────────┘  └──────────┘      │
│  • 별도 컨텍스트  • 작업 후 종료  • 상태 비유지     │
└─────────────────────────────────────────────────┘

이 구조에서 가장 중요한 포인트 세 가지를 다시 강조합니다.

Primary는 게이트키퍼 — 모든 사용자 요청은 Primary를 거칩니다. 직접 처리하거나 Subagent에 위임합니다.
Subagent는 스페셜리스트 — 각자 전문 영역이 있고, 호출되면 그 일만 하고 결과를 반환합니다.
위임은 단방향 — Primary → Subagent 방향만 존재합니다. 역방향이나 횡방향 호출은 기본적으로 없습니다.

실전: 에이전트 구조를 직접 확인하기

이론만으로는 감이 잡히지 않을 수 있습니다. 직접 opencode를 열고 에이전트 구조를 확인해봅시다.

현재 활성 에이전트 확인

opencode 세션에서 /agents 명령을 입력하면 현재 사용 가능한 에이전트 목록이 표시됩니다. 기본 설치 상태에서는 Build, Plan, General, Explore, Scout 다섯 개가 나옵니다.


# opencode 세션 내에서
/agents

현재 활성화된 에이전트가 어떤 것인지, 각 에이전트가 어떤 설명(description)을 가지고 있는지 확인할 수 있습니다. 이 description이 바로 Primary가 “어떤 Subagent에 위임할까”를 결정하는 기준이 됩니다.

에이전트 전환 실험

Build에서 Plan으로 전환해보겠습니다.


# Build 에이전트 상태에서
/plan 이 프로젝트의 인증 시스템을 개선하려면 어떤 순서로 작업해야 할까?

Plan 에이전트는 코드를 수정하지 않고 분석과 계획만 제시합니다. 작업 계획이 마음에 들면 다시 Build로 돌아와 실행하면 됩니다. 이 워크플로우가 Primary 두 개를 번갈아 쓰는 기본 패턴입니다.

Subagent 위임 관찰

Build 에이전트에게 큰 코드베이스를 분석하는 작업을 맡기면, Build가 스스로 Explore 서브에이전트를 호출하는 것을 관찰할 수 있습니다.


# Build 에이전트 상태에서
이 프로젝트에서 사용되지 않는 import를 모두 찾아줘

터미널 출력을 보면 “Exploring codebase…”나 별도의 에이전트 호출 표시가 나타납니다. Build가 직접 파일을 하나씩 열어보는 대신, Explore에 탐색을 위임한 것입니다. 이 자동 위임이 바로 description 기반 자동 위임이며, 6일차에서 심도 있게 다룹니다.

opencode 에이전트의 해부학 — 에이전트를 구성하는 4요소

내장 에이전트든 커스텀 에이전트든, 모든 opencode 에이전트는 네 가지 요소로 구성됩니다. 이 구조를 알면 내일부터 시작하는 커스텀 에이전트 정의가 한결 수월해집니다.

요소 1: 시스템 프롬프트 (System Prompt)

에이전트의 성격과 행동 규칙을 정의하는 텍스트입니다. “너는 코드 리뷰어야. 항상 보안 취약점을 먼저 확인해”와 같은 지시를 담습니다. 가장 중요한 요소이며, 3일차 전체를 이 주제에 할애합니다.

요소 2: 권한 (Permissions)

에이전트가 사용할 수 있는 도구를 정의합니다. 파일 읽기, 쓰기, 터미널 실행, 웹 검색 등의 도구를 allow, ask, deny 세 단계로 제어합니다. 4일차에서 권한 매트릭스를 설계합니다.

요소 3: 모델 (Model)

어떤 LLM으로 추론할지 지정합니다. provider/model-id 형식으로, 예를 들어 anthropic/claude-sonnet-4-6처럼 씁니다. 에이전트마다 다른 모델을 쓸 수 있어서, 비용과 성능을 최적화할 수 있습니다. 5일차 주제입니다.

요소 4: 설명 (Description)

다른 에이전트(특히 Primary)가 이 에이전트를 언제 호출할지 판단하는 기준입니다. “코드베이스를 탐색하고 파일 구조를 파악하는 전문가”와 같은 설명을 보고, Primary가 “이 작업은 Explore에 맡기자”라고 결정합니다. 설명이 모호하면 자동 위임이 제대로 작동하지 않으므로, 생각보다 중요한 요소입니다.

직접 만져보는 첫 번째 설정 — 기본 에이전트 확인과 설정 구조

오늘의 핸즈온 설정입니다. 프로젝트 루트에 opencode.json 파일을 만들고 아래 내용을 넣어보세요. 아직 커스텀 에이전트를 추가하는 것은 아니고, 기본 에이전트 구조를 명시적으로 확인하는 설정입니다.

{
  "$schema": "https://opencode.ai/schema.json",

  "default_agent": "build",

  "agent": {
    "build": {
      "description": "Primary agent for code implementation and modification",
      "model": "anthropic/claude-sonnet-4-6"
    },
    "plan": {
      "description": "Primary agent for analysis and planning without code changes",
      "model": "anthropic/claude-sonnet-4-6"
    }
  }
}

이 설정에서 주목할 포인트 세 가지입니다.

첫째, default_agent 키. opencode를 실행했을 때 어떤 Primary 에이전트가 기본으로 활성화될지 지정합니다. "build"가 기본값이고, "plan"으로 바꾸면 항상 분석·계획 모드로 시작합니다. 팀에서 코드 리뷰 위주로 쓴다면 Plan을 기본으로 두는 것도 전략입니다.

둘째, agent 키 구조. 에이전트 이름을 키로, 설정 객체를 값으로 가집니다. 여기서 description과 model을 지정할 수 있습니다. 2일차에서 이 구조를 확장해 커스텀 에이전트를 추가하고, .opencode/agents/*.md 파일 방식과 비교합니다.

셋째, 모델 지정 형식. "provider/model-id" 형식을 씁니다. provider는 anthropic, openai, google 등이 올 수 있고, 그 뒤에 슬래시와 모델 ID가 옵니다. 5일차에서 에이전트별 모델을 다르게 지정하는 라우팅 전략을 깊이 다룹니다.

설정 파일의 위치와 우선순위

opencode 에이전트 설정은 두 곳에 둘 수 있습니다.

글로벌 설정: ~/.config/opencode/ (macOS/Linux) 또는 %APPDATA%/opencode/ (Windows). 모든 프로젝트에 공통으로 적용됩니다.
프로젝트 로컬 설정: 프로젝트 루트의 opencode.json 또는 .opencode/ 디렉토리. 해당 프로젝트에서만 적용됩니다.

우선순위는 프로젝트 로컬 > 글로벌입니다. 프로젝트에 opencode.json이 있으면 글로벌 설정보다 우선합니다. 2일차에서 이 폴백 순서를 표로 정리하고, 실무에서 글로벌과 로컬을 어떻게 나눠 쓰는지 다룹니다.

왜 이 구조가 중요한가 — 실무 관점

에이전트를 하나만 쓴다면 이 아키텍처를 몰라도 됩니다. 하지만 실무에서는 하나로 부족합니다.

시나리오: 코드 리뷰 자동화

팀에서 PR이 올라오면 다음 네 가지를 체크하고 싶다고 합시다.

코딩 컨벤션 준수 여부
보안 취약점 존재 여부
테스트 커버리지 확인
성능 영향도 분석

이걸 하나의 에이전트에 전부 맡기면 어떻게 될까요? 시스템 프롬프트가 너무 길어지고, 컨텍스트 윈도우가 빠르게 차며, 어떤 체크를 빼먹었는지 추적하기 어렵습니다.

Primary/Subagent 구조를 쓰면 이렇게 됩니다.


Primary (Build 또는 커스텀 Orchestrator)
  ├── Subagent: ConventionChecker  → 컨벤션만 확인
  ├── Subagent: SecurityAuditor   → 보안만 확인
  ├── Subagent: TestAnalyzer      → 테스트만 확인
  └── Subagent: PerfReviewer      → 성능만 확인

각 Subagent는 자기 전문 분야의 시스템 프롬프트만 가지고, 해당 체크에 최적화된 모델을 사용합니다. Primary는 네 Subagent의 결과를 종합해서 최종 리뷰 의견을 만듭니다. 이것이 6일차에서 구축할 멀티 에이전트 오케스트레이션의 기본 패턴입니다.

시나리오: 비용 최적화

모든 작업에 가장 비싸고 강력한 모델을 쓸 필요는 없습니다. Primary가 복잡한 의사결정을 하므로 고성능 모델을 쓰고, Scout 서브에이전트는 간단한 검색만 하므로 저렴한 모델을 쓰는 식입니다. BYOK(Bring Your Own Key) 환경에서 이 전략은 월 비용을 상당히 줄여줍니다.

자동 위임 vs 수동 호출 — 미리보기

Subagent를 호출하는 방식은 두 가지입니다. 6일차에서 본격적으로 다루지만, 오늘 아키텍처를 이해하는 데 필요한 만큼 미리 봅니다.

자동 위임 (Description 기반)

Primary 에이전트가 작업을 수행하다가, 특정 Subagent의 description에 부합하는 작업이 필요하다고 판단하면 자동으로 해당 Subagent를 호출합니다. 사용자가 명시적으로 지시하지 않아도 됩니다.

예를 들어, “이 프로젝트의 디렉토리 구조를 알려줘”라고 하면 Build가 직접 탐색하는 대신 Explore에 위임합니다. Explore의 description이 “코드베이스 탐색 전문가”이므로, Build가 “이건 Explore 일이구나”라고 판단하는 것입니다.

수동 호출 (@멘션)

사용자가 직접 @에이전트명으로 특정 Subagent를 호출할 수도 있습니다. 자동 위임이 원하는 대로 작동하지 않거나, 특정 에이전트를 의도적으로 사용하고 싶을 때 씁니다.


@explore src/auth 디렉토리의 모든 미들웨어 파일을 분석해줘

자동 위임의 품질은 전적으로 description의 명확함에 달려 있습니다. 이것이 커스텀 에이전트를 만들 때 description을 정밀하게 작성해야 하는 이유입니다.

커스텀 에이전트 정의 방법 — 2일차 예고

오늘은 내장 에이전트의 구조를 이해했습니다. 내일부터는 직접 만듭니다. opencode에서 커스텀 에이전트를 정의하는 방법은 두 가지입니다.

방법 1: opencode.json의 agent 키에 인라인으로 정의
방법 2: .opencode/agents/ 디렉토리에 마크다운 파일(YAML frontmatter + 시스템 프롬프트 본문)로 정의

각 방법의 장단점, 언제 어떤 것을 쓸지, 글로벌 설정과 프로젝트 로컬 설정의 합산 규칙까지 2일차에서 비교표와 함께 다룹니다.

Gotcha 미니 코너: “왜 내 Subagent가 호출 안 되지?”

커스텀 Subagent를 만들고 나서 가장 흔히 겪는 문제가 “Primary가 내 Subagent를 무시한다”입니다. 열에 아홉은 description이 너무 모호하거나 다른 에이전트와 겹치기 때문입니다.

예를 들어 커스텀 Subagent의 description을 “코드 관련 작업을 도와주는 에이전트”라고 썼다면, Build(Primary) 입장에서는 자기 자신도 코드 관련 작업을 하므로 위임할 이유가 없습니다. description은 “SQL 쿼리 성능을 분석하고 인덱스 전략을 제안하는 전문가”처럼 구체적이고 다른 에이전트와 겹치지 않게 작성해야 자동 위임이 제대로 작동합니다.

기억하세요: description은 사람이 읽는 설명이 아니라, Primary 에이전트가 위임 판단을 내리는 입력값입니다.

오늘 만든 것 → 내일 추가할 것

오늘은 opencode 에이전트의 5계층 아키텍처(사용자 → Primary 2종 → Subagent 3종)를 이해하고, opencode.json의 기본 구조를 확인했습니다. 내일은 이 뼈대 위에 살을 붙입니다 — opencode.json 인라인 방식과 .opencode/agents/*.md 파일 방식으로 커스텀 에이전트를 직접 정의하고, 두 방식의 차이와 실무 선택 기준을 비교합니다.

내일 예고: 2일차 — 커스텀 에이전트 정의 2가지 방식 완전 비교 (opencode.json vs .opencode/agents/*.md)

📚 시리즈: opencode 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기 (총 12화 중 1화)

Tags:

AI 코딩 에이전트 opencode 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기-1화 opencode 시즌2 opencode 에이전트 Primary Subagent 멀티 에이전트 아키텍처 연재:opencode 시즌 2 심화 — 나만의 도메인 특화 에이전트 만들기