AI 코딩 에이전트에게 바로 “고쳐줘”라고 말해도 되는 일이 있다.

오탈자 하나, 문장 한 줄, 실패 원인이 분명한 작은 테스트는 바로 맡겨도 된다.

하지만 여러 파일을 바꾸거나, 삭제와 배포가 섞이거나, 데이터베이스와 권한이 닿는 작업은 다르다. 이때 바로 실행시키면 나중에 사람이 물어야 할 질문을 에이전트가 먼저 결정해 버린다.

Plan Mode는 그 결정을 잠깐 멈추는 단계다.

이 글에서는 Codex Plan Mode를 “좋은 계획을 뽑는 버튼”이 아니라, 코드 수정 전에 사람이 다시 결정권을 가져오는 작업 습관으로 본다.

바로 실행, Plan Mode, 승인 후 구현 사이에 검토 게이트를 둔 흐름도.

바로 실행이 위험해지는 순간

AI agent가 빠르게 움직이는 것은 장점이다.

문제는 빠르게 움직여도 되는지 아직 정하지 않았을 때다.

예를 들어 이런 요청은 겉으로는 단순해 보인다.

댓글 기능 고쳐줘.
빌드 깨지는 것 고쳐줘.
릴리스 노트 배포까지 해줘.
로그인 흐름 정리해줘.

하지만 실제 작업으로 들어가면 질문이 바로 생긴다.

  • 어떤 파일을 봐야 하는가.
  • 기존 패턴을 유지해야 하는가.
  • 삭제, migration, package install, push, deploy가 필요한가.
  • 실패하면 어디서 멈춰야 하는가.
  • 완료됐다는 증거는 무엇인가.

이 질문에 답하지 않은 상태에서 agent가 파일을 고치기 시작하면, 사람은 나중에 diff를 보고 거꾸로 추론해야 한다.

나는 이 비용을 줄이려고 Plan Mode를 쓴다.

Plan Mode는 구현 전 대화 단계다

OpenAI의 Codex 문서는 복잡하거나 모호한 작업에서는 구현 전에 계획을 먼저 요청하라고 안내한다. Codex의 Plan Mode는 맥락을 모으고, 필요한 질문을 하고, 구현 전에 더 나은 계획을 만들게 하는 흐름으로 설명된다.

CLI에서는 /plan으로 Plan Mode에 들어갈 수 있고, 문서 기준으로는 Shift+Tab 전환도 언급된다. 중요한 점은 이것을 “안전이 자동으로 끝난 상태”로 착각하지 않는 것이다.

Codex에서 Plan Mode는 계획을 세우는 단계다. 실제 파일 수정, 명령 실행, 네트워크 접근 같은 행동 경계는 sandbox, approval policy, /permissions 같은 권한 설정과 함께 봐야 한다.

쉽게 나누면 이렇다.

Plan Mode는 지금 작업의 접근법과 순서를 먼저 만든다.

permission이나 read-only 설정은 실제로 무엇을 실행하거나 수정할 수 있는지 제한한다.

approval은 위험한 행동 앞에서 사용자 확인을 받게 만든다.

test, build, browser check는 끝났다는 증거를 만든다.

그래서 나는 “Plan Mode니까 안전하다”라고 쓰지 않는다.

더 정확한 문장은 이쪽이다.

Plan Mode는 실행 전에 멈추게 해준다.
실행을 실제로 막는 것은 권한과 승인 경계다.

Claude Code에서 같은 단어는 권한을 가리킨다

여기서 헷갈리는 지점이 있다.

Claude Code도 Plan Mode라는 말을 쓴다. 다만 Claude Code 문서에서는 Plan Mode가 permission mode 중 하나로 더 강하게 설명된다. 코드베이스를 읽고 계획을 제안하지만 승인 전에는 source file을 편집하지 않는 흐름이다.

그래서 “Plan Mode”라는 같은 단어라도 도구마다 보장 범위가 조금 다르다.

Codex 글을 쓸 때는 이 차이를 분리해야 한다.

  • Codex에서는 /plan으로 계획을 만든다.
  • 변경을 막고 싶으면 read-only나 approval 설정을 같이 본다.
  • Claude Code에서는 Plan Mode 자체가 read-only exploration 성격으로 더 명확하게 문서화돼 있다.
  • 어느 쪽이든 계획 승인은 diff 검토를 대체하지 않는다.

이 차이를 모르면 위험한 문장이 나온다.

Plan Mode를 쓰면 파일 수정이 절대 일어나지 않는다.

이렇게 쓰면 안 된다. 도구별 권한 모델이 다르고, 설정과 표면도 계속 바뀐다.

켜야 할 때와 안 켜도 될 때

나는 Plan Mode를 모든 작업에 켜지 않는다.

작은 작업까지 전부 계획부터 만들면 오히려 느려진다. Plan Mode는 정중한 의식이 아니라 복잡도 필터다.

켜는 쪽이 좋은 경우는 이렇다.

  • 요구사항이 아직 흐릿하다.
  • 여러 파일이나 여러 모듈이 바뀐다.
  • 삭제, 이동, migration, 배포, push, 권한 변경이 범위에 들어온다.
  • 기존 패턴을 먼저 찾아야 한다.
  • 실패했을 때 되돌리기 어렵다.
  • 완료 기준이 아직 테스트나 화면 확인으로 정리되지 않았다.

안 켜도 되는 경우도 있다.

  • 문장 한두 개만 고친다.
  • 단일 함수의 명확한 오타나 타입 오류를 고친다.
  • 실패 로그와 기대 결과가 이미 분명하다.
  • 수정 범위가 좁고 되돌리기 쉽다.

핵심은 작업 크기가 아니라 결정의 수다.

작아 보여도 결정이 많으면 Plan Mode가 맞다. 커 보여도 결정이 이미 끝났고 검증 기준이 분명하면 바로 구현으로 가도 된다.

좋은 Plan Mode 요청은 짧다

Plan Mode에 넣는 요청은 길수록 좋은 것이 아니다.

길어야 할 때도 있지만, 처음에는 아래 다섯 줄이면 충분한 경우가 많다.

/plan
목표:
맥락:
제약:
완료 기준:
하지 말 것:

예를 들면 이렇게 쓴다.

/plan
목표: 댓글 작성 실패 원인을 찾고 최소 수정안을 제안해줘.
맥락: 최근 바뀐 댓글 UI, API 호출부, 관련 검증 스크립트를 먼저 봐줘.
제약: migration, deploy, package install, push는 하지 말 것.
완료 기준: 수정 전 계획에 재현 방법, 변경 후보 파일, 검증 명령이 포함되어야 함.
하지 말 것: 바로 파일을 수정하지 말 것.

이 요청의 목적은 agent를 묶어두는 것이 아니다.

사람이 먼저 리뷰하는 계획을 받는 것이다.

계획을 받으면 무엇을 봐야 하나

좋은 계획은 문장이 매끄러운 계획이 아니다.

리뷰 가능한 계획이다.

나는 Plan Mode 결과를 받을 때 아래를 본다.

바뀔 파일이 보이는가?
아직 모르는 가정이 드러나는가?
사용자에게 물어야 할 질문이 남아 있는가?
위험 작업이 분리되어 있는가?
검증 명령이나 화면 확인이 있는가?
어디서 멈출지 쓰여 있는가?

여기서 하나라도 비어 있으면 바로 구현으로 넘기지 않는다.

예를 들어 “전체 구조를 리팩터링한다”는 계획은 아직 약하다. 어느 파일을 왜 바꾸는지, 어떤 테스트로 끝을 볼지, 어떤 변경은 이번 범위에서 제외할지 보여야 한다.

Plan Mode의 장점은 agent가 코드를 아직 덜 만졌다는 점이다.

계획 단계에서 방향을 고치는 비용은 작다. 구현이 끝난 뒤 잘못된 방향을 되돌리는 비용은 크다.

다른 장치와 역할을 섞지 않는다

Plan Mode를 쓰다 보면 /goal, AGENTS.md, Skill, permission과 자주 섞인다.

나는 이렇게 나눈다.

  • Plan Mode는 이번 작업을 시작하기 전 접근법을 만든다.
  • /goal은 긴 작업의 완료 기준을 계속 붙잡는다.
  • AGENTS.md는 repo에서 반복 적용할 기본 규칙을 준다.
  • Skill은 자주 반복하는 절차를 재사용하게 한다.
  • permission과 sandbox는 실제 행동 가능 범위를 제한한다.
  • hook과 CI는 특정 행동을 기계적으로 막거나 검증한다.

Plan Mode는 이 중 하나일 뿐이다.

예를 들어 “위험한 삭제 명령은 실행 전 확인받아라”는 Plan Mode 요청에만 남기면 약하다. 반복 규칙이면 repo 지침에 있어야 하고, 정말 막아야 하면 hook, permission, CI 같은 기계적인 경계가 필요하다.

반대로 “이번 기능을 어떤 순서로 고칠까”는 Plan Mode에 잘 맞는다. 매번 같은 규칙으로 박아둘 내용이 아니라 이번 작업에서 판단해야 할 내용이기 때문이다.

실패 모드도 있다

Plan Mode를 켰다고 무조건 좋아지지는 않는다.

첫 번째 실패는 계획이 너무 길어지는 것이다.

긴 계획은 안전해 보이지만, 핵심 결정이 묻히기도 한다. 특히 “조사한다”, “수정한다”, “검증한다” 같은 말만 길게 늘어나면 실제로는 아무것도 정하지 않은 계획이다.

두 번째 실패는 계획 승인을 코드 승인으로 착각하는 것이다.

계획을 승인했다는 것은 “이 방향으로 구현해도 된다”는 뜻이지, 최종 diff를 보지 않아도 된다는 뜻이 아니다. 구현 뒤에는 여전히 diff, 테스트, build, 화면 확인이 필요하다.

세 번째 실패는 Plan Mode를 보안 경계처럼 믿는 것이다.

Codex 기준으로는 특히 조심해야 한다. 계획 요청과 권한 제한은 다른 축이다. 파일 수정을 막아야 하는 상황이면 read-only, approval, sandbox를 함께 확인해야 한다.

네 번째 실패는 작은 일에도 전부 Plan Mode를 붙이는 것이다.

오타 하나를 고치는데 계획, 승인, 검토, 검증 문서까지 요구하면 작업 비용이 더 커진다. 작은 일은 작게 끝내는 편이 낫다.

내가 쓰는 기준

나는 Plan Mode를 이렇게 쓴다.

agent가 내 대신 결정을 내릴 것 같으면 Plan Mode.
내가 이미 결정을 끝냈고 검증만 남았으면 바로 구현.

이 문장이 제일 단순하다.

Plan Mode는 에이전트를 느리게 만드는 장치가 아니다. 사람이 늦게 개입하는 비용을 줄이는 장치다.

코드를 쓰기 전에 잠깐 멈추고, 바뀔 파일과 위험 작업과 검증 기준을 먼저 본다. 그 다음에 구현을 맡긴다.

좋은 Plan Mode는 거창한 문서가 아니라 이런 질문을 남긴다.

이 계획대로 실행해도 되는가,
아니면 아직 사람이 결정해야 할 것이 남았는가.

그 질문에 답하고 나면 agent에게 맡길 준비가 된 것이다.

시리즈 연결

참고한 문서