Spend planning effort where uncertainty matters

Learning objective

Use plan-first workflows for complex changes and direct execution for well-scoped tasks.

Core idea

Claude Code supports investigation and design through --permission-mode plan; small, understood fixes can proceed directly. At team scale, the architect’s decision is how much planning a change deserves, who accepts the design, and what discoveries require reopening it.

Treat planning as an investment in reducing costly uncertainty. A mandatory plan for every typo consumes attention without resolving a decision. Direct execution of a migration with unsettled compatibility requirements spreads assumptions through implementation before the responsible owners have chosen them. The useful policy distinguishes those cases before work begins.

How it works

Classify by uncertainty and consequence

Anthropic’s best practices favor planning when the approach is uncertain, multiple files change, or the developer is unfamiliar with the code. Their intake heuristic is: “If you could describe the diff in one sentence, skip the plan.” Use those signals to define a team intake rule, rather than converting a file count into an inflexible threshold.

Ask three questions. Is the desired behavior settled? Is the affected dependency path understood? Can the team verify the result without discovering the specification during implementation? A one-file authorization change can fail all three. A mechanical rename across several files can satisfy them if consumers and checks are known.

Record the choice in the work item. For direct execution, name the behavior, affected area, verification command, and escalation condition. For plan-first work, name the unresolved decisions and the people authorized to answer them. This is a project-owned planning policy, not another Claude Code permission mode.

Make the plan answer decisions

A plan should explain the selected approach, affected interfaces, migration order, acceptance checks, and rollback implications relevant to that change. Ask Claude to attach source paths to dependency claims so reviewers can check the decisive passages. A list of files is insufficient when compatibility or sequencing remains unsettled.

Assign review according to the decision. A module owner can accept a local refactor; a cross-service migration needs the owners of the producer and consumers. Do not ask a general reviewer to implicitly authorize a business behavior change hidden in an implementation detail. The plan makes that decision visible before editing multiplies its cost.

Use Ctrl+G to correct the proposed plan. An accountable owner accepts its approach and checks; Claude Code does not supply the organization’s approval policy.

Separate design approval from execution authority

Choose the approval option under the team’s policy in 7.1.3: Yes, and use auto mode delegates execution checks to the classifier; Yes, manually approve edits retains individual edit approvals. When auto mode is unavailable, the first option instead offers automatic edit acceptance; when the session started with bypass permissions enabled, it instead offers a switch to bypass permissions. Use No, keep planning when the design is not accepted. Accepting an approach does not mean granting every shell command, deployment, or repository write the resulting session might request.

Enforced source-preserving investigation needs a session without bypass permissions available. The platform owner should define the managed settings policy for planning sessions and verify that developer-local configuration cannot undermine the intended restriction; see 7.1.2 for settings ownership and 7.1.3 for permission enforcement. The technical lead records that requirement with the planning assignment instead of treating the displayed mode as sufficient assurance.

Reopen scope instead of stretching it

A direct assignment can expose a shared dependency or a policy question. Make that a reason to return to planning, not permission to extend the original fix across services. The developer reports what changed in the understanding, and the technical lead accepts a revised scope before implementation continues.

A direct assignment that exposes a shared dependency returns to planning, and implementation continues after an accountable owner accepts the approach.

The reverse also matters. Once investigation resolves the only ambiguity, stop planning and implement the agreed slice. Measure review and rework costs under 7.2.1. If plans repeatedly discover no decisions and reduce no rework, narrow the policy for that task class. If direct changes repeatedly trigger redesign, strengthen its intake criteria.

Key distinctions and trade-offs

Complexity versus size: Uncertainty, coupling, and consequence determine planning value. Lines changed are only a proxy.

Plan acceptance versus tool permission: One authorizes a design; the other governs actions during execution. Maintain both decisions explicitly.

Detailed plan versus verified assumptions: More prose cannot compensate for an unchecked caller or an unowned compatibility decision.

Planning adds review latency and consumes context. Its return comes from preventing a mistaken approach from propagating, especially where several teams must agree before implementation can be safely divided.

Architecture / decision scenario

A financial-services team must replace a settlement adapter used by three services within a two-week release window. A developer proposes direct bulk replacement because the method names appear compatible. The architect requires planning: two consumers depend on a retry behavior that the replacement may not preserve, and those owners must choose the compatibility rule.

The team investigates with claude --permission-mode plan in a terminal without bypass permissions available. The plan names the shared wrapper, the two compatibility decisions, consumer verification, and migration order. The service owners accept one adapter slice before any caller conversion. The technical lead owns scope changes; the release owner retains deployment authority.

During the same window, an agreed display-label correction needs one known template edit and its existing check. The architect chooses direct execution. Requiring the settlement planning process for that label would consume scarce review time without answering an unresolved question. If the edit reveals that the label also controls a persisted transaction code, the developer stops the direct path and returns that discovery for planning.

Common exam traps

• Mandating a plan for every understood small change.
• Skipping planning because a consequential change touches only one file.
• Treating a file inventory as agreement on compatibility and sequencing.
• Equating plan approval with unrestricted execution permission.
• Assuming every terminal planning session enforces source-edit blocks.

What to remember

Spend planning effort on unresolved approaches, dependencies, and consequential decisions. Give direct work a bounded acceptance target and a trigger for returning to planning. The architect owns the policy and decision owners; the session’s permission configuration determines which actions are actually blocked.

Knowledge check

References

• Anthropic, Best practices for Claude Code
• Anthropic, Choose a permission mode
• Anthropic, Common workflows