OpenCode 및 기타 AI 어시스턴트: 파이프라인 실행 3가지 방법

학습 후 할 수 있는 것

✅ OpenCode로 Factory 파이프라인 시작 및 실행
✅ Cursor로 파이프라인 실행
✅ 다양한 AI 어시스턴트의 명령어 형식 차이점 이해
✅ 사용 시나리오에 따라 적합한 AI 어시스턴트 선택

현재의 곤경

Factory 프로젝트를 초기화했지만 Claude Code 외에 다른 AI 어시스턴트로 파이프라인을 실행하는 방법을 모릅니다. OpenCode와 Cursor는 주류 AI 프로그래밍 어시스턴트입니다. Factory 파이프라인을 실행할 수 있을까요? 시작 방법과 명령어 형식은 어떤 차이가 있을까요?

이 기법을 사용하는 시기

AI 어시스턴트	권장 사용 시나리오	장점
Claude Code	가장 안정적인 Agent 모드 경험 필요	네이티브 Agent 모드 지원, 명확한 명령어 형식
OpenCode	멀티플랫폼 사용자, 유연한 AI 도구 필요	크로스플랫폼, Agent 모드 지원
Cursor	VS Code 파워유저, VS Code 생태계에 익숙	높은 통합도, 원활한 전환

핵심 원칙

모든 AI 어시스턴트의 실행 로직은 완전히 동일합니다: Agent 정의 읽기 → 파이프라인 실행 → 산출물 생성. 차이점은 시작 방법과 명령어 형식뿐입니다.

🎒 시작하기 전 준비사항

시작하기 전에 다음을 확인하세요:

✅ 설치 및 설정 완료
✅ factory init로 프로젝트 초기화 완료
✅ OpenCode 또는 Cursor 설치(최소 하나)

핵심 개념: AI 어시스턴트를 파이프라인 실행 엔진으로

AI 어시스턴트는 파이프라인의 실행 엔진이며, Agent 정의를 해석하고 산출물을 생성하는 역할을 담당합니다. 핵심 워크플로우는 다섯 단계로 구성됩니다: 먼저 .factory/pipeline.yaml을 읽어 단계 순서를 파악하고, 그 다음 스케줄러를 로드하여 실행 제약 조건과 권한 검사 규칙을 파악한 다음, 현재 상태에 따라 해당 Agent 정의 파일을 로드하고, 그 후 Agent 명령어를 실행하여 산출물을 생성하고 종료 조건을 검증하며, 마지막으로 사용자 확인을 기다린 후 다음 단계를 계속 진행합니다.

중요: AI 어시스턴트는 Agent 모드를 지원해야 함

Factory 파이프라인은 AI 어시스턴트가 복잡한 Markdown 명령어를 이해하고 실행할 수 있어야 합니다. 모든 지원되는 AI 어시스턴트(Claude Code, OpenCode, Cursor)는 Agent 모드 기능을 보유하고 있습니다.

따라 해보기

1단계: OpenCode로 파이프라인 실행

자동 시작(권장)

전역에 OpenCode CLI가 설치된 경우:

bash

# 프로젝트 루트 디렉터리에서 실행
factory init

factory init은 자동으로 OpenCode를 감지하고 시작하며, 다음 프롬프트를 전달합니다:

text

.factory/pipeline.yaml과 .factory/agents/orchestrator.checkpoint.md를 읽고, 파이프라인을 시작하여 제품 아이디어 조각을 실행 가능한 애플리케이션으로 전환해 주세요. 다음에 아이디어 조각을 입력하겠습니다. 참고: Agent가 참조하는 skills/ 및 policies/ 파일은 먼저 .factory/ 디렉터리에서 찾고, 없으면 루트 디렉터리에서 찾습니다.

확인해야 할 사항:

터미널에 Starting OpenCode... 표시
OpenCode 창 자동 열림
프롬프트가 입력 상자에 자동 붙여넣기됨

수동 시작

자동 시작이 실패하는 경우 수동으로 작업할 수 있습니다:

OpenCode 앱 열기
Factory 프로젝트 디렉터리 열기
다음 프롬프트를 OpenCode 입력 상자에 복사:

text

.factory/pipeline.yaml과 .factory/agents/orchestrator.checkpoint.md를 읽고, 파이프라인을 시작하여 제품 아이디어 조각을 실행 가능한 애플리케이션으로 전환해 주세요. 다음에 아이디어 조각을 입력하겠습니다. 참고: Agent가 참조하는 skills/ 및 policies/ 파일은 먼저 .factory/ 디렉터리에서 찾고, 없으면 루트 디렉터리에서 찾습니다.

Enter로 실행

파이프라인 계속 실행

파이프라인이 특정 단계까지 실행된 경우 factory run 명령어로 계속할 수 있습니다:

bash

# 현재 상태 확인 및 명령어 생성
factory run

# 또는 지정된 단계부터 시작
factory run prd

OpenCode는 Claude Code와 유사한 명령어를 표시합니다:

🤖 AI 어시스턴트 명령어:
────────────────────────────

This is an Agent Factory project. Please:

1. Read .factory/pipeline.yaml
2. Read .factory/agents/orchestrator.checkpoint.md
3. Read .factory/config.yaml
4. Execute pipeline from: bootstrap

Note: Check .factory/ first for skills/policies/ references, then root directory.

2단계: Cursor로 파이프라인 실행

Cursor는 VS Code 기반의 AI 프로그래밍 어시스턴트로, Composer 기능을 사용하여 Factory 파이프라인을 실행합니다.

Cursor 감지

Factory CLI는 자동으로 Cursor 환경을 감지합니다(CURSOR 또는 CURSOR_API_KEY 환경 변수를 통해).

Composer 사용하여 실행

Cursor에서 Factory 프로젝트 디렉터리 열기
factory run 명령어 실행:

bash

factory run

터미널에 Cursor 전용 명령어가 표시됩니다:

🤖 Cursor 명령어:
────────────────────────────

This is an Agent Factory project. Use Cursor Composer to:

1. @ReadFile .factory/pipeline.yaml
2. @ReadFile .factory/agents/orchestrator.checkpoint.md
3. @ReadFile .factory/config.yaml
   (Note: Check .factory/ first for skills/policies/ references)
4. Execute pipeline from: bootstrap

이러한 명령어를 Cursor Composer 입력 상자에 복사
실행

체크포인트 ✅

Cursor Composer 창이 열려 있음
파이프라인이 실행되며 현재 단계 표시(예: Running: bootstrap)
산출물 생성(예: input/idea.md)

3단계: 다양한 AI 어시스턴트의 명령어 형식 이해

실행 로직은 동일하지만, 다양한 AI 어시스턴트의 명령어 형식에는 미세한 차이가 있습니다:

작업	Claude Code 형식	Cursor 형식	기타 AI 어시스턴트(OpenCode 등)
파일 읽기	`Read(filePath)`	`@ReadFile filePath`	`Read filePath`
여러 파일 읽기	`Read(file1)`, `Read(file2)`	`@ReadFile file1`, `@ReadFile file2`	-
파일 쓰기	`Write(filePath, content)`	직접 쓰기	-
Bash 명령 실행	`Bash(command)`	직접 실행	-

Factory CLI 자동 처리

factory run을 실행할 때, CLI는 현재 AI 어시스턴트 유형을 자동으로 감지하고 해당 명령어 형식을 생성합니다. 수동으로 변환할 필요 없이 복사하여 붙여넣기만 하면 됩니다.

4단계: 지정된 단계에서 계속 실행

파이프라인이 앞의 단계들을 완료한 경우, 임의의 단계에서 계속할 수 있습니다:

bash

# UI 단계부터 시작
factory run ui

# Tech 단계부터 시작
factory run tech

# Code 단계부터 시작
factory run code

Factory CLI는 현재 파이프라인 상태를 표시합니다:

Pipeline Status:
────────────────────
Project: my-app
Status: Running
Current Stage: ui
Completed: bootstrap, prd

Available stages:
  ✓ bootstrap
  ✓ prd
  → ui
  ○ tech
  ○ code
  ○ validation
  ○ preview

5단계: factory continue로 토큰 절약(Claude Code 전용)

주의

factory continue 명령어는 현재 Claude Code에서만 지원됩니다. OpenCode 또는 Cursor를 사용하는 경우, 직접 factory run을 사용하여 새 세션을 수동으로 시작하세요.

토큰을 절약하고 컨텍스트 누적을 피하기 위해, Claude Code는 세션 분할 실행을 지원합니다:

bash

# 새 터미널 창을 열고 실행
factory continue

실행 효과:

현재 상태 읽기(.factory/state.json)
새 Claude Code 창 자동 시작
이전에 일시 중지한 단계에서 계속

적용 시나리오:

Bootstrap → PRD 완료 후, 새 세션에서 UI 단계 실행
UI → Tech 완료 후, 새 세션에서 Code 단계 실행
긴 대화 기록을 피해야 하는 모든 시나리오

문제 해결 팁

문제 1: OpenCode 시작 실패

증상: factory init 실행 후, OpenCode가 자동으로 시작되지 않습니다.

원인:

OpenCode CLI가 PATH에 추가되지 않음
OpenCode가 설치되지 않음

해결책:

bash

# OpenCode 수동 시작
# Windows
%LOCALAPPDATA%\Programs\OpenCode\OpenCode.exe

# macOS
/Applications/OpenCode.app

# Linux(우선 순위: 먼저 /usr/bin/opencode, 다음 /usr/local/bin/opencode)
/usr/bin/opencode
# 위 경로가 없으면 시도:
/usr/local/bin/opencode

그런 다음 프롬프트를 수동으로 복사하여 OpenCode에 붙여넣으세요.

문제 2: Cursor Composer가 명령어를 인식하지 못함

증상: factory run에서 생성한 명령어를 Cursor Composer에 복사했지만 응답이 없습니다.

원인:

Cursor Composer의 @ReadFile 구문이 정확히 일치해야 함
파일 경로가 올바르지 않을 수 있음

해결책:

@ReadFile을 Read 또는 ReadFile 대신 사용하는지 확인
파일 경로가 프로젝트 루트 디렉터리 기준인지 확인
절대 경로 사용 시도

예시:

text

# ✅ 올바름
@ReadFile .factory/pipeline.yaml

# ❌ 잘못됨
Read(.factory/pipeline.yaml)
@readfile .factory/pipeline.yaml

문제 3: Agent가 스킬 파일 참조 실패

증상: Agent가 skills/bootstrap/skill.md 또는 policies/failure.policy.md를 찾을 수 없다고 오류를 보고합니다.

원인:

Agent 조회 경로 순서 오류
프로젝트에 .factory/와 루트 디렉터리 모두 skills/, policies/가 존재

해결책: 모든 AI 어시스턴트는 동일한 조회 순서를 따릅니다:

우선 조회 .factory/skills/ 및 .factory/policies/
루트 디렉터리로 폴백 skills/ 및 policies/

확인 사항:

Factory 프로젝트 초기화 후, skills/ 및 policies/가 .factory/에 복사되었는지 확인
Agent 정의에 다음이 명시되었는지 확인: ".factory/ 디렉터리를 먼저 찾고, 없으면 루트 디렉터리에서 찾기"

문제 4: 파이프라인 상태 비동기화

증상: AI 어시스턴트가 특정 단계 완료를 표시했지만, factory run은 여전히 running 상태를 표시합니다.

원인:

AI 어시스턴트가 state.json을 수동으로 업데이트했지만 CLI 상태와 일치하지 않음
여러 창이 동시에 상태 파일을 수정했을 수 있음

해결책:

bash

# 프로젝트 상태 재설정
factory reset

# 파이프라인 재실행
factory run

모범 사례

여러 AI 어시스턴트 창에서 동시에 동일한 프로젝트의 파이프라인을 실행하지 마세요. 상태 충돌 및 산출물 덮어쓰기가 발생할 수 있습니다.

이번 강의 요약

이번 강의에서는 OpenCode, Cursor 등 AI 어시스턴트를 사용하여 Factory 파이프라인을 실행하는 방법을 배웠습니다:

핵심 요점:

✅ Factory는 다양한 AI 어시스턴트 지원(Claude Code, OpenCode, Cursor)
✅ factory init이 사용 가능한 AI 어시스턴트를 자동 감지 및 시작
✅ factory run이 현재 AI 어시스턴트에 따라 해당 명령어 생성
✅ factory continue(Claude Code 전용)이 세션 분할 실행을 지원하여 토큰 절약
✅ 모든 AI 어시스턴트가 동일한 실행 로직을 따르며 명령어 형식만 다름

주요 파일:

.factory/pipeline.yaml — 파이프라인 정의
.factory/agents/orchestrator.checkpoint.md — 스케줄러 규칙
.factory/state.json — 파이프라인 상태

선택 제안:

Claude Code: 가장 안정적인 Agent 모드 경험(권장)
OpenCode: 크로스플랫폼 사용자를 위한 최선의 선택
Cursor: VS Code 파워유저를 위한 최선의 선택

다음 강의 예고

다음 강의에서는 **필수 플러그인 설치**를 배웁니다.
배울 내용:
superpowers 및 ui-ux-pro-max 플러그인 설치 필요 이유
플러그인 자동 또는 수동 설치 방법
플러그인 설치 실패 시 처리 방법

부록: 소스 코드 참조

소스 코드 위치 보기

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

기능	파일 경로	라인 번호
OpenCode 시작	`cli/commands/init.js`	152-215
Claude Code 시작	`cli/commands/init.js`	119-147
AI 어시스턴트 감지	`cli/commands/run.js`	105-124
명령어 생성	`cli/commands/run.js`	130-183

주요 상수:

CLAUDE_CODE / ANTHROPIC_API_KEY: Claude Code 환경 변수 감지(run.js:109-110)
CURSOR / CURSOR_API_KEY: Cursor 환경 변수 감지(run.js:114-115)
OPENCODE / OPENCODE_VERSION: OpenCode 환경 변수 감지(run.js:119-120)

주요 함수:

launchClaudeCode(projectDir): Claude Code 시작 및 프롬프트 전달(init.js:119-147)
launchOpenCode(projectDir): OpenCode 시작, CLI 및 실행 파일 두 가지 방식 지원(init.js:152-215)
detectAIAssistant(): 환경 변수를 통해 현재 AI 어시스턴트 유형 감지(run.js:105-124)
getAssistantInstructions(assistant, ...): AI 어시스턴트 유형에 따라 해당 명령어 생성(run.js:130-183)

OpenCode 및 기타 AI 어시스턴트: 파이프라인 실행 3가지 방법 ​

학습 후 할 수 있는 것 ​

현재의 곤경 ​

이 기법을 사용하는 시기 ​

🎒 시작하기 전 준비사항 ​

핵심 개념: AI 어시스턴트를 파이프라인 실행 엔진으로 ​

따라 해보기 ​

1단계: OpenCode로 파이프라인 실행 ​

자동 시작(권장) ​

수동 시작 ​

파이프라인 계속 실행 ​

2단계: Cursor로 파이프라인 실행 ​

Cursor 감지 ​

Composer 사용하여 실행 ​

체크포인트 ✅ ​

3단계: 다양한 AI 어시스턴트의 명령어 형식 이해 ​

4단계: 지정된 단계에서 계속 실행 ​

5단계: factory continue로 토큰 절약(Claude Code 전용) ​

문제 해결 팁 ​

문제 1: OpenCode 시작 실패 ​

문제 2: Cursor Composer가 명령어를 인식하지 못함 ​

문제 3: Agent가 스킬 파일 참조 실패 ​

문제 4: 파이프라인 상태 비동기화 ​

이번 강의 요약 ​

다음 강의 예고 ​

부록: 소스 코드 참조 ​

OpenCode 및 기타 AI 어시스턴트: 파이프라인 실행 3가지 방법

학습 후 할 수 있는 것

현재의 곤경

이 기법을 사용하는 시기

🎒 시작하기 전 준비사항

핵심 개념: AI 어시스턴트를 파이프라인 실행 엔진으로

따라 해보기

1단계: OpenCode로 파이프라인 실행

자동 시작(권장)

수동 시작

파이프라인 계속 실행

2단계: Cursor로 파이프라인 실행

Cursor 감지

Composer 사용하여 실행

체크포인트 ✅

3단계: 다양한 AI 어시스턴트의 명령어 형식 이해

4단계: 지정된 단계에서 계속 실행

5단계: factory continue로 토큰 절약(Claude Code 전용)

문제 해결 팁

문제 1: OpenCode 시작 실패

문제 2: Cursor Composer가 명령어를 인식하지 못함

문제 3: Agent가 스킬 파일 참조 실패

문제 4: 파이프라인 상태 비동기화

이번 강의 요약

다음 강의 예고

부록: 소스 코드 참조