marketing-shibata50/claude-code-ultimate-guide

Florian BRUNIAUX 9c5d030b11 docs: add dual-instance planning pattern (Jon Williams)

Add vertical separation pattern (planner/implementer) as complement to horizontal scaling (Boris pattern).

## Changes

**Main guide (ultimate-guide.md)**:
- New Section 9.17.1: "Alternative Pattern: Dual-Instance Planning" (~350 lines)
  - When to use (solo devs, spec-heavy, $100-200/month)
  - Setup instructions (2 Claude instances, Plans/ directory)
  - Complete workflow (5 phases: planning, review, implementation, verification, archive)
  - Comparison table (Boris horizontal vs Jon vertical scaling)
  - Cost analysis (2 instances vs correction loops)
  - Agent-ready plan best practices
  - Limitations and tips

**Workflow file (workflows/dual-instance-planning.md)**:
- Full workflow guide (~750 lines)
- Complete example (JWT auth implementation)
- Plan template (ready to copy-paste)
- Cost breakdown and decision matrix
- Troubleshooting and bash aliases

**References updated**:
- machine-readable/reference.yaml: 15 new entries
  - dual_instance_planning, dual_instance_workflow, etc.
  - Line numbers, source attribution, metadata
- guide/workflows/plan-driven.md: Link in See Also section
- README.md: Update evaluation count (46 → 47)

**Evaluation documented**:
- docs/resource-evaluations/jon-williams-dual-instance-pattern.md
  - Full methodology (fetch, analyze, challenge, fact-check)
  - Score progression (2-3/5 → 4/5 after technical-writer challenge)
  - Gap analysis, comparison, integration rationale

## Source
LinkedIn post by Jon Williams (Product Designer, UK)
Date: 2026-02-03
URL: https://www.linkedin.com/posts/thatjonwilliams_ive-been-using-cursor-for-six-months-now-activity-7424481861802033153-k8bu

Context: Transition from Cursor (6 months) to Claude Code with Opus 4.5
Pattern: Vertical separation (Claude Zero: planning/review, Claude One: implementation)
Distinction: Orthogonal to Boris pattern (vertical vs horizontal scaling)

## Stats
- Lines added: ~1,400
- Files modified: 4
- Files created: 2 (workflow + evaluation)
- References added: 15 (reference.yaml)
- Evaluation score: 4/5 (High Value)
- Integration time: ~2.5 hours

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-02-04 10:38:10 +01:00

5.3 KiB

Raw Blame History

Plan-Driven Development

Confidence: Tier 1 — Based on Claude Code's native /plan mode functionality.

Use /plan mode for anything non-trivial. Claude explores the codebase (read-only), then proposes an implementation plan for your approval.

TL;DR
The /plan Workflow
When to Use
Plan File Structure
Integration with Other Workflows
Tips
See Also

TL;DR

1. /plan (or ask complex question)
2. Claude explores codebase (read-only)
3. Claude writes plan to .claude/plans/
4. You review and approve
5. Claude executes

The /plan Workflow

Step 1: Enter Plan Mode

Either use the slash command:

/plan

Or ask a complex question that triggers plan mode automatically:

How should I refactor the authentication system to support OAuth?

Step 2: Claude Explores

In plan mode, Claude:

Reads relevant files
Searches for patterns
Understands existing architecture
CANNOT make any changes

Step 3: Claude Writes Plan

Claude creates a plan file at .claude/plans/[name].md:

# Plan: Refactor Authentication for OAuth

## Summary
Add OAuth support while maintaining existing email/password auth.

## Files to Modify
- src/auth/providers/index.ts (add OAuth provider)
- src/auth/middleware.ts (handle OAuth tokens)
- src/config/auth.ts (OAuth config)

## Files to Create
- src/auth/providers/oauth.ts
- src/auth/providers/google.ts

## Implementation Steps
1. Create OAuth provider interface
2. Implement Google OAuth provider
3. Update middleware to detect token type
4. Add OAuth routes
5. Update config schema

## Risks
- Breaking existing sessions during migration
- Token format differences between providers

Step 4: You Review

Review the plan for:

Completeness (all requirements covered)
Correctness (right approach for your codebase)
Scope (not over-engineering)

Step 5: Approve and Execute

Looks good. Proceed with the plan.

Or request changes:

Modify the plan: also add support for GitHub OAuth, not just Google.

When to Use

Use Plan Mode

Scenario	Why
Multi-file changes	See all affected files upfront
Architecture changes	Validate approach before coding
New features	Ensure complete implementation
Unfamiliar codebase	Let Claude explore first
Risky operations	Review before execution

Skip Plan Mode

Scenario	Why
Single-line fixes	Obvious, low risk
Typo corrections	No planning needed
Simple questions	Exploration, not implementation
Adding comments	Trivial change

Plan File Structure

Plans are stored in .claude/plans/ with auto-generated names.

Typical Plan Sections

# Plan: [Title]

## Summary
[1-2 sentence overview]

## Context
[Why this change is needed]

## Files to Modify
[List of existing files that will change]

## Files to Create
[List of new files]

## Files to Delete
[List of files to remove, if any]

## Implementation Steps
[Ordered list of steps]

## Testing Strategy
[How to verify the changes]

## Risks & Mitigations
[What could go wrong and how to handle it]

## Open Questions
[Things to clarify before proceeding]

Integration with Other Workflows

Plan + TDD

/plan

I need to implement a rate limiter.
Plan the test cases first, then the implementation.

Claude plans both tests and implementation in proper TDD order.

Plan + Spec-First

/plan

Review the Payment Processing spec in CLAUDE.md.
Create an implementation plan that satisfies all acceptance criteria.

Plan + TodoWrite

After plan approval, Claude can break down into todos:

Approved. Create a todo list from this plan and start implementing.

Tips

Be Specific About Scope

# Too vague
/plan
Improve the API

# Better
/plan
Add pagination to the /users endpoint with cursor-based navigation.
Maintain backwards compatibility with existing clients.

Request Plan Modifications

The plan looks good but:
- Add error handling for network failures
- Skip the caching optimization for now
- Include rollback procedure

Use for Architecture Decisions

/plan

I'm considering two approaches for state management:
A) Redux Toolkit
B) Zustand

Explore the codebase and recommend which fits better.

Save Plans for Documentation

Plans in .claude/plans/ serve as decision documentation:

Why certain approaches were chosen
What files were expected to change
Implementation order rationale

5.3 KiB Raw Blame History