[AI] oh-my-opencode 도입기

🛠️ 개발 환경

• OpenCode : 1.2.14
• OS : Mac OS

💬 OmO(oh-my-opencode)란

Github: oh-my-opencode

이 오픈 소스를 도입하기 전, AI를 활용한 코딩 도구가 어떻게 진화했는지 짚고 넘어갈 필요가 있다.

세대	핵심 개념	작동 방식 및 설명	대표 사례
1세대	Auto Completion	개발자가 코드를 입력하면, 문맥을 파악해 알맞은 코드를 제안	GitHub Copilot (초창기)
2세대	Chat with AI	웹이나 IDE 플러그인에서 질문하면 코드 스니펫이나 해결책을 응답	ChatGPT, Claude 웹
3세대	AI Agent	터미널 환경에서 AI 에이전트가 직접 파일 시스템에 접근하여 코드를 작성하고 수정	Gemini CLI, Claude Code, Cursor
4세대	AI Agent Team	여러 AI 모델을 조합해 기획, 구현, 검토 등 역할을 분담하여 자율적으로 프로젝트 개발	oh-my-claudecode, oh-my-opencode 등

oh-my-opencode(OmO)는 현시점 최신 세대인 AI Agent Team(멀티 에이전트 오케스트레이터)에 해당하는 강력한 오픈소스다. Gemini CLI나 Claude Code가 훌륭한 '단일 개발자'라면, oh-my-opencode는 작업의 성격에 맞춰 각 분야의 최고 AI 모델을 적재적소에 배치하고 지휘하는 수석 아키텍트이자 자동화된 개발 팀이다.

❓ 왜 사용할까

단일 AI Agent도 훌륭한데, 굳이 복잡해 보이는 AI Agent Team 프레임워크를 사용하는 이유는 무엇일까? 개인적으로는 세 가지 명확한 이점이 있다고 생각한다.

1. 컨텍스트 분리를 통한 API 토큰(비용) 최소화

단일 CLI 환경에서 AI와 대화를 이어가다 보면 이전 대화 기록이 누적되어 컨텍스트 윈도우(Context Window)가 비대해진다. 수시로 대화를 압축(/compress)하지 않으면 불필요한 입력 토큰이 계속 소모된다.

 

OmO는 작업을 세분화하여, 특정 에이전트(예: 단순 코드 수정 담당)는 필요한 최소한의 파일과 문맥만 들고 실행된다. 불필요한 토큰 낭비를 막아 비용을 극적으로 절감한다.

2. 구체적인 계획 수립과 자율 실행 분리 (Prometheus & Sisyphus)

일반적인 Agent에게 "게시판 API 만들어줘"라고 하면 곧바로 코드를 짜다가 길을 잃는 경우가 많다. 하지만 OmO는 다르게 접근한다.

 

Prometheus 에이전트가 먼저 인터뷰 모드로 개발자에게 요구사항을 역질문하며 완벽한 계획 문서(Plan)를 수립한다. 이후 Sisyphus 에이전트가 이 계획을 바탕으로 하위 에이전트들을 지휘하며 작업이 끝날 때까지 무한 루프(Ralph Loop)를 돌며 코드를 완성한다.

3. 안전한 코드 편집 (Hash-Anchored Edits & AST-Grep)

기존 AI 도구들의 가장 큰 문제는 코드를 덮어쓸 때 들여쓰기를 망치거나 엉뚱한 라인을 날려버리는 것이다. OmO는 각 코드 라인에 해시(Hash)를 부여하여, 원본이 변경되었거나 해시가 일치하지 않으면 편집을 거부한다. Kotlin/Spring Boot 처럼 패키지 구조가 깊고 파일 간 의존성이 복잡한 프로젝트를 리팩토링할 때 필수적인 안정성을 보장한다.

⚙️ 설치 방법

설치 과정은 직접 설정 파일을 건드리는 것보다 Agent에게 위임하는 것이 가장 확실하다. 터미널에서 기존에 사용하던 AI Agent(Gemini CLI, Claude Code 등)를 실행한 뒤 다음 프롬프트를 입력한다.

Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/refs/heads/master/docs/guide/installation.md

공식 README에도 "사람은 설정하다 오타를 내니, Agent에게 시켜라(Let an agent do it)"라고 명시되어 있다. Agent가 가이드 문서를 읽고 알아서 환경에 맞게 설치를 진행한다.

 

설치 중 Provider(OpenAI, Anthropic, Google 등)를 선택하게 되는데, API 비용 최적화를 위해 Gemini를 메인으로 구성했다. (Google AI Studio에서 제공하는 무료 크레딧을 활용하면 초기 구축 비용을 크게 아낄 수 있다.)

 

환경 변수에 API 키가 없다면 터미널 설정 파일에 추가해 준다.

# zsh 사용 시
echo 'export GOOGLE_GENERATIVE_AI_API_KEY="YOUR_API_KEY"' >> ~/.zshrc
source ~/.zshrc

# 정상 등록 확인
echo $GOOGLE_GENERATIVE_AI_API_KEY

공식 문서에 "모든 에이전트는 해당 모델의 특장점에 맞춰 튜닝되어 있습니다. 수동으로 모델 바꿔가며 뻘짓하지 마세요."라고 나와있듯이, 모델을 따로 지정할 필요는 없다. 하지만 비용에 큰 부담이 있을 것 같다면 직접 사용할 모델을 수정해도 된다.

vim ~/.config/opencode/oh-my-opencode.json

👾 Agent 구성

설치가 완료되면 터미널에 opencode를 입력하여 실행한다. tab 키를 누르면 프로젝트를 책임질 다양한 에이전트 목록을 확인할 수 있다.

이름	설명
Sisyphus (Orchestrator)	개발 팀의 리더. 하위 에이전트들에게 작업을 위임하고, 작업이 100% 완료될 때까지 집요하게 밀어붙인다.
Prometheus (Planner)	아키텍트 역할. 코드를 건드리기 전, 인터뷰를 통해 시스템 구조와 예외 상황을 고려한 명확한 작업 계획서를 작성한다.
Atlas (Executor)	실제 코드를 작성하는 실무자. Prometheus가 세운 계획을 바탕으로 파일을 수정하고 로직을 구현한다.

사용 방법

가장 효율적인 작업 워크플로우는 다음과 같다.

1. 프로젝트 이동 및 실행

AI Agent Team에게 개발을 맡길 프로젝트로 이동한 뒤에, opencode를 실행한다.

cd {프로젝트_경로}
opencode

2. 초기 컨텍스트 구성

프로젝트 구조를 AI가 이해할 수 있도록 다음 명령어를 입력해 AI가 AGENTS.md 파일을 생성하도록 한다.

/init-deep

 

3. 기획 및 계획 수립

Prometheus를 호출하여 만들고자 하는 기능을 설명한다. 사진과 같이 요구사항이 애매할 경우, AI가 사용자에게 질문을 던지게 된다. 이에 대해 구체적인 답변을 입력하면, 요구사항 명세서를 완성시킨다.

 

4. 개발 시작

계획이 수립되면 Atlas를 호출하여 /start-work 명령어를 입력한다.

/start-work

그러면 Prometheus에게 맡겼던 계획 정보를 Atlas가 이어 받아서 개발을 한다. 그러면 백그라운드에서 에이전트들을 스폰하여 파일 수정, 빌드, 오류 수정을 알아서 반복한다. 완료될 때까지 기다리면 된다.

5. 자동 개발

만약, 계획 수립, 개발 시작을 내가 입력하지 않아도 알아서 하도록 만들고 싶다면, Sisyphus에게 /ulw 명령어를 사용하면 된다. 그러면 백그라운드에서 에이전트 팀을 스폰하여 작업이 끝날 때까지 멈추지 않고 개발을 진행한다.

🤔 회고

Sisyphus의 자율 주행 성능은 정말 좋지만, 개인적으로는 Prometheus로 탄탄하게 계획을 세운 뒤 Atlas로 실행하는 워크플로우가 가장 안정적이고 깔끔하게 느껴진다. 단일 AI 에이전트(Claude Code, Gemini CLI 등)와 비교했을 때 속도 면에서는 느리지만, 그 단점을 충분히 상쇄할 만큼의 압도적인 꼼꼼함을 보여준다.

 

특히 내가 미처 고려하지 못한 엣지 케이스나 유스케이스까지 세밀하게 커버해 주는 점이 정말 놀라웠다. 이제는 단순히 코드를 직접 작성하는 시대를 넘어, 의도를 정확히 전달하는 프롬프트 엔지니어링(Prompt Engineering)의 역량이 개발자의 핵심 실력이 되었음을 실감한다.