📑
Clineの内部構造：Plan ModeとAct Modeの技術解説

2025/04/01に公開
 はじめにAIがコードを書き、ファイルを編集し、コマンドを実行する時代が到来しています。VSCode拡張機能として人気を集めているClineは、AIアシスタントにファイル作成・編集、ターミナルコマンド実行、さらにはブラウザ操作までを許可する革新的なツールです。しかし、強力な自律性を持つAIに対する適切な制御機構が不可欠であることは言うまでもありません。
Clineの「Plan Mode」と「Act Mode」は、この問題に対するエレガントな解決策です。この記事では、両モードの内部実装を深掘りし、各モードが内部でどのように機能しているのかをソースコードレベルで解説します。

 Clineのモード設計：基本概念Clineは、AIアシスタントの操作を「計画」と「実行」の2つのフェーズに分離することで、ユーザーがAIの行動をより細かく制御できるようにしています。

 モードの定義ソースコードを見ると、モードは非常にシンプルに定義されています：
// src/shared/ChatSettings.ts
export interface ChatSettings {
    mode: "plan" | "act"
}

export const DEFAULT_CHAT_SETTINGS: ChatSettings = {
    mode: "act",
}
この単純なAPIが、実は内部で複雑な動作モードの切り替えを実現しています。デフォルトでは「Act Mode」が設定されていますが、ユーザーはいつでもUIからモードを切り替えることができます。

 Plan Mode：思考と計画のフェーズ
 コンセプトPlan Modeは、AIが実際の変更を加える前に、ユーザーと一緒に計画を練るためのモードです。このモードでは、AIは情報収集、質問、解決策の設計に集中し、実際のファイル変更やコマンド実行などの「危険な」操作は制限されています。

 内部動作Plan Modeの核心部分は、system.tsファイルに見ることができます：
// Plan Modeの説明（system.tsから抜粋）
`- PLAN MODE: In this special mode, you have access to the plan_mode_respond tool.
 - In PLAN MODE, the goal is to gather information and get context to create a detailed plan for accomplishing the task, which the user will review and approve before they switch you to ACT MODE to implement the solution.
 - In PLAN MODE, when you need to converse with the user or present a plan, you should use the plan_mode_respond tool to deliver your response directly, rather than using <thinking> tags to analyze when to respond. Do not talk about using plan_mode_respond - just use it directly to share your thoughts and provide helpful answers.`
このモードでは、AIは特別な「plan_mode_respond」ツールを使用してユーザーと対話します。このツールはassistant-message/index.tsで他のツールと一緒に定義されています：
export const toolUseNames = [
    "execute_command",
    "read_file",
    "write_to_file",
    "replace_in_file",
    "search_files",
    "list_files",
    "list_code_definition_names",
    "browser_action",
    "use_mcp_tool",
    "access_mcp_resource",
    "ask_followup_question",
    "plan_mode_respond",  // Plan Modeで使用するツール
    "attempt_completion",
] as const

 AIへの指示AIがPlan Modeで動作する際には、responses.tsから特別な指示も提供されます：
planModeInstructions: () => {
    return `In this mode you should focus on information gathering, asking questions, and architecting a solution. Once you have a plan, use the plan_mode_respond tool to engage in a conversational back and forth with the user. Do not use the plan_mode_respond tool until you've gathered all the information you need e.g. with read_file or ask_followup_question.
    (Remember: If it seems the user wants you to use tools only available in Act Mode, you should ask the user to "toggle to Act mode" (use those words) - they will have to manually do this themselves with the Plan/Act toggle button below...)`
}
この指示から、Plan Modeには明確なワークフローがあることがわかります：
情報収集（read_fileやask_followup_questionなどの限られたツールを使用）
解決策の設計

plan_mode_respondツールを用いた対話的な計画の共有と改善
ユーザーによるAct Modeへの切り替え（AIは「toggle to Act mode」と提案）

 Act Mode：実行のフェーズ
 コンセプトAct Modeは、計画を実行に移すためのモードです。このモードでは、AIはファイルの作成・編集、コマンドの実行、ブラウザの操作など、実際にシステムに変更を加えるツールにアクセスできます。

 内部動作Act Modeの動作も同様にsystem.tsに定義されています：
`- ACT MODE: In this mode, you have access to all tools EXCEPT the plan_mode_respond tool.
 - In ACT MODE, you use tools to accomplish the user's task. Once you've completed the user's task, you use the attempt_completion tool to present the result of the task to the user.`
Act Modeでは、plan_mode_respond以外のすべてのツールが使用可能です。これには以下のような操作が含まれます：

write_to_file/replace_in_file: ファイルの作成・編集

execute_command: ターミナルコマンドの実行

browser_action: ブラウザの操作（ローカルサーバーへのアクセスなど）
タスクが完了したら、attempt_completionツールを使用して結果をユーザーに提示します。

 コンテキスト管理：モード間の会話の流れ興味深いのは、Plan ModeとAct Modeの間でコンテキスト（会話履歴）がどのように管理されるかです。
// Task クラスのフィールド
apiConversationHistory: Anthropic.MessageParam[] = []
clineMessages: ClineMessage[] = []
Clineは2種類の会話履歴を保持しています：

apiConversationHistory: AIモデルに送信される会話履歴

clineMessages: UI表示やツール使用履歴を含む内部履歴
重要なポイント: Plan ModeからAct Modeに切り替えても、会話履歴は継続します。つまり、Plan Modeで議論した内容はAct Modeに引き継がれ、AIはその計画に基づいて実装を進めることができます。
各メッセージには、現在のモード情報がenvironment_detailsとして含まれます：
環境詳細: { mode: "plan", ... } → 環境詳細: { mode: "act", ... }
これにより、AIは現在のモードに応じて適切なツールを選択できます。

 両モードの仕組みを図解┌─────────────────────────────┐      ┌─────────────────────────────┐
│         Plan Mode          │      │          Act Mode          │
├─────────────────────────────┤      ├─────────────────────────────┤
│                             │      │                             │
│  - 情報収集                 │      │  - ファイル作成/編集        │
│  - 質問と回答               │ ──→ │  - コマンド実行             │
│  - 解決策の設計             │      │  - ブラウザ操作             │
│  - 計画の共有/改善          │      │  - 実装と検証               │
│                             │      │                             │
└─────────────────────────────┘      └─────────────────────────────┘
         ↑                                         │
         │                                         │
         └─────────────────────────────────────────┘
                  ユーザーによるモード切替

 安全設計：モードによる制約の実装Plan/Actモード設計の本質は、安全性とユーザーコントロールの強化です。これを実現する具体的な方法を見てみましょう：
ツールアクセスの制御：
Plan Modeではplan_mode_respondのみが許可され、ファイル変更等は不可
Act Modeでは多くのツールが利用可能だが、各ツール使用には明示的なユーザー承認が必要
モード切替の制御：
// AIはモードを自動的に切り替えることができない
// ユーザーが明示的に切り替える必要がある
承認フロー：
const askApproval = async (type: ClineAsk, partialMessage?: string) => {
    const { response, text, images } = await this.ask(type, partialMessage, false)
    if (response !== "yesButtonClicked") {
        // User denied the tool use
        pushToolResult(formatResponse.toolDenied())
        // ...
    }
    // ...
}
このデザインにより、ユーザーは計画段階でAIと十分に対話し、実行内容を理解した上で初めて実行を許可することができます。

 実践的なユースケースこのモード設計は以下のようなシナリオで特に効果的です：
大規模リファクタリング：
Plan Mode: 変更範囲の議論、影響範囲の分析、最適なアプローチの検討
Act Mode: 合意された計画に基づいたコード変更の実行
新機能の追加：
Plan Mode: 要件の明確化、アーキテクチャの議論、必要なファイル構造の設計
Act Mode: 実際のコーディングと実装
バグ修正：
Plan Mode: 問題の分析、考えられる原因の特定、修正アプローチの検討
Act Mode: 修正の実装とテスト

 技術的な洞察Clineのモード設計から学べる技術的洞察：

関心の分離：計画と実行を分けることで、各フェーズに集中できる

ユーザーコントロール：重要な決定はユーザーに委ねられている

段階的実装：複雑なタスクを管理可能な段階に分割

コンテキスト共有：モード間で会話履歴を継続することでコンテキストが保持される

 結論：設計の妙Clineの「Plan Mode」と「Act Mode」の分離は、AIの強力な機能と人間のコントロールの必要性の間でバランスを取る絶妙な設計です。このアプローチは、AIツールの設計に携わる開発者にとって貴重なインスピレーションとなるでしょう。
計画・実行の2段階アプローチは、AIツールがより強力になる今後の時代において、人間主導の開発プロセスを維持しつつAIの恩恵を最大限に活用するためのひとつの指針となるかもしれません。

 参考資料Cline公式リポジトリ
VSCode Marketplace - Cline

Model Context Protocol (Clineで使用されている拡張ツール機能)
この記事は、Clineのソースコードを直接分析したものであり、内部実装は将来のバージョンで変更される可能性があります。
はじめに

Clineのモード設計：基本概念

モードの定義

Plan Mode：思考と計画のフェーズ

コンセプト

内部動作

AIへの指示

Act Mode：実行のフェーズ

コンセプト

内部動作

コンテキスト管理：モード間の会話の流れ

両モードの仕組みを図解

安全設計：モードによる制約の実装

実践的なユースケース

技術的な洞察

結論：設計の妙

参考資料

Discussion
