백그라운드 병렬 작업: 팀처럼 일하기

학습 목표

✅ 여러 병렬 백그라운드 작업을 시작하여 다른 AI 에이전트가 동시에 작업하도록 설정
✅ 동시성 제한을 구성하여 API 속도 제한과 비용 과지 방지
✅ 완료를 기다리지 않고 백그라운드 작업 결과 가져오기
✅ 작업을 취소하여 리소스 해제

현재 직면한 문제

혼자만 일하고 있나요?

다음 시나리오를 상상해 보세요:

Explore 에이전트가 코드베이스에서 인증 구현을 찾아야 함
동시에 Librarian 에이전트가 베스트 프랙티스를 연구해야 함
그리고 Oracle 에이전트가 아키텍처 설계를 검토해야 함

순차적으로 실행하면 총 소요 시간 = 10분 + 15분 + 8분 = 33분

하지만 병렬로 실행할 수 있다면? 3개 에이전트가 동시에 작업하면 총 소요 시간 = max(10, 15, 8) = 15분, **54%**의 시간을 절약합니다.

문제: 기본적으로 OpenCode는 한 번에 하나의 세션만 처리할 수 있습니다. 병렬 실행을 구현하려면 여러 창을 수동으로 관리하거나 작업 완료를 기다려야 합니다.

해결: oh-my-opencode의 백그라운드 작업 시스템은 여러 AI 에이전트를 동시에 실행하고 백그라운드에서 진행 상황을 추적하여 다른 작업을 계속할 수 있습니다.

사용 시기

백그라운드 작업 시스템을 사용하여 효율성을 높일 수 있는 시나리오:

시나리오	예시	가치
병렬 연구	Explore가 구현 찾기 + Librarian이 문서 찾기	연구를 3배 빠르게 완료
다중 전문가 검토	Oracle이 아키텍처 검토 + Momus가 계획 검증	다각도 피드백을 신속하게 획득
비동기 작업	Git commit 제출 시 동시에 코드 검토 수행	메인 프로세스 차단 방지
리소스 제한	동시성 수 제한으로 API 속도 제한 방지	비용과 안정성 제어

Ultrawork 모드

프롬프트에 ultrawork 또는 ulw를 추가하면 최대 성능 모드가 자동으로 활성화되며, 모든 전문 에이전트와 병렬 백그라운드 작업이 포함됩니다. 수동 구성이 필요 없습니다.

🎒 시작 전 준비

전제 조건

이 튜토리얼을 시작하기 전에 다음을 확인하세요:

oh-my-opencode가 설치됨 ( 설치 튜토리얼 참조)
기본 설정이 완료되었으며 최소 하나의 AI Provider를 사용할 수 있음
Sisyphus 오케스트레이터의 기본 사용법을 이해함 ( Sisyphus 튜토리얼 참조)

핵심 개념

백그라운드 작업 시스템의 작동 원리는 세 가지 핵심 개념으로 요약할 수 있습니다:

1. 병렬 실행

백그라운드 작업 시스템은 여러 AI 에이전트 작업을 동시에 시작할 수 있으며, 각 작업은 독립적인 세션에서 실행됩니다. 이는 다음을 의미합니다:

Explore가 코드 검색
Librarian가 문서 참조
Oracle이 설계 검토

세 가지 작업이 병렬로 실행되며 총 소요 시간은 가장 느린 작업과 같습니다.

2. 동시성 제어

너무 많은 작업을 동시에 시작하여 API 속도 제한이나 비용 과지가 발생하는 것을 방지하기 위해 시스템은 3단계 동시성 제한을 제공합니다:

우선순위: Model > Provider > Default

구성 예시:
modelConcurrency:     claude-opus-4-5 → 2
providerConcurrency:  anthropic → 3
defaultConcurrency:   모두 → 5

규칙:

model 레벨 제한이 지정된 경우 해당 제한 사용
그렇지 않고 provider 레벨 제한이 지정된 경우 해당 제한 사용
그렇지 않으면 기본 제한 사용 (기본값 5)

3. 폴링 메커니즘

시스템은 2초마다 작업 상태를 확인하여 작업 완료 여부를 판단합니다. 완료 조건:

세션 idle (session.idle 이벤트)
안정성 감지: 연속 3회 폴링, 메시지 수가 변하지 않음
TODO 리스트가 비어 있음: 모든 작업이 완료됨

따라해 보세요

1단계: 백그라운드 작업 시작

delegate_task 도구를 사용하여 백그라운드 작업을 시작하세요:

markdown

병렬 백그라운드 작업 시작:

1. Explore가 인증 구현 찾기
2. Librarian가 베스트 프랙티스 연구
3. Oracle이 아키텍처 설계 검토

병렬 실행:

이유 백그라운드 작업의 가장 대표적인 사용 시나리오를 보여줍니다. 3가지 작업이 동시에 진행될 수 있어 시간을 크게 절약합니다.

예상 결과 시스템이 3개 작업 ID를 반환합니다:

Background task launched successfully.

Task ID: bg_abc123
Session ID: sess_xyz789
Description: Explore: 인증 구현 찾기
Agent: explore
Status: pending
...

Background task launched successfully.

Task ID: bg_def456
Session ID: sess_uvwx012
Description: Librarian: 베스트 프랙티스 연구
Agent: librarian
Status: pending
...

작업 상태 설명

pending: 동시성 슬롯 대기 중
running: 실행 중
completed: 완료됨
error: 오류 발생
cancelled: 취소됨

2단계: 작업 상태 확인

background_output 도구를 사용하여 작업 상태를 확인하세요:

markdown

bg_abc123의 상태 확인:

이유 작업이 완료되었는지 아니면 여전히 실행 중인지 파악합니다. 기본적으로 기다리지 않고 즉시 상태를 반환합니다.

예상 결과 작업이 여전히 실행 중인 경우:

## Task Status

| Field | Value |
|--- | ---|
| Task ID | `bg_abc123` |
| Description | Explore: 인증 구현 찾기 |
| Agent | explore |
| Status | **running** |
| Duration | 2m 15s |
| Session ID | `sess_xyz789` |

> **Note**: No need to wait explicitly - system will notify you when this task completes.

## Original Prompt

src/auth 디렉토리下的 인증 구현 찾기, 로그인, 등록, Token 관리 등 포함

작업이 완료된 경우:

Task Result

Task ID: bg_abc123
Description: Explore: 인증 구현 찾기
Duration: 5m 32s
Session ID: sess_xyz789

---

3개의 인증 구현을 찾았습니다:
1. `src/auth/login.ts` - JWT 인증
2. `src/auth/register.ts` - 사용자 등록
3. `src/auth/token.ts` - Token 갱신
...

3단계: 동시성 제어 구성

~/.config/opencode/oh-my-opencode.json을 편집하세요:

jsonc

{
  "$schema": "https://code-yeongyu.github.io/oh-my-opencode/schema.json",

  "background_task": {
    // Provider 레벨 동시성 제한 (권장 설정)
    "providerConcurrency": {
      "anthropic": 3,     // Anthropic 모델 최대 3개 동시
      "openai": 2,         // OpenAI 모델 최대 2개 동시
      "google": 2          // Google 모델 최대 2개 동시
    },

    // Model 레벨 동시성 제한 (최고 우선순위)
    "modelConcurrency": {
      "claude-opus-4-5": 2,    // Opus 4.5 최대 2개 동시
      "gpt-5.2": 2              // GPT 5.2 최대 2개 동시
    },

    // 기본 동시성 제한 (위 설정이 없을 때 사용)
    "defaultConcurrency": 3
  }
}

이유 동시성 제어는 비용 과지를 방지하는 핵심입니다. 제한을 설정하지 않으면 10개의 Opus 4.5 작업을 동시에 시작하여 순간적으로 많은 API 할당량을 소비할 수 있습니다.

권장 설정

대부분의 시나리오에서 다음 설정을 권장합니다:

providerConcurrency.anthropic: 3
providerConcurrency.openai: 2
defaultConcurrency: 5

예상 결과 구성이 적용된 후 백그라운드 작업을 시작할 때:

동시성 제한에 도달하면 작업이 pending 상태로 대기열에 들어감
작업이 완료되면 대기 중인 작업이 자동으로 시작됨

4단계: 작업 취소

background_cancel 도구를 사용하여 작업을 취소하세요:

markdown

모든 백그라운드 작업 취소:

이유 때로는 작업이 멈추거나 더 이상 필요하지 않을 때 리소스를 해제하기 위해 취소할 수 있습니다.

예상 결과

Cancelled 3 background task(s):

| Task ID | Description | Status | Session ID |
|--- | --- | --- | ---|
| `bg_abc123` | Explore: 인증 구현 찾기 | running | `sess_xyz789` |
| `bg_def456` | Librarian: 베스트 프랙티스 연구 | running | `sess_uvwx012` |
| `bg_ghi789` | Oracle: 아키텍처 설계 검토 | pending | (not started) |

## Continue Instructions

To continue a cancelled task, use:

    delegate_task(session_id="<session_id>", prompt="Continue: <your follow-up>")

Continuable sessions:
- `sess_xyz789` (Explore: 인증 구현 찾기)
- `sess_uvwx012` (Librarian: 베스트 프랙티스 연구)

체크포인트 ✅

다음 핵심 사항을 이해했는지 확인하세요:

[ ] 여러 병렬 백그라운드 작업을 시작할 수 있음
[ ] 작업 상태(pending, running, completed)를 이해함
[ ] 합리적인 동시성 제한을 구성함
[ ] 작업 상태를 확인하고 결과를 가져올 수 있음
[ ] 불필요한 작업을 취소할 수 있음

흔한 실수

함정 1: 동시성 제한 설정 잊음

증상: 너무 많은 작업을 시작하여 API 할당량이 순간적으로 소진되거나 속도 제한에 도달함

해결: oh-my-opencode.json에서 providerConcurrency 또는 defaultConcurrency를 구성하세요

함정 2: 결과 확인 폴링이 너무 잦음

증상: 몇 초마다 background_output을 호출하여 작업 상태를 확인, 불필요한 오버헤드 증가

해결: 시스템이 작업 완료를 자동으로 알려줍니다. 실제로 중간 결과가 필요한 경우에만 수동으로 확인하세요

함정 3: 작업 타임아웃

증상: 작업이 30분 후에 자동으로 취소됨

원인: 백그라운드 작업에는 30분의 TTL(타임아웃)이 있음

해결: 장기 작업이 필요한 경우 여러 하위 작업으로 분할하거나 delegate_task(background=false)를 사용하여 포그라운드에서 실행하세요

함정 4: Pending 작업이 계속 시작되지 않음

증상: 작업 상태가 계속 pending이며 running으로 들어가지 않음

원인: 동시성 제한이 가득 차서 사용 가능한 슬롯이 없음

해결:

기존 작업 완료 대기
동시성 제한 구성 증가
불필요한 작업 취소하여 슬롯 해제

수업 요약

백그라운드 작업 시스템을 통해 실제 팀처럼 작업할 수 있으며, 여러 AI 에이전트가 병렬로 작업을 실행합니다:

병렬 작업 시작: delegate_task 도구 사용
동시성 제어: providerConcurrency, modelConcurrency, defaultConcurrency 구성
결과 가져오기: background_output 도구 사용 (시스템이 자동으로 알림)
작업 취소: background_cancel 도구 사용

핵심 규칙:

2초마다 작업 상태 폴링
연속 3회 안정 또는 idle이면 작업 완료
작업 30분 후 자동 타임아웃
우선순위: modelConcurrency > providerConcurrency > defaultConcurrency

다음 수업 예고

다음 수업에서는 **LSP 및 AST-Grep: 코드 리팩토링 도구**를 학습합니다.
학습 내용:
LSP 도구를 사용하여 코드 탐색 및 리팩토링하는 방법
AST-Grep을 사용하여 정확한 패턴 검색 및 교체하는 방법
LSP와 AST-Grep 결합 사용의 베스트 프랙티스

부록: 소스 코드 참조

클릭하여 소스 코드 위치 보기

업데이트 시간: 2026-01-26

기능	파일 경로	줄 수
백그라운드 작업 관리자	`src/features/background-agent/manager.ts`	1-1378
동시성 제어	`src/features/background-agent/concurrency.ts`	1-138
delegate_task 도구	`src/tools/background-task/tools.ts`	51-119
background_output 도구	`src/tools/background-task/tools.ts`	320-384
background_cancel 도구	`src/tools/background-task/tools.ts`	386-514

핵심 상수:

TASK_TTL_MS = 30 * 60 * 1000: 작업 타임아웃 시간 (30분)
MIN_STABILITY_TIME_MS = 10 * 1000: 안정성 감지 시작 시간 (10초)
DEFAULT_STALE_TIMEOUT_MS = 180_000: 기본 타임아웃 시간 (3분)
MIN_IDLE_TIME_MS = 5000: 초기 idle 무시 최소 시간 (5초)

핵심 클래스:

BackgroundManager: 백그라운드 작업 관리자, 시작, 추적, 폴링, 완료 담당
ConcurrencyManager: 동시성 제어 관리자, 3단계 우선순위 구현 (model > provider > default)

핵심 함수:

BackgroundManager.launch(): 백그라운드 작업 시작
BackgroundManager.pollRunningTasks(): 2초마다 작업 상태 폴링 (1182번 줄)
BackgroundManager.tryCompleteTask(): 안전하게 작업 완료, 경쟁 조건 방지 (909번 줄)
ConcurrencyManager.getConcurrencyLimit(): 동시성 제한 가져오기 (24번 줄)
ConcurrencyManager.acquire() / ConcurrencyManager.release(): 동시성 슬롯 획득/해제 (41, 71번 줄)

백그라운드 병렬 작업: 팀처럼 일하기 ​

학습 목표 ​

현재 직면한 문제 ​

사용 시기 ​

🎒 시작 전 준비 ​

핵심 개념 ​

1. 병렬 실행 ​

2. 동시성 제어 ​

3. 폴링 메커니즘 ​

따라해 보세요 ​

1단계: 백그라운드 작업 시작 ​

2단계: 작업 상태 확인 ​

3단계: 동시성 제어 구성 ​

4단계: 작업 취소 ​

체크포인트 ✅ ​

흔한 실수 ​

함정 1: 동시성 제한 설정 잊음 ​

함정 2: 결과 확인 폴링이 너무 잦음 ​

함정 3: 작업 타임아웃 ​

함정 4: Pending 작업이 계속 시작되지 않음 ​

수업 요약 ​

다음 수업 예고 ​

부록: 소스 코드 참조 ​

백그라운드 병렬 작업: 팀처럼 일하기

학습 목표

현재 직면한 문제

사용 시기

🎒 시작 전 준비

핵심 개념

1. 병렬 실행

2. 동시성 제어

3. 폴링 메커니즘

따라해 보세요

1단계: 백그라운드 작업 시작

2단계: 작업 상태 확인

3단계: 동시성 제어 구성

4단계: 작업 취소

체크포인트 ✅

흔한 실수

함정 1: 동시성 제한 설정 잊음

함정 2: 결과 확인 폴링이 너무 잦음

함정 3: 작업 타임아웃

함정 4: Pending 작업이 계속 시작되지 않음

수업 요약

다음 수업 예고

부록: 소스 코드 참조