Plan Mode in Claude Code: Build a Solid Golang Implementation Plan

Plan Mode in Claude Code: Plan Before the First Line

Mastering plan mode in Claude Code for Golang is what separates a controlled, spec-driven build from a chaotic one. There’s a strong temptation the moment you have a clear spec: ask the AI to generate code immediately. Why not? The spec is ready — just say “implement it” and wait.

But there’s one step that’s often skipped and that dramatically improves output quality: making a plan first. Plan Mode is the phase where you ask Claude Code to produce a detailed implementation plan — which files to create, which interfaces to define, the optimal implementation sequence, and the potential issues — before a single line of code is written.

10.1 Why Planning Before Coding Produces Better Output

Before touching any tooling, it’s worth understanding why planning pays off. When an AI jumps straight to code, its first instinct is to write the most obvious implementation rather than the most correct one for your architecture. A short plan changes that dynamic entirely.

Without a plan, the AI tends to:

• Write the first implementation that comes to mind
• Make architectural decisions that may not be optimal
• Miss dependencies between components that need to exist
• Generate code that then needs refactoring because it doesn’t follow project patterns

With a plan, the workflow flips in your favor:

• You can review and correct direction before investing in code
• The AI knows the right order: interfaces first, implementations second
• Potential problems surface before they become real problems
• Effort estimates become far more accurate

Think of it as “measure twice, cut once” from carpentry — applied to software. The few minutes spent planning are repaid many times over in avoided rework.

10.2 The Prompt That Activates Plan Mode

The plan is only as good as the request that produces it. The prompt below is deliberately structured so Claude Code returns a plan you can actually review, rather than a vague paragraph. Notice how it enumerates exactly which sections the plan must contain and explicitly forbids writing code.

 1Before we start implementation, I want to create a solid plan first.
 2
 3Based on the following spec, create an implementation plan covering:
 4
 51. FILES TO CREATE (new)
 6   - Full file name and path, package name, type, brief description
 7
 82. FILES TO MODIFY (existing)
 9   - Path, what needs to be added or changed, any breaking changes?
10
113. DATABASE CHANGES (if any)
12   - Migration scripts, new indexes, new constraints
13
144. NEW INTERFACES (if any)
15   - Interface names and method signatures
16   - Package where the interface is defined
17
185. IMPLEMENTATION SEQUENCE
19   - Optimal order with dependency consideration
20   - What must finish before others can start
21
226. POTENTIAL ISSUES
23   - What might be complex or need extra attention
24   - Dependencies on existing code to check
25   - Questions to confirm before implementation
26
27DO NOT write implementation now — plan only.
28I'll review the plan first, confirm, then proceed to implementation.
29
30---
31Spec: @specs/order/cancel-order.md
32Reference code patterns:
33- Handler: internal/delivery/http/handler/order_handler.go
34- Usecase: internal/usecase/order/create_order.go

The takeaway: the two most important lines are “DO NOT write implementation now” and the reference-code section. The first keeps the review honest, and the second anchors the plan to patterns that already exist in your codebase instead of generic best practices.

10.3 Example Plan Mode Output: Cancel Order

To make this concrete, imagine we hand Claude the cancel-order spec for our Santekno Shop. The plan it returns is not prose — it is a structured document you can scan in a minute. The block below is a compressed shape of that output so you can see what “good” looks like.

 1IMPLEMENTATION PLAN: Cancel Order
 2Spec: specs/order/cancel-order.md v1.3
 3
 41. FILES TO CREATE
 5   - internal/usecase/order/cancel_order.go (usecase + Execute)
 6   - internal/usecase/order/cancel_order_test.go (unit tests, AC/EC cases)
 7
 82. FILES TO MODIFY
 9   - internal/domain/order/entity.go (StatusCancelled, CanBeCancelled)
10   - internal/domain/order/repository.go (new interface methods) [breaking mocks]
11   - internal/repository/postgres/order_repository.go (implement methods)
12   - internal/delivery/http/handler/order_handler.go (CancelOrder)
13   - internal/delivery/http/router/router.go (DELETE route)
14
153. DATABASE CHANGES
16   - CHECK constraint may need a CANCELLED value — VERIFY FIRST
17
184. NEW INTERFACES
19   - OrderCancelledPublisher.PublishOrderCancelled(ctx, orderID, userID)
20
215. IMPLEMENTATION SEQUENCE
22   entity -> repository interface -> repository impl -> usecase -> tests -> handler -> router
23
246. POTENTIAL ISSUES
25   - Mocks must be regenerated after the interface change
26   - Clock mocking needed for the 15-minute window test
27   - Concurrent cancel (EC1) likely needs an integration test

The takeaway: a good plan clearly lists new files with their purpose, flags every modified file and its breaking impact, defines new interfaces with signatures, gives an ordered sequence, and — critically — ends with the questions that must be answered before coding. If any of those six sections is missing, the plan isn’t ready.

One step that is easy to skip: write the plan to a file instead of leaving it in the chat history.

1Save the plan above verbatim to docs/plans/cancel-order-2025-07-15.md.
2Add a header with the spec it references, the date, and a status
3(DRAFT/APPROVED). Do not change the plan content.

This is not about tidiness. A saved plan can be referenced from the implementation prompts — in article 12 every prompt opens by pointing at both the spec and this plan, so the generated code traces back to an agreed plan rather than to whatever the person typing remembered. A plan that only lives in chat history cannot do that. File location and format are covered in section 10.12.

10.4 Reviewing the Plan: How to Respond

A plan is a conversation starter, not a final answer. The most valuable thing you do in Plan Mode is respond precisely. The two response patterns below cover the majority of real cases — confirming with corrections, and drilling into a single risky decision.

The first pattern answers the plan’s open questions and adds any missing steps in one message:

 1Answers to your questions:
 21. StatusCancelled doesn't exist yet in entity.go
 32. Mock exists, generated with mockgen — regenerate after the interface update
 43. Yes, inject a clock interface for testability
 54. EC1 will be an integration test
 6
 7Corrections:
 8- Add a step: regenerate the mock after the interface update
 9- Add a step: update main.go DI wiring
10
11Proceed with the corrected plan.

The second pattern pauses on one architectural fork before committing:

1One question before proceeding:
2For CancelWithStockRestore — is this better as a repository method
3or should we introduce a TransactionManager pattern?
4
5Consider that we may need the same pattern for other operations
6that also require multi-table atomic writes.

The takeaway: never approve a plan you don’t fully understand. A single clarifying message now is far cheaper than a refactor later, and it teaches Claude the conventions you care about for the rest of the session.

10.5 Using the Plan as an Implementation Checklist

Once the plan is approved, convert it into something you can track. A plan you can’t check off is just documentation; a checklist is a live progress indicator. The markdown below turns the approved plan into per-layer tasks with commit references.

 1# Implementation Checklist: Cancel Order
 2Spec: specs/order/cancel-order.md v1.3
 3
 4### Domain Layer
 5- [x] Update entity.go — add StatusCancelled (commit: abc123)
 6- [ ] Update repository.go — add interface methods
 7- [ ] Update/create errors.go
 8
 9### Repository Layer
10- [ ] Implement GetByIDAndUserID and CancelWithStockRestore
11
12### Usecase Layer
13- [ ] Create cancel_order.go
14- [ ] Create cancel_order_test.go
15- [ ] Regenerate mock after the interface update
16
17### Delivery Layer
18- [ ] Update order_handler.go
19- [ ] Update router.go
20
21### Wiring
22- [ ] Update main.go dependency injection
23
24### Verification
25- [ ] go test ./... -race → all pass
26- [ ] go vet ./... → clean
27- [ ] Spec compliance: ./scripts/spec-audit.sh specs/order/cancel-order.md

The takeaway: grouping tasks by layer (domain → repository → usecase → delivery → wiring → verification) mirrors the dependency order, so working top-to-bottom naturally keeps the build green at every checkpoint.

10.6 Plan Mode for Refactoring

Refactoring plans need extra caution because the goal is zero behavioral change. The prompt below forces the plan to treat safety — testability, small commits, rollback — as first-class requirements rather than afterthoughts.

 1I want to refactor error handling in OrderHandler.
 2Currently each handler has its own switch statement for error mapping.
 3I want to centralize this into one middleware or helper.
 4
 5Create a refactoring plan that:
 61. Identifies all places that need to change
 72. Defines the new interface/abstraction
 83. Chooses a strategy: big bang or incremental?
 94. Ensures each refactoring step remains testable
105. Assesses risk: what could break?
116. Includes a rollback plan: how to revert if needed?
12
13IMPORTANT CONSTRAINTS:
14- Zero behavioral change — only structure changes, not behavior
15- Every commit must be green (all tests pass)
16- No PR larger than 200 lines changed

The takeaway: the three constraints at the bottom are what keep a refactor from silently becoming a rewrite. Spelling them out makes the AI plan in reversible, testable slices.

10.7 Plan Mode vs Direct Implementation: When to Use Each

Plan Mode is not free, so it shouldn’t be mandatory for every change. The table below is a quick decision guide for when the planning overhead pays off versus when it just slows you down.

The takeaway: the trigger is complexity and blast radius, not personal preference. When a change touches many files or has concurrency risk, the plan is cheap insurance; for a one-line fix that follows an existing pattern, skip straight to implementation.

10.8 Plan for Database Migration

Database changes carry their own risks — backward compatibility, downtime, and existing rows. The prompt below asks the plan to address all three explicitly instead of just producing a migration file.

 1Create a database migration plan for the "order cancellation reason" feature.
 2
 3Requirements:
 4- Optional reason (string, max 500 chars) on cancelled orders
 5- Reason can be set at cancel time or within 24 hours
 6- Audit trail: who set the reason and when
 7
 8Plan must include:
 91. Migration script (forward and rollback)
102. Impact on existing queries to update
113. Go struct changes
124. Repository method changes
135. Safe deployment approach (zero downtime)
14
15Consider:
16- Is this backward compatible? (existing rows without reason → NULL ok?)
17- Does the reason field need an index?
18- Any data migration for existing rows?

The takeaway: a migration plan is judged less by its CREATE TABLE line and more by its rollback path and backward-compatibility answer. Forcing those questions up front prevents a broken deploy on production data.

10.9 Generating Jira/Linear Tasks from a Plan

An approved plan can feed your project tracker directly. The prompt below converts plan items into ticket-shaped tasks with titles, estimates, and dependencies — ready to paste into Jira or Linear.

 1Convert the following implementation plan into tasks ready for Jira/Linear.
 2
 3Format for each task:
 4**Title:** [max 60 chars, actionable]
 5**Description:** [2-3 sentence context + brief acceptance criteria]
 6**Labels:** [domain/repository/usecase/handler/test]
 7**Estimate:** [S/M/L — Small < 2hr, Medium 2-4hr, Large > 4hr]
 8**Dependencies:** [which tasks must complete first]
 9
10Plan: @docs/plans/cancel-order-2025-07-15.md

The takeaway: because the plan already knows the sequence and dependencies, the generated tickets arrive pre-ordered — sprint planning becomes a copy-paste rather than a re-derivation.

10.10 Plan for Parallel Development

When two developers share a feature, the plan’s job is to define the seams before anyone starts typing. The prompt below asks Claude to identify the interfaces to agree on first and the parallelizable work.

 1Two developers will pair-implement cancel order:
 2Developer A: domain layer + usecase layer
 3Developer B: repository layer + handler layer
 4
 5Create a plan that:
 61. Defines the interfaces to agree on first (before each starts)
 72. Divides tasks that can be done in parallel
 83. Identifies integration points needing coordination
 94. Suggests a testing order (who mocks whom)
10
11Goal: minimize blocking between developers.

The takeaway: agreeing on interface signatures first lets both developers mock each other and work in parallel — the plan’s real output here is a contract, not a task list.

10.11 Plan Iteration: Multiple Rounds

A plan doesn’t have to be produced in one shot. Complex features benefit from layered rounds — broad first, then deep on the riskiest part, then a final safety review. The prompt below is the “deep dive” round for the most critical method.

 1From the plan, let's detail CancelWithStockRestore in the repository layer.
 2
 3This is the most critical operation because:
 4- It must be atomic (data integrity)
 5- It has a concurrent access concern (EC1)
 6- Partial failure must roll back completely (EC4)
 7
 8Create a detailed plan for this method:
 91. Exact SQL queries with parameters
102. Transaction flow
113. Error handling for each step
124. Test cases needed
135. Potential performance issues and solutions

The takeaway: reserve the deep-dive round for the one or two operations where correctness is hardest — atomic writes, concurrency, rollback — and leave the routine parts at the high level.

10.12 Saving the Plan in Git

A plan is a design artifact and deserves to live alongside the spec and code. The commands below snapshot the approved plan into the repository so future readers understand why the implementation looks the way it does.

1# Optional: commit the plan as documentation
2mkdir -p docs/plans
3cat > docs/plans/cancel-order-2025-07-15.md << 'EOF'
4[plan content from Claude]
5EOF
6git add docs/plans/cancel-order-2025-07-15.md
7git commit -m "plan: implementation plan for cancel order feature"

The takeaway: committing the plan turns a throwaway chat into permanent project memory — six months later, the plan explains the decisions the diff alone can’t.

10.13 Dependency Injection Is Often Missed

The single most common gap in AI-generated plans is wiring. Claude will happily plan the usecase and forget the main.go that constructs it. The prompt below closes that gap by asking for the DI change explicitly, as a diff.

1Please also plan what needs to be updated in cmd/api/main.go
2for the new cancel order usecase dependency injection.
3
4Current DI pattern: @cmd/api/main.go
5
6Show it as a code diff (before/after), not the full file.

The takeaway: always ask “what changes in main.go?” as its own line item — otherwise you’ll finish a green build that fails to boot because nothing constructs the new usecase.

10.14 Plan Validation: A Second Opinion

Before you commit to a plan, it’s worth asking the AI to critique its own work from a fresh perspective. The prompt below reframes Claude as a battle-scarred senior engineer looking for what’s missing.

 1Review this implementation plan as a senior Go engineer who has
 2maintained a Go codebase for 3 years and debugged production issues.
 3
 4Identify:
 51. What might be missing?
 62. Which implementation sequence could be optimized?
 73. Any non-obvious potential issues?
 84. Any unnecessary steps (over-engineering)?
 9
10Plan: @docs/plans/cancel-order-2025-07-15.md

The takeaway: a “second opinion” pass routinely catches the mock regeneration, the missing index, or the over-engineered abstraction — cheap to fix on paper, expensive to fix in code.

10.15 Effort Estimation from a Plan

A concrete plan also produces a far more honest estimate than a gut feeling. The prompt below asks for per-task hours with a confidence level, which exposes where the real risk hides.

 1Based on the cancel order implementation plan, create a realistic effort estimate:
 2
 3For each task:
 4- Estimate in hours (not story points)
 5- Confidence: high (done this before) / medium / low (new territory)
 6- Potential blocker that could delay it
 7
 8Assumptions:
 9- Engineer familiar with the codebase (3+ months on the project)
10- Unit tests written alongside code, not after
11- Code review by 1 senior engineer
12
13Output format:
14| Task | Hours | Confidence | Potential Blocker |
15|------|-------|------------|-------------------|
16
17Provide a total and a buffer recommendation.

The takeaway: tasks marked “low confidence” are where your buffer should go — the estimate’s value is in flagging uncertainty, not in the total itself.

10.16 Plan Mode for Onboarding New Developers

Plan Mode is a surprisingly good teaching tool. Asking a new engineer to produce a plan before coding forces them to read the codebase and surface their confusion early. The prompt below structures that onboarding exercise.

 1[For a new developer who will implement cancel order]
 2
 3Use this spec to create an implementation plan:
 4- specs/order/cancel-order.md
 5
 6Before coding, read and understand:
 7- internal/usecase/order/create_order.go (same pattern)
 8- internal/domain/order/entity.go (domain types)
 9- CLAUDE.md (conventions)
10
11Then create an implementation plan and discuss it with a senior engineer
12before writing any code.
13
14Your plan must answer:
151. What files will you create/modify?
162. What new interfaces will you define?
173. What test cases will you write?
184. What don't you understand and needs discussion?

The takeaway: the fourth question — “what don’t you understand?” — is the point. A new developer’s plan is most valuable for the questions it raises, not the tasks it lists.

10.17 Plan for Legacy Code Integration

Adding a feature to legacy code is a different problem: you must decide how much to refactor versus how much to tolerate. The prompt below makes that trade-off an explicit part of the plan.

 1I need to add cancel order to an existing legacy codebase.
 2The codebase uses different patterns:
 3- Handlers query the DB directly (no usecase layer)
 4- Inconsistent error handling
 5- No unit tests
 6
 7The plan must consider:
 81. Refactor existing code first, or add the feature with a new pattern?
 92. If a new pattern: how do old and new patterns coexist?
103. Minimum refactoring to let the new feature follow best practice
114. A strategy to introduce tests incrementally
12
13Goal: deliver the new feature without a big-bang refactor.

The takeaway: in legacy code, the plan’s key decision is coexistence — how new and old patterns live side by side — so you can ship value without pausing for a rewrite.

10.18 Tips & Gotchas

A few hard-won habits and traps are worth internalizing before Plan Mode becomes second nature.

• Tip 1: Strictly separate Plan Mode and Implementation Mode — explicitly instruct Claude not to write implementation during planning.
• Tip 2: Ask questions about the plan before approving — it’s cheaper to clarify now than to refactor later.
• Tip 3: Save plans alongside specs and code — they document how you decided on an implementation.
• Tip 4: Update the plan when implementation surfaces something unexpected — don’t silently “work around” it.
• Gotcha 1: A plan that’s too detailed becomes a straitjacket — plan the “what” and the “sequence”, not every line.
• Gotcha 2: Claude may plan without reading existing code — always provide reference patterns explicitly.
• Gotcha 3: Dependency injection is routinely forgotten — always ask about main.go updates.
• Gotcha 4: Parallel work without a plan means merge conflicts — an explicit interface contract prevents them.

The takeaway: most of these reduce to one discipline — treat the plan as a reviewable artifact, keep it honest, and keep it current.

10.19 A Reusable Plan Mode Template

To avoid rewriting the prompt every time, keep a snippet on hand. The template below is the distilled, reusable form of everything above — paste it, attach the spec, and you’re planning.

 1## PLAN MODE PROMPT TEMPLATE
 2
 3Before implementation, create a plan covering:
 4
 51. NEW FILES: path, package, type, purpose (1-2 sentences)
 62. MODIFIED FILES: what changes, breaking or not?
 73. DB CHANGES: migrations, indexes, constraints
 84. NEW INTERFACES: method signatures, which package
 95. IMPLEMENTATION SEQUENCE: ordered steps with dependencies
106. POTENTIAL ISSUES: complexity, external deps, questions to confirm
11
12DO NOT write any implementation code.
13Ask clarifying questions if anything is ambiguous.
14After I confirm the plan, THEN we proceed to implementation.
15
16Spec: @specs/order/cancel-order.md
17Reference patterns: [list relevant existing files]

The takeaway: standardizing the prompt makes your plans consistent across features and teammates — the same six sections every time means reviews get faster and gaps get rarer.

10.20 Summary

Plan Mode is a small investment with a large return: less rework, fewer architectural bugs, and a far more focused implementation. A good plan covers new and modified files, database changes, new interfaces, an ordered implementation sequence, and the potential issues that could bite you.

The effective workflow is consistent: generate the plan from the spec, review and correct it, answer the clarifying questions, approve it, and only then start implementing. Plan Mode becomes mandatory for new complex features, changes touching five or more files, anything with concurrency or transaction concerns, and work handed to a new developer. As a bonus, the same plan gives you an implementation checklist, a more accurate estimate, and ready-to-file tickets.

In the next article we break the plan down further — turning abstract plan items into Golang work units you can implement one at a time, with a verifiable result at every step.