OpenCode + OMO 에이전트 실전 가이드

에이전트를 많이 만든다고 작업이 자동으로 잘 굴러가지는 않는다. 오히려 역할이 겹치고, 권한이 과하게 열리고, 어느 순간부터는 사람이 에이전트들을 관리하느라 더 바빠지는 일이 생긴다. OpenCode와 OMO(Oh My OpenAgent)를 함께 쓸 때 필요한 것은 더 많은 프롬프트가 아니라, 역할과 경계를 먼저 정리하는 설계다.

이 시리즈는 OpenCode의 커스텀 에이전트 설계와 OMO의 오케스트레이션을 하나의 운영 가능한 흐름으로 묶는 방법을 다룬다.

시리즈 구성

1. 에이전트가 필요한 순간 — 커스텀 에이전트를 만들기 전에 command, skill, AGENTS.md 같은 더 가벼운 선택지로 충분한지 먼저 판단한다.
2. 에이전트 파일 작성하기 — frontmatter와 시스템 프롬프트를 나눠 모델, 권한, 출력 형식을 고정하는 방법을 정리한다.
3. 권한·커맨드·스킬·툴 설계하기 — permission으로 물리적 경계를 만들고 command, skill, custom tool, MCP로 실행 표면을 확장한다.
4. OMO에 연결하기 — OpenCode 커스텀 에이전트와 OMO 내장 에이전트의 역할을 구분하고 task() 호출 전략을 잡는다.
5. 에이전트 조율하기 — 순차, 병렬, 계층, 이벤트 기반 패턴으로 여러 전문가가 서로의 결과를 이어받게 만든다.
6. 하네스와 실전 레시피 — permission, AGENTS.md, orchestrator를 하네스로 묶어 운영 가능한 에이전트 시스템으로 마무리한다.

추천 읽기 순서

처음부터 에이전트를 설계하려는 독자라면 1편부터 6편까지 순서대로 읽는 편이 좋다. 앞의 글에서 역할과 권한의 경계를 정해야 뒤의 OMO 조율 패턴이 과한 자동화로 흐르지 않는다.

이미 OpenCode 설정 파일을 어느 정도 다뤄봤다면 3편에서 시작해도 된다. permission, command, skill, tool의 실행 표면을 먼저 정리한 뒤 4편과 5편으로 넘어가면 OMO를 어디에 붙여야 하는지 더 선명하게 보인다.

운영 단계에서 막힌 경우라면 5편과 6편을 먼저 읽어도 된다. 여러 에이전트를 어떻게 나눌지, 실패한 작업을 어디서 멈추고 다시 검증할지 결정하는 데 초점을 맞추면 된다.

각 편에서 확인할 질문

이 안내 글은 전체 지도를 제공하는 역할만 한다. 실제 설정 예시와 연결 흐름은 각 편에서 더 구체적으로 다룬다.

• 1편에서는 “정말 에이전트가 필요한가”를 판단한다. command, skill, AGENTS.md로 충분한 작업을 굳이 에이전트로 만들지 않는 기준을 세운다.
• 2편에서는 커스텀 에이전트 파일을 어떻게 나누고, 모델·권한·출력 형식을 어디에 고정할지 본다.
• 3편에서는 permission, command, skill, tool, MCP가 각각 어떤 층인지 정리하고, 외부 API나 도구를 안전하게 연결하는 방법을 다룬다.
• 4편에서는 OpenCode에서 정의한 역할을 OMO의 task() 호출과 어떻게 연결할지 살핀다.
• 5편에서는 explore, librarian, builder, reviewer 같은 역할이 서로의 결과를 이어받는 조율 패턴을 본다.
• 6편에서는 이 모든 요소를 운영 가능한 하네스로 묶고, 실패했을 때 어디서 멈추고 다시 검증할지 정한다.

자동화보다 먼저 필요한 것

에이전트 시스템의 핵심은 AI에게 더 많은 권한을 주는 데 있지 않다. 어떤 역할은 독립된 에이전트가 되어야 하고, 어떤 작업은 command 하나로 충분하며, 어떤 규칙은 AGENTS.md에 남겨 모든 에이전트가 공유해야 한다. 이 구분이 먼저 서야 OMO의 오케스트레이션도 안전한 협업 구조가 된다.

결국 좋은 에이전트 설계는 똑똑한 모델을 부르는 기술이 아니라, 실패해도 추적 가능하고 성공하면 반복 가능한 작업 환경을 만드는 일에 가깝다. 이 시리즈는 그 환경을 한 겹씩 쌓아 올리는 순서로 읽히도록 구성했다.