Planning Mode vs Doing Mode in Coding Agents
A coding agent can understand a task and still make the wrong change. Often, the problem is not code generation but timing: the agent starts editing before the goal, constraints, and verification steps are clear. Separating planning mode from doing mode gives you a practical checkpoint between deciding what should happen and allowing it to happen.
This walkthrough uses a small example: adding an optional status filter to an existing API endpoint without changing its default behavior.
§ Step 1: Define the two modes by their permissions
Planning mode is for investigating the repository, identifying constraints, and proposing an approach. Doing mode is for making approved changes and checking the results. These are workflow roles, not universal product features: different coding tools implement them differently.
A prompt that says “do not edit” is useful guidance, but it is not a security boundary. Where your tool supports it, restrict write access and require approval for commands with side effects. Even an inspection command can execute repository code, so judge commands by their behavior rather than their label.
§ Step 2: Give the agent a bounded task
Start with the intended outcome and the behavior that must remain unchanged. For the status-filter example, a useful instruction is: “Investigate adding an optional status parameter. Requests without it must return the same results as before. Do not modify files yet. Identify the implementation path, validation rules, and tests.”
Include relevant constraints: public API compatibility, database migration restrictions, performance expectations, and files or systems that are out of scope. This prevents the agent from interpreting a small feature as permission for a broader cleanup.
§ Step 3: Ask for evidence before a plan
Have the agent inspect the route handler, request validation, query construction, and existing tests. Its findings should reference actual repository paths and distinguish confirmed behavior from assumptions.
- Where are accepted query parameters defined?
- How are invalid values handled today?
- Does the data layer already support filtering?
- Which tests establish the endpoint’s current default behavior?
If an answer depends on an unavailable service or missing documentation, mark it as unresolved. A confident guess should not silently become an implementation requirement.
§ Step 4: Approve a small, testable plan
Request a short sequence of changes, not a speculative redesign. For this example, the plan might add parameter validation, pass the filter into the existing query layer, and cover filtered and unfiltered requests with tests.
Define acceptance criteria before approving execution: omitted parameters preserve existing behavior, supported values filter correctly, and unsupported values follow the API’s established error format. Resolve ambiguities now, including whether an empty parameter counts as omitted or invalid.
§ Step 5: Switch to doing mode explicitly
Use a clear handoff: “Implement the approved plan. Keep unrelated files unchanged. Stop and ask if you need a dependency, schema migration, or behavior change outside the plan.” This makes the execution boundary visible.
Keep approval requirements for destructive commands, credentials, deployments, and external writes. Doing mode should mean permission to perform a bounded task, not unrestricted access. If new evidence invalidates the plan, return to planning rather than improvising a larger change.
§ Step 6: Verify results, not just completion claims
Ask the agent to run focused tests first, then relevant broader checks. Review the diff for accidental formatting churn, unrelated refactors, and missing edge cases. A successful command is evidence only for what that command actually checked.
The final handoff should list changed files, tests run, outcomes, and anything not verified. If dependencies prevented tests from running, report that limitation plainly instead of presenting the implementation as validated.
§ Step 7: Keep the workflow portable
The separation between planning and execution belongs primarily in your coding tool’s permissions and approval workflow, not in the model endpoint. Vana API provides one endpoint supporting OpenAI-compatible requests, Anthropic Messages, and Gemini native protocols, and works with Claude Code, Codex, and Gemini CLI.
If you want to use that shared access layer, create a Vana API account. Billing is per real token with no monthly fee. Keep investigation proportional to task risk: plan enough to remove uncertainty, then execute the smallest approved change.