Oh My OpenCode 완전 가이드: 초급 개발자를 위한 기능 총정리

OpenCode를 설치해 보면 기본 기능만으로도 충분히 유용하지만, 어느 순간 이런 생각이 들기 시작합니다.
“여기에 Claude나 Gemini, Grok도 다 붙여서 팀처럼 쓸 수 없을까?”
“프로젝트마다 규칙 설정을 자동으로 적용할 방법은 없을까?”
“agent를 여러 명 불러서 동시에 작업시키는 워크플로우는 어떻게 만들지?”

그 답을 전부 해결해주는 것이 바로 Oh My OpenCode입니다.
이 도구는 간단히 말해 OpenCode의 확장팩이자, multi-agent 개발환경을 자동 조율해주는 보조 시스템입니다.
따라서 이번 글은 초급 개발자가 꼭 이해해야 할 구조를 중심으로 정리합니다.

1. Oh My OpenCode란 무엇인가?

OpenCode는 기본적으로 단일 AI 모델과 대화를 나누며 코드를 다루는 terminal AI IDE에 가깝습니다.
하지만 실무에서는 다음이 자연스럽게 필요해집니다.

프로젝트 전반을 이해하는 아키텍트형 에이전트
UI/UX에 강한 프론트엔드 에이전트
문서를 잘 만드는 문서 전용 에이전트
빠른 코드 탐색용 가벼운 에이전트
PDF·이미지·도면을 읽는 멀티모달 에이전트

이 모든 에이전트를 한 환경에서 조합하고 관리하는 역할을 하는 것이 Oh My OpenCode입니다.

핵심 개념

여러 AI coding agent 를 “등록”하고 “역할별로 구분”하여 사용할 수 있음
파일·디렉터리·프로젝트 규칙을 자동 주입
모델 간 전환을 자연스럽게 처리
병렬 작업(ultrawork)을 가능하게 하는 구조적 기반

즉, 간단히 표현하면

“OpenCode를 실제 개발 팀처럼 만드는 확장 도구”

2. 기본 제공 AI 에이전트 소개 (초급자용 버전)

Oh My OpenCode에는 대표적인 역할 기반 agent 들이 미리 설정되어 있습니다.
초급 개발자가 익히기 좋은 순서대로 설명해볼게요.

1) @oracle — 전체 구조/아키텍처 분석 담당

복잡한 요구사항 요약
함수/모듈 간 관계 설명
리팩터링 전략 제안
프로젝트 전반의 향후 방향 논의

아래는 @oracle 명령어를 실행하면 보여지는 내용입니다.

언제 사용하나요?
“이 기능을 어디에 넣는 게 맞을까?” 라는 질문이 떠오를 때.

2) @librarian — 코드베이스 탐색 + 유사 패턴 검색

여러 파일을 빠르게 훑어봄
특정 패턴이 어디 있는지 찾아줌
유사 구현 예시 추천

언제 사용하나요?
“이 함수 어디서 쓰이지?” → 이럴 때 바로 호출.

3) @explore — 초고속 코드 탐색 에이전트

빠른 검색 및 구조 파악
가벼운 분석
Grok 모델 기반 속도형 agent

언제 사용하나요?
큰 프로젝트에서 특정 키워드/파일을 빨리 찾고 싶을 때.

4) @frontend-ui-ux-engineer

UI 구조 제안
React/Next.js 등 컴포넌트 설계
디자인 시스템 반영

언제 사용하나요?
“대시보드 페이지 하나 빠르게 스케치해줘.”

5) @document-writer

README
개발가이드
API 문서
PR 설명문 초안

언제 사용하나요?
기능 개발 후 문서화해야 하는 순간.

6) @multimodal-looker

이미지/PDF/도면 분석
UI 스크린샷 해석
플로우차트 설명

언제 사용하나요?
회의 자료나 PDF 설계 문서를 이해하고 싶을 때.

3. 규칙 자동 주입: AGENTS.md / 디렉터리 룰 / 조건부 룰

Oh My OpenCode의 가장 강력한 기능 중 하나입니다.

1) AGENTS.md 자동 주입

프로젝트 루트 또는 디렉터리 수준에 AGENTS.md 파일을 두면,
AI는 해당 경로에 들어오는 순간 그 규칙을 자동으로 인식합니다.

예를 들어

/src/auth/AGENTS.md

여기에

인증 규칙
예외 처리 방식
파일 구조 원칙
을 적어 두면, auth 관련 파일에서 작업할 때 AI는 자동으로 이 규칙을 따릅니다.

2) 디렉터리 기반 규칙

하위 디렉터리를 내려가면 내려갈수록 규칙이 덮어씌워집니다.
대규모 프로젝트에서 매우 유용합니다.

3) 조건부 규칙 (.claude/rules/*.md)

예:

---
globs: ["*.ts", "src/**/*.js"]
---
- 함수 이름은 camelCase
- 컴포넌트 이름은 PascalCase

언어별·폴더별 스타일 가이드를 자동 적용할 수 있습니다.

4. 자동화 훅(hook) 시스템

Oh My OpenCode는 다양한 자동화 훅을 제공합니다.
초급 개발자가 알아두면 좋은 핵심만 추려볼게요.

keyword-detector

사용자가 “리팩터링”, “분석”, “찾아줘”, “정리해줘”라고 하면
agent를 자동 전환하거나 모드를 조정.

auto-compact

대화가 길어지면 AI가 스스로 요약하고 맥락을 유지.

todo-enforcer

작업 중 “TODO”를 만들면, 완료할 때까지 안내.

session-recovery

TUI가 종료되거나 에러가 나도 세션을 되살림.

이런 자동화 덕분에 초급자도 훨씬 편하게 작업할 수 있습니다.

5. LSP + AST-Grep: 초급자가 실력 있게 보이는 순간

LSP(Language Server Protocol)

에디터처럼 다음이 모두 가능합니다.

변수 정의로 이동
함수 참조 찾기
진단 메시지
코드 액션(Quick Fix)
Rename Refactor

터미널 기반임에도 IDE 수준 작업을 AI가 수행할 수 있는 이유가 바로 이것입니다.

AST-Grep

문법 기반 검색·치환 도구입니다.

예:
“모든 파일에서 var를 let으로 바꿔줘. 단, 문자열 내부는 제외.”

이런 작업이 단 한 줄의 요청으로 가능합니다.

6. oh-my-opencode.json: 모든 기능의 중심

이 설정 파일을 통해

agent 추가/삭제
모델 선택
훅 활성화/비활성
MCP(외부 도구) 연결
규칙 우선순위 정의
를 모두 관리하게 됩니다.

초급자라면 처음에는 다음 세 가지만 설정해도 충분합니다.

기본 agent 세트 유지
모델 프로바이더 연결
auto-complete 기능 활성화

이후 프로젝트 규모가 커지면 상세 설정을 확장하는 방식이 좋습니다.

7. 초급 개발자를 위한 추천 사용 패턴

1) “요약 → 제안 → 반영” 3단계

AI에게 바로 구현을 시키지 말고

설명 요청
개선 제안
반영 확인
순서로 작업하면 실수 확률이 줄어듭니다.

2) agent를 “직무”로 생각하기

예:

설계 검토: @oracle
UI 작업: @frontend-ui-ux-engineer
코드 포맷 정리: LSP
문서화: @document-writer

3) 작은 작업부터 시작

함수 분리
코드 설명
테스트 초안
문서 요약

이렇게 단계적으로 키우면 multi-agent 개발이 자연스러워집니다.

정리하기

이번 글에서는 Oh My OpenCode가 어떤 구조로 동작하며,
왜 OpenCode 사용자라면 반드시 함께 사용해야 하는지 초급자 관점에서 정리해 보았습니다.

핵심은 아주 단순합니다.

“여러 AI coding agent 를 하나의 개발 환경에서 팀처럼 조직해 주는 확장 시스템”

다음 글에서는 oh-my-opencode.json 설정방법 및 커스텀 에이전트 만들기를 다룹니다.
이 설정 파일 하나만 이해하면 OpenCode 사용 경험이 완전히 달라질 거예요.

Oh My OpenCode 완전 가이드: 초급 개발자를 위한 기능 총정리