⚡ 03. 활용

opencode-03-활용-diagram.svg

OpenCode의 에이전트 시스템은 특정 작업과 워크플로우에 최적화된 전문 AI 어시스턴트를 생성하고 관리할 수 있습니다. 에이전트는 사용자 지정 프롬프트, 모델, 도구 접근 권한을 가질 수 있습니다.

에이전트 타입

Primary Agents (주요 에이전트)

사용자가 직접 상호작용하는 메인 어시스턴트입니다.

Tab 키 또는 설정된 단축키로 전환
모든 구성된 도구에 접근 가능
기본 에이전트: Build, Plan

Subagents (하위 에이전트)

특정 작업을 위해 주요 에이전트가 호출하는 전문화된 어시스턴트입니다.

메시지에서 @ 언급으로 수동 호출
주요 에이전트가 자동으로 호출
자식 세션 생성

빌트인 에이전트

Build (기본)

mode: primary
tools: all enabled

전체 개발 작업용
모든 도구 활성화
파일 시스템 및 시스템 명령 접근 가능

Plan

mode: primary
permissions:
  file edits: ask
  bash: ask

제한된 에이전트 (계획 및 분석용)
권한 시스템으로 의도하지 않은 변경 방지
기본적으로 모든 작업에 승인 요구

General

mode: subagent

복잡한 질문 연구
코드 검색
다단계 작업 실행
키워드나 파일 검색 시 첫 시도에서 정확한 일치를 찾을 자신이 없을 때

Explore

mode: subagent

코드베이스 탐색에 특화된 빠른 에이전트
패턴으로 파일 찾기
코드에서 키워드 검색
코드베이스 관련 질문 답변

에이전트 사용법

Primary Agents 전환

<Tab>  # 빌드/플랜 에이전트 순환

Subagents 호출

@general 복잡한 검색 도와줘
@explore 이 함수 찾아봐

세션 간 탐색

<Leader>+Right    # 부모 → 자식1 → 자식2 → ... → 부모 순환
<Leader>+Left     # 부모 ← 자식1 ← 자식2 ← ... ← 부모 역순환

에이전트 설정

JSON 설정 (opencode.json)

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown 설정

에이전트 파일 위치:

전역: ~/.config/opencode/agent/
프로젝트별: .opencode/agent/

예시: 리뷰 에이전트

~/.config/opencode/agent/review.md:

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---
 
You are in code review mode. Focus on:
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations
 
Provide constructive feedback without making direct changes.

에이전트 옵션

description (필수)

에이전트의 역할과 사용 시점에 대한 간단한 설명

{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

temperature

LLM 응답의 무작위성과 창의성 제어

0.0-0.2: 매우 집중적이고 결정론적 (코드 분석, 계획용)
0.3-0.5: 균형 잡힌 응답 (일반 개발 작업용)
0.6-1.0: 더 창의적이고 다양한 응답 (브레인스토밍, 탐색용)

{
  "agent": {
    "analyze": { "temperature": 0.1 },
    "build": { "temperature": 0.3 },
    "brainstorm": { "temperature": 0.7 }
  }
}

maxSteps

에이전트가 수행할 수 있는 최대 반복 횟수 제한

{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "maxSteps": 5
    }
  }
}

disable

에이전트 비활성화

{
  "agent": {
    "review": { "disable": true }
  }
}

prompt

에이전트 전용 시스템 프롬프트 파일 경로

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

model

에이전트 전용 모델 오버라이드

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

tools

에이전트가 사용할 수 있는 도구 제어

{
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

permissions

에이전트가 수행할 수 있는 작업 관리

"ask": 승인 전 실행
"allow": 승인 없이 모든 작업 허용
"deny": 도구 비활성화

{
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask"
        }
      }
    }
  }
}

mode

에이전트 모드 제어: primary, subagent, all

{
  "agent": {
    "review": { "mode": "subagent" }
  }
}

hidden

@ 자동완성 메뉴에서 하위 에이전트 숨기기

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

task permissions

Task 도구를 통해 호출할 수 있는 하위 에이전트 제어

{
  "agent": {
    "orchestrator": {
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

에이전트 생성

opencode agent create

이 대화형 명령은:

저장 위치 선택 (전역/프로젝트별)
에이전트 설명 요청
시스템 프롬프트 및 식별자 생성
사용할 도구 선택
에이전트 설정으로 마크다운 파일 생성

사용 사례

Build Agent

모든 도구 활성화된 전체 개발 작업
실제 코드 구현

Plan Agent

변경 사항 없는 분석 및 계획
코드 리뷰 및 제안

Review Agent

읽기 전용 접근 + 문서화 도구
코드 품질 검토

Debug Agent

Bash 및 읽기 도구 활성화
조사 및 디버깅 중심

Docs Agent

파일 작업 + 시스템 명령 제한
문서 작성 전용

예시 에이전트

Documentation Agent

~/.config/opencode/agent/docs-writer.md:

---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---
 
You are a technical writer. Create clear, comprehensive documentation.
Focus on:
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Security Auditor

~/.config/opencode/agent/security-auditor.md:

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---
 
You are a security expert. Focus on identifying potential security issues.
Look for:
- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues

에이전트 오케스트레이션 패턴

1. Orchestrator Pattern

메인 에이전트가 여러 하위 에이전트를 조율하여 복잡한 작업 수행

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "researcher": "allow",
          "implementer": "allow",
          "tester": "allow"
        }
      }
    }
  }
}

2. Sequential Pattern

순차적으로 여러 에이전트를 통해 작업 수행

@explore로 관련 파일 찾기
@plan으로 계획 수립
build로 구현
@review로 리뷰

3. Parallel Pattern

여러 에이전트를 동시에 사용하여 다른 관점에서 작업 수행

@code-reviewer로 코드 품질 검토
@security-auditor로 보안 검토
@docs-writer로 문서화

일하는 ai

탐색기