Claude Code plan mode workflow for team approval gates

<article> <p>A senior engineer asks Claude Code to change a deployment workflow. The agent understands the request, finds the YAML file, edits a few steps, and starts explaining the fix. The diff is plausible. The problem is not that the agent is careless. The problem is that nobody agreed on the blast radius before the repository changed.</p>

<p>That is the real job of a <strong>Claude Code plan mode workflow</strong>. It is not a magic safety switch. It is a review point before source edits begin.</p>

<p>Used well, plan mode gives a team a shared artifact: what Claude inspected, what it thinks should change, what it will avoid, which files are likely to move, which tests will prove the work, and where a human needs to decide. Used loosely, it becomes another prompt habit that feels safe while the real enforcement still lives somewhere else.</p>

<h2>What plan mode actually gives your team</h2>

<p>Claude Code plan mode is designed for analysis before editing. Claude can inspect the project, read files, run exploration commands, and propose a plan before source edits are allowed. You can enter it with <code>/plan</code>, cycle into it with <code>Shift+Tab</code>, start Claude with <code>claude --permission-mode plan</code>, or set <code>permissions.defaultMode: "plan"</code> in project settings.</p>

<p>After the plan is ready, Claude asks how to proceed. The approval flow can move the session into auto mode, into manual edit approval, back into planning, or into a deeper planning pass where available. Once you approve a plan, the session leaves plan mode and switches to the selected execution mode.</p>

<p>That last detail matters. Plan mode is a phase, not a permanent project state. If your team wants another plan before the next risky phase, someone has to put the session back into plan mode or prefix the next request with <code>/plan</code>.</p>

<p>There is also a useful review feature: <code>Ctrl+G</code> opens the proposed plan in your editor. For teams, that turns a chat response into something closer to a reviewable engineering note. You can edit the plan, narrow it, remove risky assumptions, or add the missing verification step before Claude starts changing code.</p>

<p>For the permission model behind this workflow, see the <a href="/claude-code-permissions" data-internal-link="claude-code-permissions">Claude Code permissions guide</a>.</p>

<h2>What plan mode does not enforce</h2>

<p>The practical mistake is treating plan mode as a governance boundary. It is not enough for that.</p>

<p>Plan mode is read-oriented, but it is not the same as "no commands." Claude Code documentation says Claude may read files and run shell commands to explore. Some built-in commands are treated as read-only, including common commands such as <code>ls</code>, <code>cat</code>, <code>grep</code>, <code>find</code>, <code>wc</code>, <code>diff</code>, <code>stat</code>, <code>du</code>, <code>cd</code>, and read-only forms of <code>git</code>, with documented exceptions.</p>

<p>Auto mode can also interact with planning. When auto mode during plan is enabled, classifier-approved commands may run while Claude is still planning. That can be fine in a normal application repo. It is less comfortable in a repository where exploration commands can touch cloud accounts, databases, package scripts, deployment systems, or generated files.</p>

<p>The bigger caveat is bypass permissions. In sessions where bypass permissions are available, Claude Code documentation says plan-mode blocks are not enforced. Claude is still instructed to plan, but attempted file edits or shell commands run without prompting except for explicit ask rules and certain built-in circuit breakers.</p>

<p>So the rule is simple: <strong>plan mode improves reviewability, but permissions, hooks, isolation, CI, and pull request review are what make the workflow enforceable.</strong></p>

<h2>The baseline Claude Code plan mode workflow</h2>

<p>For team use, standardize the workflow around six steps.</p>

<h3>1. Start with read-only investigation</h3>

<p>Begin non-trivial work in plan mode. Ask Claude to inspect the repository before proposing changes. The prompt should require it to list the files it read, the assumptions it made, and the unknowns that still need a human answer.</p>

<p>Use plan mode for changes with real blast radius: multi-file refactors, authentication, authorization, migrations, CI/CD, infrastructure as code, deployment config, build systems, dependencies, package scripts, cross-service behavior, and tasks likely to outlive one context window.</p>

<p>Do not force ceremony onto every tiny change. A typo in a test name does not need a committee. A migration touching production data does.</p>

<h3>2. Make the plan reviewable</h3>

<p>A useful plan is not a prose dump. It should be short enough for a reviewer to read and specific enough to catch bad assumptions.</p>

<p>Use this template:</p>

<ul> <li><strong>Goal:</strong> the user-visible or operational outcome.</li> <li><strong>Non-goals:</strong> what Claude must not change.</li> <li><strong>Likely files:</strong> files or directories expected to change.</li> <li><strong>Investigation notes:</strong> files read, relevant patterns found, unknowns.</li> <li><strong>Risk level:</strong> low, medium, or high, with a concrete reason.</li> <li><strong>Phases:</strong> a small table of implementation steps and stop points.</li> <li><strong>Commands and tests:</strong> exact verification commands Claude should run or ask to run.</li> <li><strong>Rollback:</strong> how to undo or contain the change if it fails.</li> <li><strong>Human approvals:</strong> named decisions that need a person before execution.</li> </ul>

<p>If the plan is too broad, keep planning. Ask Claude to split it by phase, remove speculative work, or state which part can be shipped independently. Teams get most of the value when the plan becomes narrow enough to approve, not when it becomes long enough to look impressive.</p>

<h3>3. Choose the execution mode by risk</h3>

<p>Approval should not mean the same thing for every task.</p>

<table> <thead> <tr> <th>Risk tier</th> <th>Typical work</th> <th>Recommended approval</th> </tr> </thead> <tbody> <tr> <td>Low</td> <td>Small tests, docs, local refactors with clear boundaries</td> <td>Approve into normal execution, ideally in a worktree</td> </tr> <tr> <td>Medium</td> <td>Multi-file app changes, API behavior, shared components</td> <td>Approve one phase at a time, with test gates after each phase</td> </tr> <tr> <td>High</td> <td>Auth, secrets, CI/CD, migrations, dependencies, infrastructure</td> <td>Manual edit approval, deny rules for risky commands, reviewer signoff</td> </tr> </tbody> </table>

<p>This is where team policy should be explicit. If a plan mentions <code>terraform apply</code>, <code>kubectl</code>, a production database client, <code>npm install</code>, <code>pip install</code>, <code>gh secret</code>, deployment CLIs, or state-changing <code>git</code> commands, it should not slide through as normal exploration.</p>

<p>For isolation patterns around these approvals, use the <a href="/ai-agent-sandboxing" data-internal-link="ai-agent-sandboxing">AI agent sandboxing guide</a>.</p>

<h3>4. Implement one phase at a time</h3>

<p>The best field pattern is phased execution. Large plans are hard to review and easy to drift from. Ask Claude to implement phase one, stop, summarize the diff, run the agreed checks, and wait before moving to phase two.</p>

<p>For larger work, keep two artifacts separate:</p>

<ul> <li><strong>Approved plan:</strong> the reviewed intent.</li> <li><strong>Progress notes:</strong> what actually changed, what failed, what was deferred.</li> </ul>

<p>Do not let Claude silently rewrite the approved plan as it discovers issues. If the plan changes, mark it as superseded and approve the new version. This prevents a common handoff failure: the plan says one thing, the diff does another, and nobody can tell when the decision changed.</p>

<h3>5. Verify the diff against the plan</h3>

<p>Approving a plan does not prove the implementation followed it. Treat plan-vs-diff reconciliation as its own review step.</p>

<p>Before a pull request, require Claude or a fresh session to compare:</p>

<ul> <li>the approved plan</li> <li>the changed files</li> <li>the commands that actually ran</li> <li>the tests that passed, failed, or were skipped</li> <li>the open risks that still need a reviewer</li> </ul>

<p>A fresh session can be useful because it has less incentive to defend the previous work. Ask it to find mismatches, omitted phases, unexpected files, and unverified claims. Then put the result in the PR description or review notes.</p>

<p>For the pull request review layer, connect this step to your <a href="/ai-code-review-agent-prs" data-internal-link="ai-code-review-agent-prs">AI code review agent workflow</a>.</p>

<h3>6. Hand off outside chat</h3>

<p>Do not rely on chat context as the source of truth. Plans can be lost in compaction, buried in a long transcript, or made stale by later decisions.</p>

<p>For team work, put the approved plan where humans already review engineering intent: an issue comment, PR description, temporary plan file, design note, or session handoff. If you store a temporary plan file in the repo, decide when it gets deleted and when it becomes durable documentation.</p>

<p>The handoff should answer one question quickly: what did we approve, and does the diff still match it?</p>

<h2>Team controls that make plan mode real</h2>

<p>Once plan mode becomes part of a team workflow, move policy out of prompts and into Claude Code controls.</p>

<h3>Checked-in project settings</h3>

<p>Use project settings for shared defaults such as <code>permissions.defaultMode: "plan"</code> and repository-specific permission rules. These settings make the expected workflow visible to everyone using the repo.</p>

<p>Project settings are still not the highest authority. Anthropic documents managed settings as the stronger control for organization standards because users and projects cannot override them. Use managed settings for non-negotiables: blocked tools, required hooks, monitoring configuration, or high-risk command policy.</p>

<h3>Ask and deny rules for risky tools</h3>

<p>Prompts and <code>CLAUDE.md</code> guide model behavior. They do not change what Claude Code allows. Permission rules are enforced by Claude Code itself, which makes them the right place for command policy.</p>

<p>In sensitive repos, add ask or deny rules for commands that can mutate state outside the source tree. Common candidates include package installation, deployment commands, cloud CLIs, database clients, secret management, remote write operations, and non-read-only <code>git</code> commands.</p>

<h3>Hooks for deterministic gates</h3>

<p>Hooks turn a polite workflow into a repeatable control. Use <code>PreToolUse</code> to block known-risk tool calls, <code>PermissionRequest</code> to log or shape approval prompts, <code>PostToolUse</code> to run checks after edits, <code>Stop</code> to require completion criteria, and <code>ConfigChange</code> to audit changes to Claude Code settings.</p>

<p>Hooks are especially useful because they do not depend on the model remembering a policy sentence from the start of a long session. They run at defined lifecycle points.</p>

<p>For concrete hook and permission patterns, see <a href="/claude-code-hooks-permissions" data-internal-link="claude-code-hooks-permissions">Claude Code hooks and permissions</a>.</p>

<h3>Telemetry for audit</h3>

<p>OpenTelemetry can export Claude Code metrics, events, and traces. For plan-mode governance, the useful events include permission mode changes, tool decisions, tool results, and hook execution. If your organization already sends security telemetry to a SIEM, map these events into the same review path as CI, deployment, and repository events.</p>

<p>This is not about watching every keystroke. It is about being able to answer basic incident questions later: which mode was active, which commands ran, which approvals happened, which hooks blocked or allowed actions, and which files changed afterward.</p>

<h2>A rollout pattern that does not overwhelm the team</h2>

<p>Start with one sensitive repository. Do not make plan mode mandatory everywhere on day one.</p>

<p>Pick a repo where the risk is real but the team can still move: an internal service with CI/CD, a shared library, an infrastructure module, or an app with auth-sensitive code. Add project settings that default to plan mode. Add ask rules for high-risk commands. Add a simple plan template. Require plan-vs-diff reconciliation in the PR description.</p>

<p>Then watch the friction. Track the number of approval prompts, how long plan review takes, how often plans are too broad, how often implementation diverges, which hooks are noisy, and which checks catch real issues. The brief does not support a universal number for these metrics, so treat them as local rollout signals rather than industry benchmarks.</p>

<p>After the pilot, tighten only the parts that proved useful. Maybe default plan mode belongs in every production repo. Maybe it belongs only in security-sensitive areas. Maybe low-risk teams need a shorter plan template. The point is to build a workflow people can actually follow when the work is moving fast.</p>

<h2>The practical policy</h2>

<p>If you want the short version, use this:</p>

<ul> <li>Use plan mode for non-trivial or high-blast-radius work.</li> <li>Require plans to state scope, non-goals, likely files, risks, phases, tests, rollback, and human approvals.</li> <li>Approve execution mode based on risk, not convenience.</li> <li>Run one phase at a time.</li> <li>Keep the approved plan visible outside chat.</li> <li>Use permissions, managed settings, hooks, worktrees, and CI as the real controls.</li> <li>Compare the final diff against the approved plan before PR.</li> </ul>

<p>That is the useful version of a Claude Code plan mode workflow: not "Claude must always plan," but "the team gets a written intent before risky work, and the tooling checks whether execution stayed inside that intent."</p> </article>