Ch3. 에이전트 설계
역할 분리, 커스텀 에이전트 구성, 서브에이전트 활용
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