diff --git a/CHANGELOG.md b/CHANGELOG.md index 5eaf798..51b196e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,46 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added +- **Vibe Coding: Context Overload Anti-Pattern** (`guide/ultimate-guide.md:8746`) + - New subsection in §9.8 Vibe Coding documenting the "context overload" anti-pattern + - Identifies symptoms: big-bang context dumps, 5K+ line prompts, performance degradation + - Phased context strategy: Exploration (plan mode) → Implementation (focused) → Fresh start (handoffs) + - Unifies 3 existing patterns (plan mode, fresh context, session handoffs) under explicit framework + - Attribution to Jens Rusitschka ("Vibe Coding, Level 2", Jan 2026) + - Practical workflow examples with bash commands + - Cross-references to §2.2 (Fresh Context Pattern, line 1525), §2.3 (Plan Mode, line 2100) + - Total additions: ~60 lines +- **machine-readable/reference.yaml**: Added `vibe_coding_context_overload`, `vibe_coding_context_overload_source`, `vibe_coding_phased_strategy` +- **guide/learning-with-ai.md:96**: Added cross-reference from "Vibe Coding Trap" to new anti-pattern section + +- **Product Manager FAQ entry** (`guide/ultimate-guide.md:14335`) + - Minimal FAQ entry (28 lines) addressing PM workflows with Claude Code + - Distinction between code-adjacent PMs (technical validation) and non-coding PMs (strategy/research) + - Tool stack example from Stilyan Mitrev (Head of Product, StableLab): Granola, Wispr Flow, ChatPRD, v0 + - Reality check: "emerging area with limited community validation" (1 practitioner report, tool not adopted long-term) + - Guidance: CLI appropriate for technical PMs, Claude Desktop better for non-technical workflows + - Cross-references: AI Ecosystem Guide, Cowork Guide, Design-to-Code Workflow + - Source: [LinkedIn article (Jan 23, 2026)](https://www.linkedin.com/pulse/how-i-currently-ai-product-manager-stilyan-mitrev-ycvvf/) + - Decision: Minimal integration (proportional to source), invite community contribution + - Reference YAML: Added `faq_product_managers: 14335` + +- **MCP architecture visual diagram** (`guide/architecture.md:513`, SVG) + - 7-layer security model showing LLM/MCP Server/Tools separation + - Visual representation of "No Data Access" (LLM layer) and "Hidden From AI" (Real Systems layer) + - Beginner-friendly introduction to MCP architecture with color-coded security boundaries + - Design inspired by Dinesh Kumar's LinkedIn visualization, recreated as original work under Apache-2.0 + - Includes workflow diagram (5 steps: User Asks → LLM Thinks → MCP Controls → Tools Execute → Safe Result) + - Golden rule banner: "LLM Thinks → MCP Controls → Tools Execute → Data Locked" +- **External orchestration systems documentation** (`guide/ai-ecosystem.md:808`) + - Gas Town (Steve Yegge): Multi-agent workspace manager using Claude Code instances + - multiclaude (dlorenc): Self-hosted multi-agent Claude Code spawner + - agent-chat (Justin Abrahms): Real-time monitoring UI for orchestrator communications + - Architecture patterns for transposing monitoring to native Claude Code workflows + - Security and cost warnings for experimental orchestration systems +- **machine-readable/reference.yaml**: Added `external_orchestrators` section with Gas Town, multiclaude, agent-chat +- **machine-readable/reference.yaml**: Added `architecture_mcp_visual` (SVG diagram reference) +- **guide/observability.md**: Cross-reference to multi-agent orchestration monitoring + ## [3.11.7] - 2026-01-25 ### Added diff --git a/guide/learning-with-ai.md b/guide/learning-with-ai.md index 3528e60..a90bdfd 100644 --- a/guide/learning-with-ai.md +++ b/guide/learning-with-ai.md @@ -93,6 +93,8 @@ Term coined by [Andrej Karpathy](https://x.com/karpathy/status/18861921848081493 **Antidote:** The UVAL Protocol (§5) forces understanding before acceptance. +> **Related**: For context management strategies that prevent vibe coding chaos, see [Anti-Pattern: Context Overload](./ultimate-guide.md#anti-pattern-context-overload) in the main guide (§9.8). + --- ## The Reality of AI Productivity diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md index c9632bd..3e36562 100644 --- a/guide/ultimate-guide.md +++ b/guide/ultimate-guide.md @@ -8743,6 +8743,58 @@ Claude: [Provides minimal example for exploration] 3. **Focus on learning**: Understand the approach 4. **Signal clearly**: "This is vibe code, not for production" +#### Anti-Pattern: Context Overload + +[Jens Rusitschka](https://kickboost.substack.com/p/are-you-still-vibe-coding-or-are) identifies "context overload" as the primary failure mode of vibe coding: dumping entire codebases into context, hoping Claude will figure it out. + +**Symptoms:** +- Pasting 5K+ lines of code in first prompt +- "Read the entire repo and implement X" +- Expecting Claude to maintain context across 20+ file changes +- Performance degradation after context pollution (see §2.2 Fresh Context Pattern) + +**Why it fails:** +- Attention dilution across too many files and concerns +- Lost architectural reasoning in noise +- Failed attempts accumulate, further degrading quality +- Context bleeding between unrelated tasks + +**The Phased Context Strategy:** + +Instead of big-bang context dump, use a **staged approach** that leverages Claude Code's native features: + +| Phase | Tool | Purpose | Context Size | +|-------|------|---------|--------------| +| 1. Exploration | `/plan` mode | Read-only analysis, safe investigation | Controlled (plan writes findings) | +| 2. Implementation | Normal mode | Execute planned changes | Focused (plan guides scope) | +| 3. Fresh Start | Session handoff | Reset when context >75% | Minimal (handoff doc only) | + +**Practical workflow:** + +```bash +# Phase 1: Exploration (read-only, safe) +/plan +You: "How should I refactor the auth system for OAuth?" +Claude: [explores codebase, writes plan to .claude/plans/oauth-refactor.md] +/execute # exit plan mode + +# Phase 2: Implementation (focused context) +You: "Execute the plan from .claude/plans/oauth-refactor.md" +Claude: [reads plan, implements in focused scope] + +# Phase 3: Fresh start if needed (context >75%) +You: "Create session handoff document" +Claude: [writes handoff to claudedocs/handoffs/oauth-implementation.md] +# New session: cat claudedocs/handoffs/oauth-implementation.md | claude -p +``` + +**Cross-references:** +- Full `/plan` workflow: See [§2.3 Plan Mode](#23-plan-mode) (line 2100) +- Fresh context pattern: See [§2.2 Fresh Context Pattern](#22-fresh-context-pattern) (line 1525) +- Session handoffs: See [Session Handoffs](#session-handoffs) (line 2278) + +**The insight:** Rusitschka's "Vibe Coding, Level 2" is Claude Code's native workflow — it just needed explicit framing as an anti-pattern antidote. Plan mode prevents context pollution during exploration, fresh context prevents accumulation during implementation, and handoffs enable clean phase transitions. + ### Skeleton Projects Skeleton projects are minimal, working templates that establish patterns before full implementation. @@ -14332,6 +14384,33 @@ Common misconceptions we've seen: **Final note**: This comparison reflects Jan 2026 state of both tools. Both are evolving rapidly. Check official documentation for latest capabilities. +### Can Product Managers use Claude Code? + +**Short answer**: Yes, but consider your primary workflow first. + +**Code-adjacent PMs** (reviewing technical specs, PRDs, architecture feasibility): +- ✅ Claude Code CLI is appropriate for technical validation workflows +- Example: Granola meeting notes → ChatPRD generation → Claude Code refinement +- Use case: Auditing technical feasibility, generating specs from PRDs + +**Non-coding PMs** (strategy, research, stakeholder management): +- ⚠️ Claude Code CLI overhead not justified +- ✅ Better fit: Claude Desktop (see [Cowork Guide](https://github.com/FlorianBruniaux/claude-cowork-guide)) +- Use case: Research synthesis, stakeholder communication, roadmap planning + +**Tool Stack Example** (via [Stilyan Mitrev, Head of Product StableLab](https://www.linkedin.com/pulse/how-i-currently-ai-product-manager-stilyan-mitrev-ycvvf/)): +- Meeting capture: Granola + Wispr Flow (dictation) +- PRD generation: ChatPRD → Claude Code review +- UI prototyping: v0 → Claude Code feasibility check +- Workflow pattern: Base context project + specialized projects per domain + +**Reality check**: PM workflows with Claude Code are an **emerging area** with limited community validation. We currently have 1 practitioner report (the source practitioner noted they tried Claude Code but didn't adopt it long-term). If you're a PM using Claude Code successfully, [contribute your workflow](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/discussions) to help the community. + +**See also**: +- [AI Ecosystem Guide](ai-ecosystem.md) — Complementary tools (Granola, Wispr Flow, ChatPRD, v0) +- [Cowork Guide](https://github.com/FlorianBruniaux/claude-cowork-guide) — Claude Desktop for non-technical PMs +- [Design-to-Code Workflow](workflows/design-to-code.md#for-product-managers) — PM perspective on Figma MCP + --- ## About This Guide diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml index d956be3..d5d73df 100644 --- a/machine-readable/reference.yaml +++ b/machine-readable/reference.yaml @@ -46,6 +46,9 @@ deep_dive: learning_capture_hook: "examples/hooks/bash/learning-capture.sh" # Anti-patterns vibe_coding_trap: "guide/learning-with-ai.md:81" + vibe_coding_context_overload: 8746 + vibe_coding_context_overload_source: "Jens Rusitschka, 'Vibe Coding, Level 2' (Jan 2026)" + vibe_coding_phased_strategy: 8760 # AI Traceability & Attribution (guide/ai-traceability.md) - Added 2026-01-24 ai_traceability_guide: "guide/ai-traceability.md" ai_traceability_why: "guide/ai-traceability.md:25" @@ -80,6 +83,7 @@ deep_dive: architecture_subagents: "guide/architecture.md:315" architecture_permissions: "guide/architecture.md:385" architecture_mcp: "guide/architecture.md:506" + architecture_mcp_visual: "guide/images/mcp-architecture-diagram.svg" architecture_philosophy: "guide/architecture.md:746" # Main guide (guide/ultimate-guide.md) - Updated 2026-01-20 installation: 196 @@ -241,6 +245,26 @@ deep_dive: multi_instance_implementation: 9934 multi_instance_monitoring: 10016 multi_instance_decision_matrix: 10144 + # External orchestration systems + external_orchestrators: + gas_town: + repo: "https://github.com/steveyegge/gastown" + author: "Steve Yegge" + description: "Multi-agent workspace manager using Claude Code instances" + status: "Experimental (Jan 2026)" + guide_section: "guide/ai-ecosystem.md:850" + multiclaude: + repo: "https://github.com/dlorenc/multiclaude" + author: "dlorenc" + description: "Self-hosted multi-agent Claude Code spawner (tmux + git worktrees)" + status: "Active development (Jan 2026, 383 stars)" + guide_section: "guide/ai-ecosystem.md:850" + agent_chat: + repo: "https://github.com/justinabrahms/agent-chat" + author: "Justin Abrahms" + description: "Real-time monitoring UI for Gas Town and multiclaude (SSE + SQLite)" + status: "Early preview (Jan 2026, v0.2.0)" + guide_section: "guide/ai-ecosystem.md:850" # Section 9.18 - Codebase Design for Agent Productivity codebase_design_agents: 9976 codebase_design_source: "https://marmelab.com/blog/2026/01/21/agent-experience.html" @@ -291,6 +315,7 @@ deep_dive: appendix_a_file_locations: 14087 appendix_b_faq: 14263 faq_clawdbot_vs_claudecode: 14265 + faq_product_managers: 14335 # ════════════════════════════════════════════════════════════════ # DECISION TREE (most important - en premier)