플랜 모드 사용

이 가이드에서는 에이전트가 코드를 한 줄도 쓰기 전에 구조화된 플랜을 받아 내는 방법을 설명합니다.

플랜 모드에서 에이전트는 읽기 전용으로 조사하며, 유일한 산출물은 타입이 지정된 플랜입니다. 이것은 직접 승인하는 단계들의 의존성 그래프이고, Control Center가 이를 실제 작업으로 컴파일합니다. 변경의 범위를 확인하고, 단계를 잘게 나눠 받고, 무엇이든 건드리기 전에 위험과 의존 관계를 이름 붙여 확인하고 싶을 때 사용합니다.

스페이스를 플랜 모드로 전환하기

다음 중 하나를 하면 스페이스의 모드가 전환되고, 그 변경은 영속됩니다:

작성기 도구 모음 맨 왼쪽의 모드 드롭다운에서 Plan을 선택합니다
Shift+Tab을 누릅니다
/plan을 보냅니다. /plan만 보내면 모드를 켜기만 하고, /plan <request>는 모드를 켠 뒤 나머지를 메시지로 보냅니다

/plan은 결코 텍스트로 전달되지 않습니다 — 대신 저장된 모드를 설정하며, 도구 표면과 가드 프리셋, 프롬프트가 모두 이 값을 권위로 삼아 읽습니다. 따라서 이번 턴과 그 이후의 모든 턴에서, 다시 바꿀 때까지 모드가 유지됩니다.

모드는 스페이스에 저장되므로, 같은 에이전트가 여기서는 플랜 모드이고 다른 곳에서는 에이전트 모드일 수 있습니다.

에이전트가 만들어 내는 것

읽기 전용으로 조사합니다 — 메모리, 코드 인덱스, 파일
submit_plan을 한 번 호출합니다. 여기에는 goal과 nodes가 들어가고, 각 노드는 안정적인 key, title, description, 그리고 자신이 dependsOn하는 노드 키를 담습니다(독립적인 작업을 병렬로 실행할 수 있게 해 주는 것이 바로 이 키입니다)
멈춥니다

이 도구는 그래프를 검증합니다 — 중복 키, 끊어진 의존성, 순환 — 그리고 망가진 플랜을 받아들이는 대신 에이전트가 고쳐야 할 위반 사항을 돌려줍니다.

플랜은 대화 안에 목표와 상태, 단계 수를 보여 주는 간결한 행으로 나타납니다. Plan Studio — 의존성 그래프, 노드별 인스펙터, 비용 추정 — 는 대화 옆의 탭으로 열립니다: 행에서 열기를 누르거나, 그냥 기다리면 됩니다. 대화를 보고 있는 동안 30초 안에 도착한 플랜은 탭을 스스로 엽니다.

요청이 모호하면 플랜 에이전트는 잠시 멈추고 ask_user 도구로 최대 세 개의 차단성 질문을 할 수 있습니다. 이 도구는 대화에 폼(선택지 또는 자유 입력)을 렌더링하고, 답할 때까지 실행이 차단됩니다. 읽기 단계에 속하는 도구이므로 플랜 모드의 읽기 전용 표면에서도 살아남고, 승인 래퍼에서도 예외입니다(프롬프트 앞에 또 프롬프트를 두면 승인자가 연결되지 않은 상태에서 닫힌 채 실패해, 에이전트가 질문하는 행위 자체가 거부됩니다).

이 도구는 렌더링할 스페이스가 필요하므로, 대화가 없는 일회성 디스패치에는 제공되지 않습니다. 첫 메시지에 범위와 대상 저장소, 수용 기준을 미리 담아 보내는 편이 왕복 한 번보다 여전히 빠릅니다.

여기서 산문은 산출물이 아닙니다. submit_plan을 호출하지 않고 끝난 실행은 대화에 “Ended without submitting a plan (no submit_plan call).“라는 줄을 눈에 보이게 게시하고, 그 실행을 산출물을 놓친 것으로 표시합니다. 실행의 상태는 의도적으로 _completed_로 남습니다 — 그래야 파이프라인과 티켓의 상태 머신이 그대로 유지됩니다 — 따라서 상태 배지가 아니라 그 줄을 읽으세요.

플랜 승인하기

대화에 있는 플랜 행에서 승인 후 실행을 누릅니다. Plan Studio의 승인 바에서는 플랜 승인을 누릅니다(옆의 거부를 눌러도 됩니다. 그래프에 검증 오류가 있는 동안에는 승인이 비활성화됩니다).

그러면:

Control Center가 플랜을 오케스트레이션으로 컴파일하고 이를 머티리얼라이즈합니다 — 티켓과 실행입니다. 이 단계에는 모델이 관여하지 않으며, 결정적입니다
플랜은 그것을 작성한 에이전트로서 실행됩니다. 다른 누군가를 끌어들일지는 실행 시점에 그 에이전트가 판단합니다 — 워크스페이스의 위임 깊이 상한 안에서, 더 적합한 팀원에게 단계를 delegate_task할 수 있습니다
플랜의 목표는 그 대화의 목표가 되고, 작업은 바로 그 대화에서 실행됩니다: 각 단계는 에이전트가 요청받은 내용을 게시하고 자신의 턴을 스트리밍하므로, 이미 보고 있는 곳에서 작업을 따라가고 턴을 중지할 수 있습니다
대화의 일반 사이드 패널(할 일 아래)에 있는 목표 행이 settled/total 형태의 실행 진행률과 중지 버튼을 담고 있습니다. Plan Studio는 그래프에 노드별 상태를 표시하며, 거기서도 취소할 수 있습니다

승인하지 않고 계속 작업하기

플랜을 승인하는 대신 이 대화에 그대로 머무르고 싶다면, 에이전트가 exit_plan_mode를 호출할 수 있습니다. 이것이 허용된 유일한 종료 경로입니다: 대화에 연결된 영속적 승인 요청을 열고 pending을 반환하며, 스페이스는 플랜 모드에 남고 에이전트는 행동해서는 안 됩니다. 요청이 승인되면, 에이전트의 다음 exit_plan_mode 호출이 스페이스를 플랜 모드에서 에이전트 모드로 전환하고 변경 도구의 잠금을 해제합니다. 거부되면 수정된 플랜에 대해 새 요청을 열 수 있습니다.

플랜 모드에서 나가려면 작성기 드롭다운(또는 Shift+Tab)을 전환하거나, 제출된 플랜을 승인합니다. exit_plan_mode는 decide_approval MCP 도구로 결정하는 영속적 승인을 엽니다. 차단된 도구 호출을 위한 가드레일 오버레이는 별개의 인메모리 큐이며, 플랜 종료 요청을 전달하지 않습니다.

파이프라인 단계에서의 플랜 모드

messaging.createSpace 파이프라인 노드는 노드 구성의 mode extra에서 대화 모드를 읽습니다 — extras['mode']: 'plan'. 이 키는 정확히 일치해야 합니다: conversationMode나 dispatchMode를 포함해 다른 철자는 조용히 무시되고, 방은 본문의 기본값으로 되돌아갑니다. 그 기본값은 채팅이 아니라 리뷰 모드입니다. promptAgent 단계는 자신이 만들지 않은 방에 참여하며, 그 방의 권한을 다시 설정하지 않습니다. 노드 구성 편집기의 디스패치 모드 선택(allParallel / manager)은 팀 디스패치 노드를 위한 것입니다. 대화 모드는 스페이스를 여는 템플릿에서, 또는 API를 통해 그 노드의 구성에서 extras['mode']로 설정합니다.