AI가 코드를 건드리기 전에 계획을 먼저 보여주게 만드는 OpenCode Plan/Build 모드
"이 함수만 수정해줘"라고 했는데, 에이전트가 관련 없는 파일까지 조용히 바꿔놓은 걸 나중에야 알게 된 적 있으신가요? 저도 그런 경험을 했습니다. 멀쩡히 돌아가던 인증 로직이 배포 직전에 슬쩍 바뀌어 있는 걸 발견했을 때, 그때부터 AI 에이전트의 "실행 범위"에 꽤 민감해졌죠.
사실 이게 개인만의 문제가 아닙니다. AI 코딩 도구가 보편화되면서 가장 많이 듣는 불만 중 하나가 "내가 원하지 않은 것까지 바꿔버렸다"입니다. 에이전트가 무엇을 하려는지 사전에 알 방법이 없다는 게 핵심 문제죠. 계획 없이 바로 실행에 들어가니, 잘못된 방향으로 파일 20개를 수정하고 나서야 뭔가 틀렸다는 걸 알게 됩니다.
OpenCode는 이 문제를 Plan 모드와 Build 모드를 명확히 분리해서, AI가 코드를 건드리기 전에 의도를 먼저 보여주도록 강제하는 설계로 풀어냅니다. 터미널 사용에 익숙하고 AI 코딩 도구를 이미 써본 개발자라면, 이 두 모드의 차이가 복잡한 작업에서 얼마나 큰 체감 차이를 만드는지 바로 알게 됩니다. Stack Overflow Developer Survey 2025 기준 전체 개발자의 85% 이상이 AI 도구를 정기적으로 사용하고 새로 작성되는 코드의 약 46%가 AI 생성이라는 현실에서, "AI를 어떻게 안전하게 신뢰할 수 있는가"는 점점 더 중요한 질문이 되고 있습니다.
핵심 개념
Plan 모드: 아키텍트처럼 생각하는 단계
Plan 모드는 읽기 전용 분석 단계입니다. 이 모드에서 OpenCode는 파일을 탐색하고 코드베이스를 이해하고 단계별 구현 계획을 제시하지만, 실제로 파일을 쓰거나 명령을 실행하지 않습니다. 내부적으로는 파일 쓰기와 셸 실행에 해당하는 툴 콜 자체가 비활성화되는 방식으로 동작합니다. 시스템 프롬프트 레벨에서 AI의 행동을 제한하는 게 아니라, 사용할 수 있는 도구 목록 자체가 달라지는 구조입니다. 그래서 Plan 모드에서 "이 파일 삭제해줘"라고 해도 OpenCode는 물리적으로 실행할 수가 없습니다.
마치 설계 회의 테이블에서 화이트보드에 그림만 그리는 것처럼, 손은 키보드에서 떼고 머리만 쓰는 시간이라고 보시면 됩니다. 저는 복잡한 기능을 붙이기 전에 항상 Plan 모드에서 먼저 "영향받는 파일이 뭔지" 확인하는 습관이 생겼는데, 예상치 못한 파일이 목록에 포함되어 있을 때 바로 방향을 바로잡을 수 있어서 꽤 유용합니다.
Plan 모드의 핵심: 파일 쓰기·삭제·명령 실행에 해당하는 도구가 비활성화된 읽기 전용 단계입니다. AI가 "아키텍트" 역할로 코드베이스를 탐색하고 구현 전략을 먼저 제안합니다.
Tab 키 하나로 Plan 모드와 Build 모드를 오갈 수 있습니다. Plan 모드에서 복잡한 기능을 요청하면 OpenCode는 현재 코드 구조를 분석한 뒤 영향받을 파일 목록과 변경 순서를 먼저 보여줍니다. 이 시점에 "이 부분은 내가 원하는 방향이 아닌데"라고 피드백을 주거나, 계획을 조정하거나, 아예 다른 접근을 요청할 수 있습니다. 코드는 아직 단 한 줄도 바뀌지 않은 상태에서요.
Build 모드: 시니어 엔지니어처럼 실행하는 단계
Build 모드가 기본 모드입니다. 파일 읽기/쓰기/삭제, 셸 명령 실행 등 모든 도구에 완전한 접근 권한을 가진 "시니어 엔지니어" 역할입니다. Plan 모드에서 계획을 충분히 검토한 뒤 다시 Tab을 눌러 Build 모드로 전환하면, OpenCode는 논의된 계획을 실제 코드로 구현합니다.
OpenCode 설치는 공식 GitHub 저장소 기준으로 npm 또는 pnpm을 통해 가능합니다.
# pnpm 환경
pnpm add -g opencode-ai
# npm 환경
npm install -g opencode-ai
# 프로젝트 디렉토리에서 실행
cd my-project
opencode
# 터미널 UI가 실행되면 Tab 키로 Plan/Build 모드 전환 (기본값은 Build 모드)의도-실행 간 의도적 단절
두 모드 사이의 핵심 가치는 **의도적 단절(deliberate pause)**입니다. 단순히 "계획 세우고 실행"이 아니라, AI가 무엇을 하려는지 먼저 명시적으로 표현하게 강제하는 구조입니다.
솔직히 처음엔 "번거롭게 왜 두 단계로 나누지?"라고 생각했습니다. 그냥 바로 구현해주면 되지 않나 싶었죠. 그런데 복잡한 기능을 다루다 보면 이게 꽤 중요해집니다. AI가 "A → B → C 순서로 바꾸겠다"고 먼저 말해줄 때, 개발자는 그 계획이 자신의 의도와 맞는지 확인할 수 있습니다. 계획 없이 바로 실행해버리면 잘못된 방향으로 수십 개 파일을 수정한 뒤에야 뭔가 틀렸다는 걸 알게 되고요.
OpenCode는 특정 LLM 제공사에 종속되지 않는 벤더 중립적 도구이기도 합니다. OpenAI GPT, Google Gemini, Ollama(로컬 실행) 등 75개 이상의 프로바이더를 Models.dev를 통해 연결할 수 있습니다. 참고로 2026년 1월에 Anthropic이 Claude 모델을 OpenCode에서 직접 사용하는 것을 제한하는 조치를 취했는데, OpenCode가 API 이용 정책과 충돌하는 방식으로 모델에 접근하고 있다는 게 이유였습니다. 현재는 OpenRouter 같은 프록시 프로바이더를 통해 Claude를 우회 연결하는 방법을 공식적으로 안내하고 있습니다.
실전 적용
예시 1: 복잡한 기능 추가 — OAuth2 소셜 로그인 구현
실무에서 자주 맞닥뜨리는 상황입니다. 기존 인증 시스템에 소셜 로그인을 붙이는 작업인데, 미들웨어·DB 스키마·세션 처리가 얽혀 있어서 어디서부터 건드려야 할지 감이 안 올 때가 있습니다.
# Plan 모드로 진입 (Tab 키)
> 현재 JWT 기반 인증 시스템에 GitHub OAuth2 소셜 로그인을 추가하고 싶어.
passport.js를 쓰면 좋겠는데, 기존 미들웨어와 충돌 없이 통합하는 방법을 분석해줘.Plan 모드에서 OpenCode가 응답하는 내용은 대략 이런 형태입니다.
✦ 현재 auth 미들웨어 구조 분석 완료
✦ 영향받는 파일:
- src/middleware/auth.ts (passport 전략 추가)
- src/routes/auth.ts (OAuth 콜백 라우트 신규)
- prisma/schema.prisma (User 테이블에 provider 컬럼 추가)
- .env (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET 필요)
✦ 구현 순서:
1. passport-github2 패키지 설치
2. DB 스키마 마이그레이션
3. passport 전략 설정
4. 콜백 라우트 구현
5. 기존 JWT 미들웨어와 연결이 시점에서 "3번과 4번 순서를 바꿔줘" 또는 "DB 스키마는 내가 직접 할 테니 나머지만 해줘" 같은 조정이 가능합니다. 파일은 아직 하나도 변경되지 않았으니까요.
| 구현 단계 | 변경 대상 파일 | 예상 복잡도 |
|---|---|---|
| passport-github2 설치 | package.json | 낮음 |
| DB 스키마 마이그레이션 | prisma/schema.prisma | 중간 |
| passport 전략 설정 | src/middleware/auth.ts | 높음 |
| 콜백 라우트 구현 | src/routes/auth.ts | 중간 |
| JWT 미들웨어 연결 | src/middleware/auth.ts | 높음 |
계획이 마음에 들면 Tab으로 Build 모드로 전환해 구현을 시작하면 됩니다.
# 계획 검토 후 Tab 키로 Build 모드 전환
> 계획대로 진행해줘. DB 스키마 변경도 포함해서.
# Build 모드에서 실제 파일 수정 시작
# 각 단계마다 어떤 파일을 어떻게 바꾸는지 터미널에 표시됨예시 2: 레거시 코드 분석 및 리팩토링 전략 수립
레거시 코드베이스를 리팩토링할 때 Plan 모드가 특히 빛납니다. 방대한 코드를 실제로 건드리지 않고 탐색할 수 있으니, "이 코드가 어디에 얼마나 영향을 미치는지" 파악하는 데 안성맞춤입니다.
# Plan 모드에서
> src/services/ 디렉토리 전체를 분석해서,
God Object 패턴이 있는 서비스 파일을 찾고
분리 전략을 제안해줘.✦ UserService.ts — 2,847 lines, 14개 의존성 (분리 권장)
✦ 분리 제안:
- UserAuthService (인증 관련 메서드 8개)
- UserProfileService (프로필 관련 메서드 12개)
- UserNotificationService (알림 관련 메서드 6개)
✦ 예상 영향 파일: 23개
✦ 권장 작업 순서: 인증 → 프로필 → 알림 (의존성 역방향)OpenCode는 코드를 읽고 분석하지만 수정하지 않습니다. 각 서비스의 의존성 그래프, 분리 기준, 예상 작업량을 먼저 확인한 뒤에 Build 모드로 진입할 수 있습니다. Plan 모드에서는 디자인 다이어그램이나 UI 스크린샷을 드래그 앤 드롭으로 넣어 "이 컴포넌트 구조처럼 분리하고 싶은데 현재 코드에서 어떻게 접근하면 될까?" 같은 시각적 목업 기반 논의도 가능합니다.
예시 3: 멀티 세션 병렬 개발
v1.3.0부터 지원되는 멀티 세션은 프론트엔드와 백엔드를 동시에 개발할 때 유용합니다. 하나의 세션이 백엔드 API 응답 구조를 바꾸는 동안 다른 세션이 그 응답을 소비하는 프론트엔드를 함께 개발하면, 변경 범위가 겹쳐 충돌이 생길 수 있습니다. 두 세션 각각을 Plan 모드로 먼저 시작해 "내가 건드릴 파일 목록"을 확인하고 겹치는 파일이 없는지 체크한 뒤 Build 모드로 전환하면, 이런 충돌을 사전에 잡을 수 있습니다.
# 터미널 창 1: 백엔드 API 작업
cd my-project
opencode
# → Plan 모드에서 API 변경 범위 먼저 확인 후 Build 전환
# 터미널 창 2: 프론트엔드 컴포넌트 작업
cd my-project
opencode
# → Plan 모드에서 프론트엔드 변경 범위 확인
# → 백엔드 세션과 파일 중복 없으면 Build 전환세션 명명 등 멀티 세션 관련 CLI 옵션은 공식 문서에서 최신 구문을 확인하시는 것을 권장합니다.
장단점 분석
장점
| 항목 | 내용 |
|---|---|
| 안전성 | Plan 모드의 툴 비활성화로 의도치 않은 파일 변경을 구조적으로 차단 |
| 투명성 | 코드 수정 전 AI의 실행 계획을 명확히 검토 가능 |
| 모델 유연성 | 75개 이상의 LLM 프로바이더 지원, 특정 벤더 종속 탈피 |
| 비용 | 도구 자체는 무료 (API 비용만 발생), 로컬 모델 사용 시 비용 제로 |
| 확장성 | LSP, MCP 프로토콜 지원으로 다양한 도구와 연동 가능 |
| 오픈소스 | 코드 완전 공개, 커뮤니티 기여 및 자체 수정 가능 |
LSP(Language Server Protocol)는 언어별 코드 분석 기능을 에디터 독립적으로 제공하는 표준 프로토콜이고, MCP(Model Context Protocol)는 AI 모델이 외부 데이터 소스나 도구와 상호작용하는 방식을 표준화한 프로토콜입니다. OpenCode가 이 둘을 지원한다는 것은 언어 문맥을 이해한 상태로 분석하고 DB나 외부 API를 컨텍스트로 활용할 수 있다는 의미입니다.
단점 및 주의사항
| 항목 | 내용 | 대응 방안 |
|---|---|---|
| 설정 복잡성 | 여러 프로바이더와 에이전트 구성에 초기 학습 비용 발생 | Models.dev 활용해 프로바이더 설정 간소화 |
| 터미널 전용 UI | IDE 수준의 시각적 diff 미리보기나 인라인 하이라이팅 없음 | 필요 시 git diff로 변경사항 별도 확인 |
| 품질 편차 | 연결된 LLM 품질에 따라 결과물 수준이 달라짐 | 작업 유형별 최적 모델을 실험해 조합 |
| Anthropic 차단 이슈 | 2026년 1월 API 이용 정책 충돌로 Claude 직접 연결 제한 | OpenRouter 등 프록시 프로바이더를 통한 우회 설정 |
| 모드 전환 인식 | Plan → Build 전환 시점을 사용자가 명확히 인지해야 함 | 세션 시작 시 항상 Plan 모드부터 진입하는 습관 권장 |
실무에서 가장 흔한 실수
-
Build 모드에서 복잡한 작업 바로 시작하기: 간단한 한 줄 수정이면 괜찮지만, 여러 파일에 걸친 기능 추가나 리팩토링은 Plan 모드 없이 시작하면 나중에 수습이 어려워집니다. 작업 규모가 애매하다면 Plan 모드를 먼저 거치는 것을 권장합니다.
-
Plan 모드 계획을 검토 없이 바로 Build 전환하기: Plan 모드의 가치는 계획을 보여주는 게 아니라, 그 계획에 피드백을 줄 수 있다는 점입니다. "영향받는 파일 목록"을 실제로 읽고 예상과 다른 파일이 포함되어 있지 않은지 확인하는 습관이 중요합니다.
-
모든 작업에 동일한 LLM 프로바이더 고집하기: 코드 생성과 코드 분석에 최적인 모델이 다를 수 있습니다. 비용 효율적인 로컬 모델(Ollama)은 Plan 모드 분석에 쓰고, Build 모드의 실제 구현에는 더 강력한 모델을 쓰는 식으로 역할을 나눠보는 것도 좋은 방법입니다.
마치며
AI 에이전트의 신뢰성은 "얼마나 잘 짜는가"보다 "실행 전에 무엇을 하려는지 보여주는가"에 달려 있습니다. OpenCode의 Plan/Build 모드 분리는 이 원칙을 구조적으로 구현한 설계이고, 복잡한 작업일수록 그 효과가 선명해집니다.
지금 바로 시작해볼 수 있는 3단계:
-
pnpm add -g opencode-ai(또는npm install -g opencode-ai)로 설치한 뒤, 현재 작업 중인 프로젝트 디렉토리에서opencode를 실행해볼 수 있습니다. 모델 프로바이더는 Ollama 로컬 모델로 시작하면 API 비용 없이 첫 경험을 해볼 수 있습니다. -
터미널 UI가 열리면 Build 모드로 바로 뛰어들지 않고,
Tab키를 눌러 Plan 모드로 진입한 뒤 "현재 이 프로젝트의 구조를 분석하고 가장 개선이 필요한 부분 3가지를 알려줘"라고 물어보면 좋습니다. 파일은 전혀 변경되지 않으니 부담 없이 탐색해볼 수 있습니다. -
Plan 모드에서 제안받은 내용 중 하나를 골라 계획을 검토한 후,
Tab으로 Build 모드 전환 → 실제 구현까지 전체 플로우를 한 번 경험해보시는 것을 권장합니다. AI가 먼저 말하게 만드는 것이 어떤 느낌인지, 직접 체험하면 분명히 알게 됩니다.
참고 자료
공식 문서
- OpenCode 공식 문서 - Modes
- Modes | opencode (dev 문서)
- OpenCode GitHub 저장소
- OpenCode: A model-neutral AI coding assistant - Red Hat Developer
커뮤니티 참고 자료
- Plan Mode vs Build Mode for Reliable AI Coding - Educative
- OpenCode vs Claude Code vs Cursor: Complete Comparison 2026 - NxCode
- OpenCode Deep Dive: Provider-Agnostic AI CLI in 2026 - sanj.dev
- OpenCode 사용법 가이드 - Kanaries (한국어)
- OpenCode 플랜→빌드 워크플로우 완전 가이드 (한국어)
- Opencode Core Modes - Plan and Build Explained