1편 OpenCode와 OpenCode Zen 완벽 가이드
2편 Oh-My-OpenCode로 나만의 워크플로우 구축하기

3편 Custom Agents 가이드

OpenCode 완벽 가이드 Part 3 - 커스텀 에이전트와 멀티 에이전트 오케스트레이션

1. 에이전트 혁명: 코딩 보조를 넘어 AI 팀 빌딩으로

Part 2에서 우리는 빌트인 에이전트(Build, Plan, General, Explore)의 역할과 Skills, Commands를 활용한 워크플로우 자동화를 살펴보았습니다. 하지만 실제 프로젝트에서는 이것만으로 부족합니다. 여러분의 팀만의 코딩 컨벤션, 특수한 보안 요구사항, 복잡한 도메인 지식을 AI가 완벽히 이해하기를 원할 것입니다.

OpenCode의 커스텀 에이전트 시스템은 바로 이 문제를 해결합니다. 단순한 코드 자동 완성 도구가 아닌, 프로젝트의 맥락을 깊이 이해하는 전문가 AI 팀을 구축할 수 있습니다. 코드 리뷰 전문가, 보안 감사관, 문서화 작가, 성능 튜너 등 역할별로 최적화된 에이전트를 정의하고, 이들이 협력하여 복잡한 작업을 분담 처리하는 멀티 에이전트 오케스트레이션까지 다룹니다.

2. AGENTS.md: 프로젝트의 AI 헌법

2.1 AGENTS.md란?

AGENTS.md는 프로젝트 루트에 위치하는 마크다운 파일로, OpenCode에게 프로젝트 맥락과 작업 규칙을 전달합니다. Cursor의 rules와 유사한 개념으로, LLM의 시스템 프롬프트에 자동으로 주입되어 모든 대화에서 참조됩니다.

프로젝트 루트/
├── AGENTS.md          # 프로젝트별 AI 지시 파일
├── opencode.json      # 에이전트 및 도구 설정
├── .opencode/
│   └── agents/        # 개별 에이전트 정의 파일
└── src/

2.2 AGENTS.md 작성하기

# Ecommerce Platform Development Guide

## 프로젝트 개요
Next.js 15 기반 이커머스 플랫폼입니다. 
TypeScript strict 모드를 사용하며, Prisma ORM과 PostgreSQL을 활용합니다.

## 코딩 컨벤션
- 함수명은 camelCase, 컴포넌트명은 PascalCase
- API 응답은 반드시 `ApiResponse<T>` 타입으로 래핑
- 에러 핸들링은 `try-catch` 대신 Result 패턴 사용

## 금지 사항
- 기존 라이브러리 버전 변경 금지 (의존성 충돌 방지)
- `any` 타입 사용 금지
- 직접적인 SQL 쿼리 작성 금지 (Prisma만 사용)

## 외부 파일 참조
CRITICAL: 파일 참조 (@docs/api-guide.md)를 만나면 Read 도구로 해당 파일을 로드하세요.

- 코드 스타일 가이드: @docs/code-style.md
- API 설계 원칙: @docs/api-design.md
- 테스트 전략: @test/testing-guide.md

2.3 실전 AGENTS.md 템플릿

프로젝트의 성격에 맞춰 아래 템플릿을 복사해서 사용하세요. OpenCode는 이 파일의 내용을 바탕으로 여러분의 코딩 스타일을 학습합니다.

# Ecommerce Platform Development Guide

## 프로젝트 정보
- 언어: TypeScript 5.x
- 프레임워크: Next.js 14 (App Router)
- 데이터베이스: PostgreSQL + Prisma
- 테스트: Vitest + Testing Library

## 코딩 컨벤션
1. 모든 컴포넌트는 함수형 + TypeScript
2. 스타일링: Tailwind CSS only (no CSS-in-JS)
3. 상태관리: React Query + Zustand
4. API 응답: `{ success: boolean, data?: T, error?: string }`

## 파일 구조 규칙
- 컴포넌트: `src/components/{Feature}/{Component}.tsx`
- API 라우트: `src/app/api/{resource}/route.ts`
- 유틸: `src/lib/{category}.ts`

## 금지 사항 (NEVER DO)
- `any` 타입 사용 금지
- `console.log` 프로덕션 코드에 남기기 금지
- 직접 SQL 쿼리 금지 (Prisma만 사용)
- 하드코딩된 URL/API 키 금지

## 참조 문서
- @docs/api-spec.md
- @docs/database-schema.md

2.4 파일 위치와 우선순위

OpenCode는 다음 순서로 규칙 파일을 검색합니다:

위치	용도	공유 범위
`./AGENTS.md`	프로젝트별 규칙	팀 전체 (Git 커밋)
`~/.config/opencode/AGENTS.md`	글로벌 개인 규칙	개인만
`./CLAUDE.md`	Claude Code 호환 (폴백)	팀 전체

프로젝트별 AGENTS.md가 글로벌보다 우선하며, 두 파일이 모두 존재할 경우 내용이 병합되어 적용됩니다.

2.5 opencode.json에서 추가 지시 파일 연결

기본 AGENTS.md 외에도 프로젝트의 다른 문서들을 지시 사항으로 연결할 수 있습니다.

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md",
    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
  ]
}

2.6 /init 명령어로 자동 생성

# OpenCode TUI에서
/init

이 명령어는 프로젝트를 스캔하여 기술 스택과 의존성을 분석한 후, 최적화된 AGENTS.md 초안을 자동으로 생성해 줍니다.

3. 커스텀 에이전트 정의하기

3.1 JSON 방식: opencode.json에서 정의

opencode.json을 통해 에이전트의 모델, 온도, 권한 등을 정밀하게 제어할 수 있습니다.

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "security-auditor": {
      "description": "OWASP Top 10 기준으로 코드 보안 취약점을 분석합니다",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.1,
      "steps": 20,
      "prompt": "당신은 10년 경력의 시니어 보안 엔지니어입니다. 코드를 검토할 때 다음에 집중하세요:\\n1. SQL/NoSQL 인젝션\\n2. XSS (Cross-Site Scripting)\\n3. CSRF 토큰 검증\\n4. 인증/인가 로직\\n5. 하드코딩된 시크릿\\n6. 안전하지 않은 의존성",
      "tools": {
        "read": true,
        "grep": true,
        "glob": true,
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "SOLID 원칙과 클린 코드 기준으로 품질을 검토합니다",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.2,
      "steps": 15,
      "prompt": "당신은 코드 리뷰 전문가입니다. 다음을 중점적으로 검토하세요:\\n- 단일 책임 원칙(SRP) 준수\\n- 함수 길이 (20줄 이하 권장)\\n- 적절한 에러 핸들링\\n- 테스트 커버리지\\n- 네이밍 컨벤션",
      "tools": {
        "read": true,
        "grep": true,
        "write": false
      }
    },
    "test-writer": {
      "description": "Vitest 기반 단위/통합 테스트를 작성합니다",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
      "prompt": "당신은 TDD 전문가입니다. 테스트 작성 시:\\n- AAA 패턴 (Arrange-Act-Assert) 사용\\n- 엣지 케이스 포함\\n- 모킹은 최소화\\n- 설명적인 테스트 이름",
      "tools": {
        "read": true,
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "docs-writer": {
      "description": "JSDoc, README, API 문서를 작성합니다",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.4,
      "prompt": "당신은 기술 문서 작가입니다. 문서 작성 시:\\n- 간결하고 명확한 설명\\n- 실행 가능한 코드 예시 포함\\n- 파라미터와 반환값 명시\\n- 에러 케이스 문서화",
      "tools": {
        "read": true,
        "write": true,
        "edit": true
      }
    }
  }
}

3.2 Markdown 방식: 개별 파일로 정의

에이전트별로 복잡한 프롬프트나 파일 기반 권한 관리가 필요할 때 유용합니다. .opencode/agents/api-designer.md 파일을 생성하는 예시입니다.

---
description: RESTful API 엔드포인트를 설계하고 OpenAPI 스펙을 생성합니다
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.2
steps: 25
tools:
  read: true
  write: true
  edit: true
  bash: false
permission:
  bash: deny
  edit:
    "*": allow
    "src/app/api/**": allow
    "docs/api/**": allow
---

# API Designer Agent

당신은 RESTful API 설계 전문가입니다.

## 설계 원칙
1. **RESTful 규칙 준수**: 적절한 HTTP 메서드 사용 (GET/POST/PUT/PATCH/DELETE)
2. **일관된 응답 형식**: `{ success: boolean, data?: T, error?: { code: string, message: string } }`
3. **버전 관리**: URL에 버전 포함 (`/api/v1/...`)
4. **페이지네이션**: `?page=1&limit=20` 형식
5. **에러 코드 표준화**: HTTP 상태 코드 + 커스텀 에러 코드

## 산출물
- Next.js Route Handler 코드 (`src/app/api/.../route.ts`)
- Zod 스키마 (`src/lib/validations/...`)
- OpenAPI 3.0 스펙 (YAML)

## 코드 템플릿
```typescript
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const RequestSchema = z.object({
  // Define schema
});

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const validated = RequestSchema.parse(body);

    // Business logic here

    return NextResponse.json({ success: true, data: result });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { success: false, error: { code: 'VALIDATION_ERROR', message: error.message } },
        { status: 400 }
      );
    }
    return NextResponse.json(
      { success: false, error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' } },
      { status: 500 }
    );
  }
}


### 3.3 주요 설정 옵션 상세

| 옵션 | 타입 | 설명 |
| --- | --- | --- |
| description | string | 에이전트 설명 (필수). UI와 자동 라우팅에 사용 |
| mode | string | `primary`, `subagent`, `all` 중 선택 |
| model | string | 사용할 LLM 모델 (예: `anthropic/claude-sonnet-4-20250514`) |
| temperature | float | 0.0~1.0. 낮을수록 결정적, 높을수록 창의적 |
| steps | int | 최대 에이전틱 반복 횟수 (비용 제어용) |
| tools | object | 도구별 활성화/비활성화 |
| permission | object | `allow`, `deny`, `ask` 권한 설정 |
| hidden | bool | `@` 자동완성에서 숨김 (내부용 에이전트) |

### 3.4 에이전트 생성 CLI

```bash
opencode agent create

대화형으로 에이전트를 생성합니다. 저장 위치, 역할, 도구 권한을 선택하면 마크다운 파일이 자동 생성됩니다.

3.5 에이전트 관리 CLI 명령어

자주 사용되는 에이전트 관련 명령어들입니다.

# 에이전트 목록 확인
opencode agent list

# 특정 에이전트 상세 정보
opencode agent info security-auditor

# 에이전트 테스트 실행
opencode agent test code-reviewer --file src/components/Button.tsx

# 에이전트 비활성화
opencode agent disable docs-writer

# 새 에이전트 대화형 생성
opencode agent create

4. Task 도구: 멀티 에이전트 오케스트레이션의 핵심

4.1 Task 도구란?

Task 도구는 Primary Agent가 Subagent에게 작업을 위임하는 메커니즘입니다. 복잡한 작업을 전문화된 에이전트들에게 분배하여 효율성을 극대화합니다.

[사용자] → [Build Agent] → [Task 도구] → [Subagent]
                ↓                           ↓
         메인 대화 유지              독립 세션에서 작업
                ↓                           ↓
         결과 수신 ←←←←←←←←←←←←←←← 작업 완료 후 반환

4.2 Task 권한 설정

어떤 서브에이전트를 호출할 수 있는지 제어하여 보안과 효율을 관리합니다.

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "security-*": "allow",
          "docs-writer": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

4.3 수동 호출: @mention

사용자가 직접 특정 에이전트를 호출하여 작업을 요청할 수 있습니다.

# Explore 서브에이전트로 코드베이스 탐색
@explore src/에서 인증 관련 파일을 모두 찾아줘

# 커스텀 에이전트 호출
@security-auditor 이 PR의 변경사항에서 보안 취약점을 분석해줘

5. 멀티 에이전트 오케스트레이션 패턴

5.1 순차 체이닝 (Sequential Chaining)

[Explorer] → 파일 경로 발견 → [Security Auditor] → 취약점 분석 → [Build] → 수정

5.2 병렬 처리 (Parallel Execution)

                    ┌→ [API Developer] → API 구현
[Build Agent] ──────┼→ [Frontend Dev] → UI 구현
                    └→ [Test Writer] → 테스트 작성

5.3 오케스트레이터 패턴

라우팅 전용 에이전트가 요청을 분석하고 적절한 에이전트에게 위임하는 고도화된 패턴입니다.

---
description: 사용자 요청을 분석하여 적절한 전문 에이전트에게 라우팅합니다
mode: primary
model: anthropic/claude-haiku-4-20250514
temperature: 0.1
tools:
  task: true
---

# Orchestrator Agent
당신은 **라우터**입니다. 사용자 요청을 분석하여 `explorer`, `security-auditor`, `build` 등 가장 적합한 에이전트에게 작업을 위임하세요.

6. 실전 멀티 에이전트 시스템 구축

6.1 코드 리뷰 파이프라인

{
  "agent": {
    "frontend-reviewer": {
      "description": "프론트엔드 코드 품질과 접근성을 검토합니다",
      "mode": "subagent",
      "prompt": "React, 성능 최적화, 웹 접근성(WCAG)에 집중하세요."
    },
    "backend-reviewer": {
      "description": "백엔드 로직과 데이터베이스 쿼리를 검토합니다",
      "mode": "subagent", 
      "prompt": "API 설계, N+1 쿼리, 에러 핸들링에 집중하세요."
    }
  }
}

6.2 문서 자동 동기화

{
  "command": {
    "sync-docs": {
      "description": "코드 변경사항에 맞춰 문서를 업데이트합니다",
      "template": "1. git diff 확인\\n2. @explorer로 문서 탐색\\n3. @docs-writer로 업데이트",
      "agent": "build"
    }
  }
}

7. 실전 시뮬레이션: 풀스택 기능 구현

⚠️ 아래 내용은 실제 실행 결과가 아닌 텍스트 시뮬레이션입니다.

시나리오: 사용자 프로필 편집 기능 추가 (이커머스 플랫폼)

User: 사용자 프로필 편집 기능을 추가하려고 해. 
      DB 스키마부터 API, 프론트엔드 UI까지 전체 구현이 필요해.

Build Agent: 복잡한 풀스택 작업이네요. 먼저 현재 구조를 파악하겠습니다.

[Task: @explorer]
"사용자 관련 파일 구조를 분석해주세요:
- DB 스키마 (prisma/schema.prisma)
- 기존 API 엔드포인트 (/api/users/)
- 프론트엔드 컴포넌트 (components/user/)"

Explorer 결과:
- prisma/schema.prisma: User 모델에 name, email, avatar 필드 존재
- src/app/api/users/[id]/route.ts: GET만 구현됨
- src/components/user/UserCard.tsx: 읽기 전용 컴포넌트

Build Agent: 분석 완료. 이제 전문 에이전트들에게 작업을 분담합니다.

[Task: @api-designer]
"src/app/api/profile/route.ts에 PATCH 핸들러를 구현하세요.
- 사용자 이름, 바이오, 웹사이트 URL 업데이트 가능
- Zod 스키마를 이용한 입력 검증 포함
- 유효한 세션이 있는지 체크하는 미들웨어 로직 적용"

[Task: @frontend-ui-ux] (병렬 실행)
"src/components/profile/ProfileEditForm.tsx를 생성하세요.
- React Hook Form과 Zod 사용
- Tailwind CSS로 깔끔한 UI 설계
- 수정 성공 시 토스트 메시지 알림"

--- 2분 후 ---

API Designer 결과:
✓ src/app/api/profile/route.ts 구현 완료
✓ src/lib/validations/profile.ts (Zod 스키마) 생성

Frontend UI/UX 결과:
✓ src/components/profile/ProfileEditForm.tsx 생성
✓ API 연동을 위한 전용 훅(useUpdateProfile) 작성

Build Agent: 백엔드와 프론트엔드 핵심 구현이 완료되었습니다. 
             보안 감사를 진행한 후 최종 병합하겠습니다.

[Task: @security-auditor]
"방금 작성된 API와 폼의 보안을 검토해주세요."

Security Auditor 결과:
⚠️ 발견된 취약점:
1. [HIGH] 인가 누락: PATCH 요청 시 현재 로그인한 사용자가 프로필 소유자인지 대조하는 로직 필요
2. [MEDIUM] XSS 위험: 'website' 필드에 'javascript:' 프로토콜 차단 필요

Build Agent: 지적된 보안 취약점을 즉시 수정하고 완료 보고를 드리겠습니다.

8. 에이전트 시스템 최적화 팁

Tip 1: 모델 전략 분리

분석/탐색에는 가벼운 모델(Haiku), 구현에는 강력한 모델(Sonnet/GPT-4)을 할당하여 비용과 속도를 최적화하세요.

Tip 2: 컨텍스트 위생

서브에이전트는 대화 맥락을 공유하지 않으므로, Task 프롬프트에 필요한 모든 정보를 명확히 포함해야 합니다.

# 나쁜 예: @explorer "그 파일 찾아줘"
# 좋은 예: @explorer "src/auth/ 디렉토리에서 JWT 검증 로직이 있는 파일을 찾아줘"

Tip 3: steps로 비용 제어

steps 옵션으로 에이전트의 최대 반복 횟수를 제한하여 무한 루프나 과도한 비용 발생을 방지하세요.

9. 트러블슈팅

커스텀 에이전트가 목록에 없음

파일 위치(.opencode/agents/)와 YAML description 필드가 필수인지 확인하세요.

Task 권한 거부

opencode.json의 permission.task 설정에서 해당 에이전트가 allow로 되어 있는지 확인하세요.

10. 결론: 나만의 AI 개발팀 구축

커스텀 에이전트와 오케스트레이션은 OpenCode를 단순한 도구에서 지능형 개발 플랫폼으로 진화시킵니다. 이제 여러분은 코드를 한 줄씩 작성하는 개발자가 아닌, 전문가 AI 팀을 지휘하는 아키텍트로서 더 창의적인 설계에 집중할 수 있습니다.

11. TL;DR

AGENTS.md: 프로젝트 루트에 생성하여 AI에게 규칙 전수, /init으로 자동 생성 가능
커스텀 에이전트: JSON 또는 Markdown 방식으로 역할별 전문 에이전트 정의
Task 도구: Primary Agent가 Subagent에게 작업을 위임하는 핵심 메커니즘
@mention: 사용자가 직접 서브에이전트를 호출하는 간편한 방법
오케스트레이션: 순차/병렬 처리를 통해 복잡한 풀스택 작업을 자동화

12. 참고 링크

OpenCode 공식 문서: https://opencode.ai/docs/
OpenCode GitHub: https://github.com/anomalyco/opencode
AGENTS.md 표준 사양: https://agents.md/
멀티 에이전트 코드 리뷰 사례: https://blog.devgenius.io/multi-agent-code-review

'AI' 카테고리의 다른 글

[4편] CliProxyAPI 완벽 가이드 - CLI AI 모델을 표준 API로 통합하기 (0)	2026.02.06
Reverse-SynthID 완벽 분석 - 구글의 워터마크를 뚫어보자 (0)	2026.02.06
[2편] OpenCode 심화 가이드 - Oh-My-OpenCode로 나만의 워크플로우 구축하기 (0)	2026.02.05
[1편] OpenCode와 OpenCode Zen 완벽 가이드 - 무료 AI 코딩의 새로운 표준 (0)	2026.02.05
Moltbook 사태 완벽 분석 - 개인화 AI의 보안 (0)	2026.02.04

Isaac Note

[3편] OpenCode + Custom Agents 가이드 - 커스텀 에이전트와 멀티 에이전트 오케스트레이션

3편 Custom Agents 가이드

OpenCode 완벽 가이드 Part 3 - 커스텀 에이전트와 멀티 에이전트 오케스트레이션

1. 에이전트 혁명: 코딩 보조를 넘어 AI 팀 빌딩으로

2. AGENTS.md: 프로젝트의 AI 헌법

2.1 AGENTS.md란?

2.2 AGENTS.md 작성하기

2.3 실전 AGENTS.md 템플릿

2.4 파일 위치와 우선순위

2.5 opencode.json에서 추가 지시 파일 연결

2.6 /init 명령어로 자동 생성

3. 커스텀 에이전트 정의하기

3.1 JSON 방식: opencode.json에서 정의

3.2 Markdown 방식: 개별 파일로 정의

3.5 에이전트 관리 CLI 명령어

4. Task 도구: 멀티 에이전트 오케스트레이션의 핵심

4.1 Task 도구란?

4.2 Task 권한 설정

4.3 수동 호출: @mention

5. 멀티 에이전트 오케스트레이션 패턴

5.1 순차 체이닝 (Sequential Chaining)

5.2 병렬 처리 (Parallel Execution)

5.3 오케스트레이터 패턴

6. 실전 멀티 에이전트 시스템 구축

6.1 코드 리뷰 파이프라인

6.2 문서 자동 동기화

7. 실전 시뮬레이션: 풀스택 기능 구현

8. 에이전트 시스템 최적화 팁

Tip 1: 모델 전략 분리

Tip 2: 컨텍스트 위생

Tip 3: steps로 비용 제어

9. 트러블슈팅

커스텀 에이전트가 목록에 없음

Task 권한 거부

10. 결론: 나만의 AI 개발팀 구축

11. TL;DR

12. 참고 링크

'AI' 카테고리의 다른 글

티스토리툴바

[3편] OpenCode + Custom Agents 가이드 - 커스텀 에이전트와 멀티 에이전트 오케스트레이션

3편 Custom Agents 가이드

OpenCode 완벽 가이드 Part 3 - 커스텀 에이전트와 멀티 에이전트 오케스트레이션

1. 에이전트 혁명: 코딩 보조를 넘어 AI 팀 빌딩으로

2. AGENTS.md: 프로젝트의 AI 헌법

2.1 AGENTS.md란?

2.2 AGENTS.md 작성하기

2.3 실전 AGENTS.md 템플릿

2.4 파일 위치와 우선순위

2.5 opencode.json에서 추가 지시 파일 연결

2.6 /init 명령어로 자동 생성

3. 커스텀 에이전트 정의하기

3.1 JSON 방식: opencode.json에서 정의

3.2 Markdown 방식: 개별 파일로 정의

3.5 에이전트 관리 CLI 명령어

4. Task 도구: 멀티 에이전트 오케스트레이션의 핵심

4.1 Task 도구란?

4.2 Task 권한 설정

4.3 수동 호출: @mention

5. 멀티 에이전트 오케스트레이션 패턴

5.1 순차 체이닝 (Sequential Chaining)

5.2 병렬 처리 (Parallel Execution)

5.3 오케스트레이터 패턴

6. 실전 멀티 에이전트 시스템 구축

6.1 코드 리뷰 파이프라인

6.2 문서 자동 동기화

7. 실전 시뮬레이션: 풀스택 기능 구현

8. 에이전트 시스템 최적화 팁

Tip 1: 모델 전략 분리

Tip 2: 컨텍스트 위생

Tip 3: steps로 비용 제어

9. 트러블슈팅

커스텀 에이전트가 목록에 없음

Task 권한 거부

10. 결론: 나만의 AI 개발팀 구축

11. TL;DR

12. 참고 링크

'AI' 카테고리의 다른 글

관련글

티스토리툴바