[opencode 12일 집중 — 터미널 네이티브 AI 코딩 에이전트 완전 정복] 5/12화: opencode Plan 모드 완전 가이드 — 읽고 확인하고 고치는 안전 루틴

이 글은 「opencode 12일 집중」 5일차로, opencode의 Plan 모드를 중심으로 안전하게 코드를 읽고 확인한 뒤 고치는 실전 루틴을 다룹니다.

어제는 TUI 단축키를 손에 익혔습니다. 오늘은 그 TUI 위에서 돌아가는 두 개의 모드 — Plan과 Build — 가 왜 나뉘어 있는지, 그리고 이 구분이 실무에서 어떤 사고를 막아 주는지 이야기합니다.

오늘의 핵심 3가지

• Plan 모드는 읽기 전용 — AI가 코드를 분석하고 계획을 세우되, 파일을 절대 수정하지 않는다.
• Build 모드는 실행 모드 — AI가 파일 쓰기·편집·셸 명령 실행까지 수행한다.
• Tab 한 번이면 전환 — “먼저 읽고, 확인하고, 그 다음에 고친다”는 습관이 자동으로 만들어진다.

왜 모드가 둘로 나뉘어야 하는가

AI 코딩 에이전트에게 “이 함수 리팩터링해 줘”라고 말하면 즉시 파일을 고칩니다. 대부분은 괜찮지만, 문제가 생기는 경우는 언제나 같은 패턴입니다.

• 코드베이스를 처음 보는 상태에서 바로 수정을 지시했다.
• 의존 관계를 파악하기 전에 파일 하나만 보고 고쳤다.
• AI가 “이렇게 하겠습니다”라고 말한 계획을 검토하지 않고 승인했다.

opencode의 Plan/Build 분리는 이 패턴을 구조적으로 차단합니다. Plan 모드에 있는 동안에는 AI가 아무리 자신 있어도 파일을 건드릴 수 없습니다. 개발자가 의식적으로 Tab을 눌러 Build로 전환해야만 변경이 시작됩니다.

Plan 모드 — 안전한 탐색 공간

Plan 모드에서 AI가 할 수 있는 것

• 파일 읽기 — 소스 코드, 설정 파일, 문서를 자유롭게 탐색합니다.
• 코드 분석 — 함수 호출 관계, 의존성 그래프, 타입 구조를 파악합니다.
• grep/glob 검색 — 패턴 매칭으로 코드베이스 전체를 훑습니다.
• LSP 연동 — 정의로 이동, 참조 찾기 등 언어 서버 기능을 활용합니다.
• 변경 계획 수립 — “어떤 파일을 어떻게 고칠 것인지” 구체적인 계획을 텍스트로 제시합니다.

Plan 모드에서 AI가 할 수 없는 것

• 파일 쓰기/편집/삭제 — write, edit, patch 도구가 비활성화됩니다.
• 셸 명령 실행 — ! 접두어 명령이 차단됩니다.
• 외부 시스템 변경 — git commit, npm install 등 부수 효과가 있는 모든 작업이 막힙니다.

요약하면, Plan 모드의 AI는 눈과 입만 있고 손이 없는 상태입니다. 무엇이든 볼 수 있고 의견을 말할 수 있지만, 실제로 무언가를 바꾸는 것은 불가능합니다.

Build 모드 — 통제된 실행

Build 모드로 전환하면 AI의 도구 상자가 완전히 열립니다.

• 파일 생성·편집·삭제 — write, edit, patch 도구가 활성화됩니다.
• 셸 명령 실행 — 테스트 실행, 빌드, 린트 등을 직접 수행합니다.
• Git 작업 — 커밋, 브랜치 생성 등(허용 범위 내에서)을 처리합니다.

Build 모드라고 해서 AI가 마음대로 하는 것은 아닙니다. opencode는 파일 변경 전에 diff를 보여 주고, 셸 명령 실행 전에 확인을 요청합니다. 하지만 Plan 모드의 “원천 차단”과는 다릅니다. Build 모드에서는 승인만 하면 실행됩니다.

Tab 토글 — 실전 워크플로우

opencode TUI에서 Tab 키를 누르면 현재 모드가 전환됩니다. 화면 하단의 상태 표시줄에 현재 모드가 표시되므로, 지금 어느 모드인지 항상 확인할 수 있습니다.

권장 워크플로우: Plan 모드 → 검토 → Build

아래는 실무에서 가장 안전하고 효율적인 3단계 패턴입니다.

1단계: Plan 모드에서 탐색과 계획

# opencode 실행 (기본이 Plan 모드)
opencode

# Plan 모드에서 질문
> 이 프로젝트의 인증 로직을 분석해 줘.
> JWT 토큰 검증이 어디서 이루어지는지 찾아 줘.
> 토큰 만료 처리에 버그가 있는지 확인해 줘.

AI가 파일을 읽고, 관련 코드를 찾고, 분석 결과를 보고합니다. 이 과정에서 파일은 전혀 변경되지 않습니다.

2단계: 계획 검토

# 아직 Plan 모드
> 토큰 만료 처리를 수정하려면 어떤 파일을 어떻게 고쳐야 하는지 계획을 세워 줘.

AI가 구체적인 변경 계획을 제시합니다. 어떤 파일의 몇 번째 줄을 어떻게 바꿀 것인지, 테스트는 어떻게 추가할 것인지 등을 텍스트로 설명합니다. 이 계획이 마음에 들지 않으면 수정을 요청하거나 다른 접근법을 제안할 수 있습니다. 아직 아무것도 바뀌지 않았으므로 얼마든지 방향을 틀 수 있습니다.

3단계: Build 모드에서 실행

# Tab을 눌러 Build 모드로 전환
# 상태 표시줄이 [BUILD]로 바뀜

> 방금 세운 계획대로 수정해 줘.

AI가 계획에 따라 파일을 수정하고, 변경 사항의 diff를 보여 줍니다. 필요하면 테스트를 실행해서 수정이 올바른지 확인합니다.

미지의 코드베이스를 만났을 때

Plan 모드의 진가는 처음 보는 코드베이스를 다룰 때 드러납니다. 레거시 프로젝트를 인수받았거나, 오픈소스 프로젝트에 기여하려는 상황을 생각해 보세요.

시나리오: 처음 보는 프로젝트에 버그 수정 기여하기

# 1. 프로젝트 클론
git clone https://github.com/example/some-project.git
cd some-project

# 2. opencode를 Plan 모드로 시작
opencode

Plan 모드에서 순차적으로 질문합니다.

# 프로젝트 구조 파악
> 이 프로젝트의 전체 구조를 분석해 줘. 주요 모듈과 진입점이 어디인지 알려 줘.

# 관련 코드 탐색
> issue #42에서 보고된 "날짜 파싱 오류"와 관련된 코드를 찾아 줘.

# 의존 관계 확인
> 해당 함수를 호출하는 모든 곳을 찾아 줘. 수정했을 때 영향 범위가 어디까지인지 파악하고 싶어.

# 수정 계획 수립
> 이 버그를 고치려면 어떻게 해야 하는지 계획을 세워 줘. 테스트 케이스도 포함해 줘.

이 전 과정에서 파일은 한 글자도 바뀌지 않습니다. AI는 read, grep, glob, LSP 도구만 사용해서 코드를 탐색하고 분석합니다.

계획이 충분히 구체적이고 타당하다고 판단되면, 그때 Tab을 눌러 Build 모드로 전환하고 수정을 시작합니다.

이 워크플로우가 중요한 이유

Build 모드에서 바로 시작하면 AI는 파일 몇 개만 읽고 곧바로 수정에 들어갈 수 있습니다. 운이 좋으면 제대로 고쳐지지만, 의존 관계를 놓쳐서 다른 곳이 깨지거나, 프로젝트의 코딩 컨벤션과 맞지 않는 코드를 생성하는 경우가 빈번합니다.

Plan 모드를 먼저 거치면 AI가 충분한 컨텍스트를 확보한 상태에서 수정에 들어가므로, 첫 번째 시도의 품질이 눈에 띄게 올라갑니다. 특히 대규모 코드베이스에서는 이 차이가 극적입니다.

실전 명령어 정리

모드 확인과 전환

# TUI 내부에서
Tab              # Plan ↔ Build 토글
# 하단 상태 표시줄에서 현재 모드 확인 가능

Plan 모드 전용 활용 예시

# 코드베이스 전체 구조 파악
> 이 프로젝트의 디렉토리 구조와 주요 모듈을 설명해 줘.

# 특정 기능의 구현 위치 탐색
> 사용자 인증 관련 코드가 어디에 있는지 찾아 줘.

# 변경 영향도 분석
> UserService 클래스를 수정하면 어떤 파일들이 영향을 받는지 분석해 줘.

# 리팩터링 계획 수립
> 이 모듈의 순환 의존성을 해소하는 방법을 제안해 줘. 구체적인 파일별 변경 계획을 세워 줘.

Build 모드 전환 후 실행

# Tab으로 Build 전환 후
> 방금 세운 계획대로 리팩터링을 진행해 줘.
> 변경 후 테스트도 실행해서 깨지는 게 없는지 확인해 줘.

비대화형에서 Plan 모드 활용

# CLI에서 Plan 모드로 분석만 수행
opencode run "이 프로젝트의 보안 취약점을 분석해 줘" --mode plan

# 결과를 JSON으로 받아 다른 도구에 연계
opencode run "코드 품질 이슈를 목록으로 정리해 줘" -f json --mode plan

Plan 모드를 극대화하는 팁

1. 계층적 질문 전략

넓은 범위에서 좁은 범위로 질문을 좁혀 가세요.

• 전체 구조 → 특정 모듈 → 특정 함수 → 특정 로직
• 한 번에 “이거 고쳐 줘”보다, 단계적으로 파고드는 것이 AI의 컨텍스트 품질을 높입니다.

2. @로 파일 고정

4회차에서 다뤘던 @ 파일 퍼지 검색을 Plan 모드에서 적극 활용하세요. 분석 대상 파일을 명시적으로 지정하면 AI가 관련 없는 파일을 읽느라 토큰을 낭비하지 않습니다.

# @ 입력 후 파일명 검색 → 선택
@src/auth/jwt.ts
> 이 파일의 토큰 검증 로직에 문제가 있는지 분석해 줘.

3. /compact로 컨텍스트 정리

Plan 모드에서 긴 탐색을 진행하다 보면 컨텍스트가 길어집니다. Build로 넘어가기 전에 /compact로 핵심만 압축하면 Build 단계에서 AI의 집중도가 올라갑니다.

# Plan 모드에서 충분히 탐색한 후
/compact

# 그 다음 Tab으로 Build 전환
# AI가 압축된 컨텍스트를 기반으로 효율적으로 작업

Gotcha 미니 코너: Build 모드에서 시작하면 Plan이 무의미해지는 함정

opencode를 열자마자 습관적으로 Tab을 눌러 Build 모드로 전환하는 분이 있습니다. Build 모드에서도 “분석해 줘”라고 물으면 AI가 분석은 합니다. 하지만 Build 모드의 AI는 분석 중에도 파일을 수정할 수 있는 상태입니다.

문제는 AI가 때때로 분석과 동시에 “간단한 수정”을 제안하면서 바로 적용해 버리는 경우가 있다는 점입니다. “이 부분은 명확한 버그니까 바로 고치겠습니다”라며 코드를 변경하는 식입니다.

해결책: 탐색과 분석이 목적이라면 반드시 Plan 모드를 유지하세요. Tab을 눌러 Build로 전환하는 것은 “이제 수정해도 좋다”는 명시적 신호입니다. 이 신호를 의식적으로 보내는 습관이 안전한 변경의 핵심입니다.

Plan/Build가 빛나는 실무 시나리오

코드 리뷰 보조

동료의 PR을 리뷰할 때 Plan 모드를 활용하면 효과적입니다.

# 해당 브랜치 체크아웃 후
git checkout feature/new-payment-flow
opencode

# Plan 모드에서
> 최근 커밋에서 변경된 파일을 분석해 줘. 잠재적 문제가 있는지 확인해 줘.
> 이 변경이 기존 결제 로직과 충돌할 수 있는 부분이 있는지 살펴봐.

Plan 모드이므로 리뷰 대상 코드가 변경될 걱정 없이 안심하고 AI에게 분석을 맡길 수 있습니다.

레거시 코드 이해

문서가 없는 오래된 코드를 파악할 때 Plan 모드의 읽기 전용 특성은 매우 유용합니다. AI가 코드를 읽고 설명해 주는 동안, 원본 코드는 한 글자도 바뀌지 않는다는 보장이 있으니까요.

# Plan 모드에서
> src/legacy/ 디렉토리의 코드를 분석해서 아키텍처 문서를 작성해 줘.
> 각 모듈의 역할과 모듈 간 의존 관계를 정리해 줘.

장애 대응 초기 분석

프로덕션 장애가 발생했을 때, 급하다고 바로 Build 모드에서 코드를 고치기 시작하면 상황을 악화시킬 수 있습니다. Plan 모드에서 먼저 원인을 정확히 파악한 뒤, 확신이 생겼을 때 Build로 전환하는 것이 안전합니다.

# Plan 모드에서 원인 분석
> 에러 로그에 "connection pool exhausted"가 반복되고 있어.
> DB 커넥션 풀 관련 코드를 찾아서 왜 누수가 발생하는지 분석해 줘.

# 원인 확인 후 Tab → Build
> 분석 결과대로 커넥션 반환 누락 부분을 수정해 줘.

다른 도구와의 비교

Plan/Build 모드 분리는 opencode만의 고유한 개념은 아닙니다. Claude Code에도 유사한 plan 모드가 있고, Cursor의 경우 Agent 모드와 Ask 모드가 비슷한 역할을 합니다. 하지만 opencode의 구현이 돋보이는 점은 Tab 한 키로 즉시 전환된다는 단순함과, 모드 전환이 도구 사용 권한 자체를 전환한다는 명확한 구분입니다.

다른 도구들은 모드 전환이 별도 설정이나 새 대화 시작을 요구하는 경우가 있지만, opencode는 같은 대화 컨텍스트를 유지하면서 모드만 바뀝니다. Plan에서 쌓은 컨텍스트가 그대로 Build로 이어지므로, AI가 “아까 분석한 내용”을 기억한 상태에서 수정 작업에 들어갑니다.

모드 전환을 워크플로우에 녹이기

Plan/Build 전환을 효과적으로 사용하기 위한 실전 규칙 세 가지를 제안합니다.

규칙 1: 새 작업은 항상 Plan으로 시작한다.

opencode를 열면 기본이 Plan 모드입니다. 이 기본값을 존중하세요. 코드를 고치겠다는 확신이 들 때까지 Plan에 머무르세요.

규칙 2: Build 전환 전에 “무엇을 고칠지” 한 문장으로 말할 수 있어야 한다.

“auth/jwt.ts의 validateToken 함수에서 만료 시간 비교 연산자를 >에서 >=로 바꾼다.” 이 정도의 구체성이 확보된 후에 Build로 넘어가세요.

규칙 3: Build에서 예상과 다른 결과가 나오면 Plan으로 돌아간다.

AI가 수정한 결과가 의도와 다르면, 추가 수정을 계속 요청하기보다 Tab을 눌러 Plan으로 돌아가서 다시 분석하는 것이 빠릅니다. Build 모드에서 “수정 → 확인 → 재수정”을 반복하면 코드가 점점 꼬입니다.

정리: Plan이 먼저다

Plan 모드는 “느린 모드”가 아닙니다. 오히려 첫 번째 시도의 정확도를 높여서 전체 작업 시간을 줄여 주는 가속 장치입니다. 처음 보는 코드베이스에서, 복잡한 리팩터링에서, 장애 대응에서 — Plan 모드로 충분히 파악한 뒤 Build로 전환하는 습관이 몸에 배면, AI 코딩 에이전트를 훨씬 안전하고 효과적으로 활용할 수 있습니다.

내일 6일차에서는 Build 모드에서 AI가 실제로 사용하는 내장 도구들 — read, write, edit, patch, grep, glob, 셸 실행, LSP 연동 — 을 하나하나 뜯어봅니다. 도구의 동작 방식을 알면 AI에게 더 정확한 지시를 내릴 수 있습니다.

---