OpenCode 멀티에이전트 실전 가이드: ultrawork 완전 활용법
OpenCodeと Oh My OpenCode를 설치하고 설정까지 완료했다면, 이제 본격적으로
“여러 AI가 동시에 일하는 개발환경”을 경험해 볼 차례입니다.
하지만 초급 개발자가 처음 multi-agent 기능을 접하면 이런 고민이 생깁니다:
- ultrawork가 정확히 어떤 기능인지?
- 여러 에이전트가 동시에 움직이면 무엇이 좋은지?
- 실제로 어떤 작업이 빨라지는지?
- 대화는 어떻게 구성해야 하는지?
그래서 이번 글에서는
“하나의 작업을 여럿이 나눠서 처리하는 흐름”을 예제로 보여주며
OpenCode의 multi-agent 개발 방식을 쉽게 이해할 수 있도록 구성했습니다.
1. ultrawork란 무엇인가?
ultrawork는 OpenCode에 있는 특수 명령 기반 작업 모드です。
한 문장 요약하자면
여러 AI coding agent 가 서로 역할을 나눠 동시에 작업하는 모드.
일반적인 AI 코딩 도구는
“질문 → 답변 → 수정 → 반영”
이라는 직선형 흐름을 갖습니다.
반면 ultrawork는
- 문제를 분석하는 에이전트
- 코드를 작성하는 에이전트
- 문서를 작성하는 에이전트
- 테스트를 만드는 에이전트
- 전체 구조를 검토하는 에이전트
이렇게 여러 AI가 한 작업을 나눠 맡고,
최종적으로 결과를 합쳐서 제안하는 구조입니다.
2. ultrawork를 실행하는 기본 문법
TUI 내부에서 다음 키워드를 입력하기만 하면 됩니다:
ultrawork또는 더 자연스럽게
이 작업을 ultrawork 모드로 진행해줘.또는 짧게
ulw그러면 OpenCode는 다음을 자동 실행합니다:
- task 분해
- 여러 agent에게 병렬 작업 할당
- 결과 요약
- 수정 제안
- 파일 변경 제안
초급 개발자라도 이 기능을 쓰면 “혼자 일하지 않는 느낌”이 강하게 듭니다.
3. 예시 시나리오 1 — 기존 코드 리팩터링을 팀처럼 수행하기
아래는 한 파일이 너무 복잡할 때 실제 사용할 수 있는 ultra 패턴입니다.
STEP 1 — 문제 제시
이 파일(src/user/service.js)이 너무 복잡해.
ultrawork 모드로 구조 리팩터링 방향을 제안해줘.STEP 2 — agent 역할 분담(자동)
- @oracle → 최적 구조 제안
- @explore → 의존성 분석
- @document → 변경 요약
- @frontend (필요 시) → UI 영향 분석
STEP 3 — 결과 제시
자동으로 다음이 생성됩니다.
- 리팩터링 설계안
- 파일 분리 기준
- 폴더 구조 추천
- 테스트 변경사항
- 마이그레이션 주의점
STEP 4 — “구현 시작” 요청
좋아. 그럼 service.js를 3개 파일로 나누는 초안을 작성해줘.4. 예시 시나리오 2 — 새 기능을 빠르게 개발하고 테스트까지 생성
예: 회원가입 기능 추가
새로운 signup 기능이 필요해.
ultrawork 모드로 API 구조, validation, DB schema, 테스트까지 함께 설계해줘.그러면
- @oracle → 전체 API 흐름 설계
- @frontend → 필요한 UI 구조 제안
- @document → API 문서 작성
- @explore → 기존 비슷한 기능 참조
- @test-agent(있다면) → 테스트 코드 자동 생성
이후
방금 결과를 기반으로 실제 signup API 파일 초안을 작성해줘.초급 개발자도 “하루 걸릴 작업을 몇 분 단위로 압축”할 수 있게 됩니다.
5. 예시 시나리오 3 — 대규모 파일 스캔 및 개선 요청
예: 프로젝트 전체에서 반복되는 패턴 제거하기
src 전체를 ultrawork 모드로 검사해서,
중복된 로직이나 불필요한 코드 패턴을 찾아줘.그러면
- @explore → 전체 스캔
- @oracle → 개선 방향 제안
- @document → 변경 요약
- @refactor-agent(사용자가 추가했다면) → 리팩터링 초안
결과는 다음 형태가 됩니다.
- 문제 목록(파일 경로 포함)
- 개선 방향
- 적용 난이도
- 예상 위험성
- 자동 생성된 패치 예시
6. multi-agent를 잘 쓰는 대화 패턴 5가지
완전 초급자에게 추천하는 패턴만 정리해보면 다음과 같습니다.
✔ 패턴 1 — “분석 먼저”
문제를 먼저 분석해줘.✔ 패턴 2 — “역할 분담 요청”
이 작업을 여러 에이전트가 나누어 진행하도록 해줘.✔ 패턴 3 — “초안 작성”
좋아. 그럼 초안을 작성해줘.✔ 패턴 4 — “부분 수정”
3번째 제안만 반영해서 다시 정리해줘.✔ 패턴 5 — “파일에 적용”
이 패치를 실제 파일에 적용해줘.세부 조정 없이 자연어로 의도를 말하기만 해도
에이전트가 상황을 자동으로 읽고 처리합니다.
7. 초급 개발자를 위한 ultrawork 사용 전략
✔ 1) 작은 작업부터 병렬화
예: “유틸 함수 리팩터링”
✔ 2) 문서화와 테스트까지 자동으로 포함
항상 다음 문장을 함께 넣어보세요:
테스트 코드와 문서화도 함께 생성해줘.✔ 3) 프로젝트 규칙과 AGENTS.md를 활용해 품질 유지
규칙 기반 자동 주입은 multi-agent 환경에서 특히 중요합니다.
✔ 4) 완성된 결과는 반드시 리뷰
“AI가 자동으로 만든 코드 = 바로 배포”는 절대 금지입니다.
整理する
今回の記事では OpenCode의 ultrawork 기능과 multi-agent workflow를 실제 개발 흐름 안에서 사용하는 방법을 초급자 눈높이로 정리했습니다.
핵심은 단순합니다.
작업을 분해하고, 여러 에이전트가 동시에 처리하도록 맡긴 뒤, 최종 결과만 검토한다.
이 방식에 익숙해지면
혼자 개발하는 상황에서도 “팀 단위 속도”를 낼 수 있게 됩니다.
다음 글(7편)에서는
OpenCode를 사용해 Django 프로젝트를 실제로 구축하는 실습 편を扱います。
