docs: add Context Overload anti-pattern (Rusitschka)

- Add "Context Overload" anti-pattern in §9.8 Vibe Coding (line 8746) - Unify plan mode + fresh context + handoffs under phased strategy - Credit Jens Rusitschka ("Vibe Coding, Level 2", Jan 2026) - Cross-reference existing patterns (§2.2, §2.3) - Update reference.yaml with new entries (3 keys) - Add cross-ref in learning-with-ai.md (line 96) Source: https://kickboost.substack.com/p/are-you-still-vibe-coding-or-are Score: 2.5/5 (10% useful packaging, 90% rebranding) Integration: 60 lines added (concise, no duplication) Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-25 13:29:02 +01:00 · 2026-01-25 13:29:02 +01:00 · a858dceda0
commit a858dceda0
parent a39d77f97b
4 changed files with 146 additions and 0 deletions
--- 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
--- 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
--- 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
--- 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)