marketing-shibata50/claude-code-ultimate-guide

Florian BRUNIAUX fd17414abb docs: add AI productivity research, trust calibration, and exploration workflow

## New Content

### Trust & Verification (ultimate-guide.md)
- Section 1.7 "Trust Calibration: When and How Much to Verify" (~155 lines)
  - Research-backed stats (ACM, Veracode, CodeRabbit, Cortex.io)
  - Verification spectrum by code type
  - Solo vs Team strategies with workflow diagrams
  - "Prove It Works" checklist
- New pitfall: "Trust AI output without proportional verification"
- CLAUDE.md size guideline: 4-8KB optimal, >16K degrades coherence

### AI Productivity (learning-with-ai.md)
- Section "The Reality of AI Productivity" (~55 lines)
  - Productivity curve phases (Wow Effect → Targeted Gains → Plateau)
  - High-gain vs low/negative-gain task categorization
  - Team success factors
- Productivity trajectory table by pattern (Dependent/Avoidant/Augmented)
- 5 new sources (GitHub, McKinsey, Stack Overflow, Uplevel, DORA)

### Session Limits (architecture.md)
- "Session Degradation Limits" section
  - Turn limits (15-25), token thresholds (80-100K)
  - Success rates by scope (1-3 files: ~85%, 8+ files: ~40%)

### Exploration Workflow
- NEW: guide/workflows/exploration-workflow.md
  - Anti-anchoring prompts, 3-5 approaches pattern
- iterative-refinement.md: Script Generation Workflow (3-7 iteration pattern)
- anchor-catalog.md: Anti-Anchoring Techniques, Exploration/Iteration Prompts

### Reference Updates
- adoption-approaches.md: Empirical data section
- reference.yaml: New deep_dive entries, updated line numbers

Sources: MetalBear engineering blog, arXiv studies, Addy Osmani (Jan 2026)

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

2026-01-19 19:16:33 +01:00

5 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 KiB Raw Blame History