Ch3. 에이전트 설계
OpenCode 빌트인·커스텀 에이전트의 역할을 분리하고 서브에이전트 권한과 책임 범위를 설계하는 운영 기준입니다.
핵심 요약
- 프라이머리 에이전트(Build·Plan)는
Tab으로 순환하고, 서브에이전트(General·Explore)는@general,@explore로 호출합니다. - 커스텀 에이전트는
opencode.json또는.opencode/agents/*.md로 정의하며, 글로벌은~/.config/opencode/agents/에 둡니다. - 읽기 전용 리뷰어는
write: false,edit: false,bash: deny로 구성해 컨텍스트 오염과 사고 범위를 줄입니다. - 에이전트별 모델을 분리해 탐색은 저비용, 생성은 고성능 모델로 비용을 제어합니다.
- v1.2.16+의 Skills는
.opencode/skills/,.claude/skills/,.agents/skills/에서 알아서 검색되는 재사용 지시문입니다.
OpenCode는 빌트인 에이전트와 커스텀 에이전트를 지원합니다. 시니어 개발자라면 에이전트 역할을 나눠 사고 범위부터 좁혀야 합니다.
빌트인 에이전트
프라이머리 에이전트
Tab 키로 전환합니다.
| 에이전트 | 역할 | 도구 접근 |
|---|---|---|
| Build (기본) | 코드 변경 중심의 일반 개발 | 전체 도구 접근 |
| Plan | 분석/계획 (읽기 전용) | 쓰기/실행은 ask 권한 |
서브에이전트
@에이전트명으로 호출합니다.
| 에이전트 | 역할 | 특징 |
|---|---|---|
| General | 멀티스텝 리서치, 병렬 작업 | todo를 제외한 전체 도구 |
| Explore | 코드베이스 탐색 | 읽기 전용, 패턴 매칭 최적화 |
시스템 에이전트 (숨김)
| 에이전트 | 역할 |
|---|---|
| Compaction | 긴 컨텍스트 자동 요약 |
| Title | 세션 제목 생성 |
| Summary | 세션 요약 생성 |
에이전트 전환 방법
| 동작 | 키/명령 |
|---|---|
| 프라이머리 에이전트 순환 | Tab |
| 서브에이전트 호출 | @general, @explore |
| 에이전트 목록 | <Leader>+a |
| 부모/자식 세션 이동 | <Leader>+Right/Left |
커스텀 에이전트 구성
JSON 방식 (opencode.json)
{
"agent": {
"review": {
"description": "코드 품질 리뷰",
"mode": "subagent",
"model": "anthropic/claude-sonnet-4-5",
"prompt": "코드 리뷰어로서 품질과 보안에 집중합니다.",
"tools": {
"write": false,
"edit": false
},
"temperature": 0.1,
"permission": {
"bash": "deny"
}
}
}
}Markdown 방식 (.opencode/agents/review.md)
---
description: 코드 품질 리뷰
mode: subagent
model: anthropic/claude-sonnet-4-5
temperature: 0.1
tools:
write: false
edit: false
---
코드 리뷰어로서 품질과 보안에 집중합니다.글로벌 에이전트는 ~/.config/opencode/agents/ 디렉토리에 배치합니다.
에이전트 설정 옵션
| 옵션 | 설명 |
|---|---|
description | 에이전트 용도 (필수) |
mode | primary, subagent, all |
model | 글로벌 모델 오버라이드 |
prompt | 커스텀 시스템 지시문 |
temperature | 응답 랜덤성 (0.0–1.0) |
tools | 도구별 활성화/비활성화 |
steps | 최대 에이전틱 반복 횟수 |
disable | 에이전트 비활성화 |
color | UI 색상 ("#ff6b6b" 또는 "accent") |
permission | 도구별 접근 레벨 |
hidden | @ 자동완성에서 숨김 |
대화형 에이전트 생성
opencode agent create에이전트 Skills
v1.2.16+에서 들어온 Skills는 재사용하는 지시문 파일입니다. .opencode/skills/, .claude/skills/, .agents/skills/ 디렉토리에서 알아서 검색됩니다.
---
description: TypeScript 코드 리뷰 체크리스트
permission: allow
---
TypeScript 코드를 리뷰할 때 다음을 확인합니다:
1. strict 모드 타입 안전성
2. 에러 핸들링 패턴
3. 불필요한 any 타입 사용| 옵션 | 설명 |
|---|---|
description | 스킬 용도 (에이전트가 자동 선택 시 참고) |
permission | allow, deny, ask |
고급 팁
- 작업 성격별 분리: 탐색/리뷰/수정 에이전트를 분리해 컨텍스트 오염을 줄입니다
- 리뷰 에이전트:
write: false,bash: deny로 읽기 전용 보안 리뷰어 구성 - 비용 제어: 에이전트별 모델을 분리하여 탐색은 저비용, 생성은 고성능 모델 할당
- 모드 분리:
mode: "primary"는 Tab 전환 대상,mode: "subagent"는@호출 전용
참고 문서
- 에이전트 개요: https://opencode.ai/docs/agents
- 모드/에이전트 전환: https://opencode.ai/docs/modes