[2편] OpenCode 심화 가이드 - Oh-My-OpenCode로 나만의 워크플로우 구축하기

1편 OpenCode와 OpenCode Zen 완벽 가이드

2편 Oh-My-OpenCode로 나만의 워크플로우 구축하기

1. Oh-My-OpenCode: 커스터마이징 생태계의 이해

터미널을 즐겨 사용하는 개발자라면 Oh-My-Zsh가 주는 마법 같은 경험을 기억하실 겁니다. 기본 셸을 플러그인과 테마로 무장시켜 나만의 강력한 무기로 만드는 과정 말이죠.

OpenCode에도 이와 같은 강력한 커스터마이징 생태계가 존재합니다. 바로 Oh-My-OpenCode입니다.

Oh-My-OpenCode는 단순히 기능을 추가하는 것을 넘어, 에이전트의 지능과 인터페이스를 프로젝트의 성격에 맞게 재정의하는 시스템입니다. 이는 크게 4가지 핵심 축으로 구성됩니다.

축	역할	비유
Skills	에이전트에게 특정 도메인의 전문 지식 주입	Oh-My-Zsh의 플러그인
Commands	복잡한 프롬프트와 반복 작업 자동화	셸의 Alias 및 함수
Agents	AI 팀원의 역할과 도구 권한 정의	터미널 프로필
Themes	작업 환경의 시각적 개인화	컬러 스킴(Color Scheme)

이 가이드에서는 Skills와 Commands, 그리고 MCP 연동을 통한 외부 도구 확장법을 상세히 다룹니다. 이를 통해 여러분의 에이전트를 "그냥 AI"에서 "우리 팀 최고의 시니어 개발자"로 업그레이드할 수 있습니다.

2. Agent 시스템 기초: 빌트인 AI 팀원들

2.1 에이전트란 무엇인가?

OpenCode에서 에이전트는 단순한 챗봇이 아닌 특화된 AI 페르소나입니다. 각 에이전트는 고유한 시스템 프롬프트, 도구 접근 권한(읽기 전용 vs 수정 가능), 그리고 작업 성격에 최적화된 모델 설정을 가집니다.

2.2 Primary Agent vs Subagent

에이전트는 크게 사용자와 직접 대화하는 Primary Agent와 특정 태스크를 위임받아 백그라운드에서 실행되는 Subagent로 나뉩니다.

구분	Primary Agent	Subagent
역할	메인 대화 담당, 사용자와 직접 상호작용	특화 작업 위임, 백그라운드 병렬 처리
전환 방법	Tab 키로 순환 전환	@mention 호출 또는 자동 위임
컨텍스트	전체 대화 기록 유지 및 흐름 관리	짧은 수명, 수행 결과만 메인에 반환
예시	Build, Plan	General, Explore, Librarian, Oracle

2.3 빌트인 에이전트 완전 가이드

Oh-My-OpenCode 환경에서 제공되는 주요 에이전트들입니다.

에이전트	타입	핵심 역할	도구 권한	사용 시나리오
Build	Primary	실제 구현, 파일 수정, 명령어 실행	전체 권한	실제 코딩 및 인프라 구축 작업
Plan	Primary	아키텍처 분석, 설계, 코드 리뷰	읽기 전용	대규모 리팩토링 전 설계 검토
General	Subagent	독립적인 태스크 병렬 처리	전체 권한	단위 테스트 작성, 모듈 분리 위임
Explore	Subagent	코드베이스 패턴 탐색 및 정보 수집	읽기 전용	레거시 코드 파악, API 엔드포인트 검색
Librarian	Subagent	외부 문서 및 라이브러리 정보 조회	읽기 전용	신규 라이브러리 사용법 및 API 문서 확인
Oracle	Subagent	디버깅 자문 및 복잡한 로직 분석	읽기 전용	메모리 누수 원인 파악, 아키텍처 상담

2.4 에이전트 호출 및 전환

• Primary Agent 전환: TUI 환경에서 Tab 키를 눌러 Build와 Plan 모드를 즉시 전환할 수 있습니다.
• Subagent 호출: @mention 구문을 사용하여 대화 도중 특정 에이전트를 소환합니다.

# 특정 폴더 구조 파악 위임
@explore src/services 내의 데이터 흐름을 분석해줘

# 외부 문서 기반 사용법 확인
@librarian Next.js 15의 서버 컴포넌트 캐싱 규칙을 알려줘

3. Skills 시스템 Deep Dive: 지식의 모듈화

Skills는 에이전트에게 프로젝트 고유의 컨벤션이나 특정 도메인의 지식을 주입하는 가장 세련된 방법입니다.

3.1 저장 위치 및 호환성

에이전트는 다음 경로에서 Skills를 검색합니다.

• 프로젝트별: .opencode/skills/<이름>/SKILL.md
• 사용자 글로벌: ~/.config/opencode/skills/
• 호환 경로: .claude/skills/ 또는 .agents/skills/ 폴더도 자동 인식합니다.

3.2 SKILL.md 구조

Skills는 YAML Frontmatter와 마크다운 본문으로 작성됩니다.

---
name: frontend-standard
description: React 및 Tailwind CSS 기반의 프런트엔드 코딩 표준 가이드
---
1. 모든 컴포넌트는 함수형으로 작성하며 hooks를 적극 활용한다.
2. 스타일링은 Tailwind CSS의 유틸리티 클래스만 사용한다.
3. 복잡한 상태 관리는 Context API 대신 전역 스토어를 우선 고려한다.

3.3 보안 및 권한 제어

opencode.json 설정을 통해 특정 Skill의 로드 여부를 패턴 기반으로 제어할 수 있습니다.

{
  "permission": {
    "skill": {
      "internal-*": "deny",     // 내부용 기술 접근 차단
      "experimental-*": "ask"    // 실험적 기술 사용 시 승인 요청
    }
  }
}

4. Custom Commands: 명령어 하나로 끝내는 복잡한 프롬프트

Commands는 슬래시(/)로 시작하는 단축키입니다. 반복되는 복잡한 요청을 명령어 하나로 정의하여 생산성을 극대화합니다.

4.1 정의 방법

.opencode/commands/<이름>.md 파일을 생성하면 파일명이 곧 명령어가 됩니다.

4.2 주요 구문 및 기능

• 인자 전달: $ARGUMENTS 또는 $1, $2를 사용하여 명령 실행 시 파라미터를 넘길 수 있습니다.
• 쉘 결과 삽입: !백틱(!​command) 구문으로 터미널 명령의 실행 결과를 프롬프트에 즉시 포함합니다.

4.3 실전 명령어 예시

/security-audit - 보안 진단

현재 스테이징된 변경 사항에 대해 보안 감사를 실시하세요.
!`git diff --cached`
OWASP Top 10 기준으로 취약점을 보고하고 수정안을 제시하세요.

/api-docs - 문서화 자동화

$1 파일 내의 함수들에 대해 JSDoc 주석을 생성하세요.
반드시 예제 코드(Usage Example)를 포함해야 합니다.

5. MCP (Model Context Protocol) 연동

MCP는 에이전트가 외부 데이터 소스(데이터베이스, 웹 검색, 이슈 트래커 등)에 직접 접근할 수 있게 해주는 표준 프로토콜입니다.

5.1 opencode.json 설정 예시

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    },
    "documentation": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"]
    }
  }
}

6. Themes와 인터페이스 커스터마이징

작업 환경의 몰입도를 높이기 위해 테마를 변경할 수 있습니다.

• 내장 테마: Dracula, Nord, Solarized Dark, Catppuccin 등 지원
• 설정 경로: ~/.config/opencode/themes/ 내에 JSON 형식으로 정의
• 핵심 단축키:
  • Tab: 에이전트 모드 전환
  • Ctrl + C: 현재 작업 중단
  • Ctrl + L: 터미널 화면 정리

7. 주요 활용 시나리오

1. 코드 리뷰 자동화: /review 커맨드로 Git Diff를 분석하여 스타일 가이드를 준수했는지 확인합니다.
2. 데이터베이스 협업: Postgres MCP를 연결하여 자연어로 쿼리를 실행하고 스키마 정보를 실시간으로 참조합니다.
3. 릴리즈 준비: release-prep Skill을 활성화하여 CHANGELOG 자동 생성과 버전 범프를 수행합니다.

8. 생산성 향상을 위한 팁

1. 구체적인 Description 작성: 에이전트가 상황에 맞는 Skill을 스스로 판단할 수 있도록 설명을 명확히 작성하세요.
2. 작은 단위의 조합: 거대한 하나의 Skill보다는 명확한 역할로 나누어진 여러 개의 작은 Skill을 조합하는 것이 정확도가 높습니다.
3. 환경 변수 활용: API 키나 민감한 정보는 설정 파일 대신 {env:VARIABLE_NAME} 형식을 통해 안전하게 관리하세요.

9. 실전 시뮬레이션: 보안 점검 커맨드 실행

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

user@dev:~/my-project$ /security-audit

> OpenCode: security-auditor 기술을 로드합니다...
> 분석 중: src/controllers/authController.ts
> 분석 중: package.json

[보안 취약점 발견]
1. SQL Injection 위험 (authController.ts:45)
   - 사용자 입력을 쿼리 문자열에 직접 결합하고 있습니다.
   - 권고: Prepared Statement 사용으로 교체하십시오.

2. 안전하지 않은 종속성 (package.json)
   - axios v1.6.0: CVE-2023-45853 취약점이 포함되어 있습니다.
   - 권고: v1.7.0 이상으로 업데이트하십시오.

발견된 이슈에 대해 자동 수정을 진행할까요? (y/n)

10. 트러블슈팅

• Skill 로드 실패: 파일명이 반드시 SKILL.md(대문자)여야 하며, Frontmatter의 name 필드에 공백이 없는지 확인하세요.
• Command 인식 불가: .opencode/commands/ 폴더 경로와 마크다운 확장자를 확인하세요.
• MCP 연결 오류: npx 명령어가 전역에서 실행 가능한지 확인하고, 방화벽 설정을 점검하세요.

11. 결론: 다음 단계 예고

지금까지 Oh-My-OpenCode의 핵심 구성 요소인 Skills, Commands, Agents, Themes를 통해 나만의 워크플로우를 구축하는 방법을 살펴보았습니다. 에이전트에게 전문 지식을 학습시키고, 복잡한 작업을 명령어로 자동화하는 것만으로도 개발 속도는 비약적으로 향상됩니다.

하지만 진정한 마법은 여러 에이전트가 유기적으로 협업할 때 일어납니다.

다음 파트에서는 빌트인 에이전트를 넘어, AGENTS.md 파일을 통해 프로젝트에 완벽히 최적화된 "커스텀 에이전트"를 직접 만들고, 멀티 에이전트 오케스트레이션으로 복잡한 프로젝트를 리드하는 고급 기법을 다룹니다.

더욱 강력해질 여러분의 AI 팀을 기대하며, 3편에서 뵙겠습니다.

TL;DR

• Oh-My-OpenCode: Skills, Commands, Agents, Themes를 아우르는 통합 커스터마이징 생태계입니다.
• Skills: 에이전트에게 도메인 지식을 주입하여 일관된 답변을 유도합니다.
• Commands: 복잡한 프롬프트를 / 명령어로 단축하고 셸 실행 결과를 결합합니다.
• Agents: Build(구현), Plan(설계), Explore(탐색) 등 역할에 맞는 에이전트를 전략적으로 활용합니다.
• MCP: 외부 서비스와 데이터를 연결하여 AI의 작업 범위를 물리적으로 확장합니다.

참고 링크

• OpenCode 공식 가이드: https://opencode.dev/docs/customization
• Skills 커뮤니티 저장소: https://github.com/opencode-community/awesome-skills
• MCP 공식 문서: https://modelcontextprotocol.io
• Claude Code 호환성 안내: https://docs.anthropic.com/claude/docs/claude-code-skills