1편 — 에이전트가 필요한 순간

커스텀 에이전트 파일을 처음 만드는 사람 대부분은 파일을 만들고 나서야 더 적합한 선택지가 있었다는 사실을 알게 된다. command 하나면 충분했던 작업이 거대한 에이전트가 되어 있고, 에이전트 파일이 늘어날수록 어떤 도구를 언제 호출해야 하는지 모호해지기 때문이다. 결과적으로 시스템은 복잡해지고 관리 비용만 늘어난다.

커스텀 에이전트를 설계하기 전에 가장 먼저 던져야 할 질문은 “정말 에이전트가 필요한가”이다. OpenCode 환경에서 에이전트를 새로 만드는 행위는 단순히 프롬프트를 저장하는 이상의 의미를 갖는다. 그것은 독립적인 실행 권한을 부여하고, 특정 도구 세트를 제한하며, 오케스트레이션 과정에서 하나의 명확한 페르소나를 할당하는 작업이다. 단순히 반복되는 프롬프트를 줄이고 싶을 뿐이라면 에이전트보다는 command가 훨씬 효율적이다.

에이전트가 진짜 필요한 순간

에이전트 생성이 정당화되는 시점은 크게 세 가지로 요약할 수 있다. 첫째는 특정 권한만 허용하는 안전한 실행 컨텍스트가 필요할 때다. 예를 들어 코드를 수정하지 않고 읽기만 하면서 리뷰를 수행하는 역할은 permission 설정을 통해 강제할 수 있으며, 이는 프롬프트로 “수정하지 마”라고 지시하는 것보다 훨씬 확실한 구속력을 갖는다.

둘째는 역할의 판단 기준과 출력 형식을 완전히 고정해야 할 때다. 범용 에이전트에게 특정 JSON 스키마나 엄격한 보고서 형식을 요구하면 대화가 길어질수록 형식이 무너질 가능성이 크다. 전용 에이전트를 만들면 해당 시스템 프롬프트를 고정하여 일관된 결과를 얻을 수 있다. 셋째는 OMO와 같은 오케스트레이션 시스템에서 전문 역할 담당자로 호출되어야 할 때다.

이 모든 상황을 관통하는 기준은 **“이 에이전트의 책임을 한 문장으로 정의할 수 있는가”**다. 한 문장으로 설명되지 않는 에이전트는 대체로 너무 많은 일을 떠안고 있다. 그런 에이전트는 시간이 지나면 작은 팀이 아니라 작은 혼돈이 된다. 혼돈도 가끔 생산성처럼 보이지만, 보통은 로그가 길어졌을 뿐이다.

선택지 비교: command, skill, AGENTS.md

에이전트 이전에 검토해야 할 선택지는 세 가지다. command는 사람이 자주 호출하는 절차를 짧은 이름으로 묶는 데 적합하다. skill은 특정 도메인의 판단 기준과 작업 방식을 필요할 때 로드하는 데 적합하다. AGENTS.md는 프로젝트 전체가 공유해야 하는 불변 규칙을 두는 곳이다.

선택지	어울리는 상황	예시
`AGENTS.md`	모든 작업자가 항상 알아야 하는 규칙	테스트 삭제 금지, 토큰 출력 금지, 코드 스타일
`command`	사람이 같은 절차를 반복 호출	`/blog update`, `/commit-review`, `/issue-pr`
`skill`	특정 작업의 판단 기준이 필요	블로그 문체, WCAG 감사 기준, 시리즈 작성 규칙
`agent`	권한·역할·출력 형식이 독립적으로 고정되어야 함	read-only reviewer, migration planner, security auditor

예를 들어 “블로그 글을 업데이트한다”는 작업을 보자. 매번 같은 API를 호출한다면 command가 적합하다. 글의 톤과 excerpt 규칙을 일관되게 유지해야 한다면 skill이 필요하다. 토큰을 출력하지 말라는 규칙은 AGENTS.md에 들어가야 한다. 그런데 이 작업을 독립된 reviewer, writer, publisher로 나누고 각자 다른 권한을 줘야 한다면 그때부터 agent가 의미를 갖는다.

작은 판별 절차

실제로는 아래 순서로 판단하면 실수가 줄어든다.

TXT

1. 모두가 지켜야 하는 규칙인가?        -> AGENTS.md
2. 사람이 반복 호출하는 절차인가?       -> command
3. 특정 도메인 지식이 필요한가?         -> skill
4. 권한과 역할을 독립적으로 묶어야 하나? -> agent
5. 여러 역할을 순서/병렬로 엮어야 하나? -> OMO orchestration

이 절차의 장점은 과한 추상화를 막아준다는 데 있다. 에이전트는 강력하지만 비싸고, command는 단순하지만 추적하기 쉽다. skill은 가볍지만 실행 권한을 직접 제한하지 않는다. AGENTS.md는 넓게 적용되지만 특정 작업의 절차를 대신 수행하지 않는다. 각각이 잘하는 일이 다르기 때문에, 하나로 모든 문제를 해결하려는 순간 구조가 흐려진다.

OpenCode와 OMO의 역할 구분

OpenCode는 물리적 실행 환경에 가깝다. 파일을 읽고, 명령을 실행하고, MCP를 붙이고, agent와 permission을 정의한다. 반면 OMO는 그 위에서 여러 역할을 어떻게 호출하고 이어붙일지 결정하는 오케스트레이션 레이어다. 둘을 섞어 생각하면 “OMO가 있으니 OpenCode 설정은 대충 해도 된다”는 오해가 생기는데, 실제로는 반대다. OpenCode 쪽 경계가 선명해야 OMO가 안전하게 움직일 수 있다.

가령 explore 에이전트가 코드베이스를 찾고, librarian이 외부 문서를 확인하고, builder가 변경을 만들고, reviewer가 read-only로 검토하는 흐름을 만든다고 하자. 이때 각 역할이 어떤 도구를 쓸 수 있는지는 OpenCode의 permission과 tool 설정이 결정한다. OMO는 이들을 언제, 어떤 순서로, 어떤 컨텍스트를 넘기며 호출할지를 맡는다.

설계 시작하기

첫 번째 파일을 만들기 전에 아래 네 가지를 적어두면 이후 글에서 다룰 설정이 훨씬 자연스럽게 이어진다.

이 역할은 무엇을 절대 하면 안 되는가?
이 역할이 반드시 사용할 도구는 무엇인가?
이 역할의 결과는 누가 검증하는가?
실패했을 때 다시 실행해도 안전한가?

좋은 에이전트 설계는 “무엇을 할 수 있는가”보다 “무엇을 하지 못하게 할 것인가”에서 시작한다. 이 경계가 정리되면 다음 단계인 에이전트 파일 작성은 훨씬 덜 무섭다. 사실 무서운 것은 YAML이 아니라, YAML 뒤에서 조용히 열려 있는 권한이다.