diff --git a/CHANGELOG.md b/CHANGELOG.md index 83f8d08..5eaf798 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Added +## [3.11.7] - 2026-01-25 + +### Added + +- **ClawdBot vs Claude Code FAQ** (`guide/ultimate-guide.md:14263`) + - New Appendix B: FAQ section addressing community confusion between ClawdBot and Claude Code + - Comprehensive comparison table (9 dimensions): interface, audience, use cases, pricing, architecture + - Decision tree: when to choose each tool, when to use both together + - Early warning note in "Before You Start" section (line 33) to alert readers immediately + - Community misconceptions addressed: different architectures, complementary not competitive + - Resources: ClawdBot website, GitHub repo, setup guides + - Context: Jan 2026 buzz on X/Reddit created confusion ("dominated X timeline over 1-2 months") + - Related: ClawdBot is self-hosted chatbot for messaging apps (personal automation, smart home); Claude Code is CLI for developers (terminal/IDE, code generation) + - Total additions: +76 lines in guide, +3 lines in reference.yaml + +- **Architecture Diagrams as Context (Advanced Pattern)** (`guide/ai-ecosystem.md:1379`) + - Pattern documentation for using architecture diagrams in OOP codebases + - MCP tools reference: Archy MCP, Mermaid MCP, Blueprint MCP (ArcadeAI) + - ACM 2024 research validation for LLM OOP limitations + - Recommended workflow: Serena → Archy MCP → Manual inline Mermaid + - Use cases: OOP codebases >20 modules, Java/Spring projects with deep polymorphism + - Source: [LinkedIn discussion (Jan 2026)](https://www.linkedin.com/posts/tigraff_uml-claude-wibecoding-activity-7420595633826258944-gGO5) + - Evaluation report: `claudedocs/resource-evaluations/uml-oop-diagrams-eval.md` + - **AI Traceability & Attribution Guide** (`guide/ai-traceability.md`) - Comprehensive documentation on AI code attribution and disclosure (~500 lines) - LLVM "Human-in-the-Loop" policy (January 2026): `Assisted-by:` trailer standard @@ -35,6 +59,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - 14 new entries for AI traceability topics - Template locations for disclosure files +- **Architecture Diagrams as Context (Advanced Pattern)** (`guide/ai-ecosystem.md:1379`) + - Pattern documentation for using architecture diagrams in OOP codebases + - MCP tools reference: Archy MCP, Mermaid MCP, Blueprint MCP (ArcadeAI) + - ACM 2024 research validation for LLM OOP limitations + - Recommended workflow: Serena → Archy MCP → Manual inline Mermaid + - Use cases: OOP codebases >20 modules, Java/Spring projects with deep polymorphism + - Source: [LinkedIn discussion (Jan 2026)](https://www.linkedin.com/posts/tigraff_uml-claude-wibecoding-activity-7420595633826258944-gGO5) + - Evaluation report: `claudedocs/resource-evaluations/uml-oop-diagrams-eval.md` + ## [3.11.6] - 2026-01-24 ### Added diff --git a/guide/ai-ecosystem.md b/guide/ai-ecosystem.md index 8b74839..8104bb8 100644 --- a/guide/ai-ecosystem.md +++ b/guide/ai-ecosystem.md @@ -1376,6 +1376,76 @@ Claude Code automatically reads files as needed, but external tools exist for: - Addy Osmani: [My AI Coding Workflow in 2026](https://addyosmani.com/blog/ai-coding-workflow/) — Discusses context packing as part of a broader AI development workflow +### Architecture Diagrams as Context (Advanced Pattern) + +For large OOP codebases, research confirms LLMs struggle with polymorphism and dependency reasoning when processing files in chunks ([ACM 2024](https://dl.acm.org/doi/10.1145/3639474.3640052): "LLMs Still Can't Avoid Instanceof"). + +**Problem**: File chunking loses structural relationships (class hierarchies, interface implementations, cross-module dependencies). + +**Solution**: Include architecture diagrams in project context to provide explicit relationships. + +#### Approaches + +| Approach | Maintenance | Token Cost | Best For | +|----------|-------------|------------|----------| +| **Archy MCP** | Zero (auto-gen) | On-demand | GitHub repos with class hierarchies | +| **Inline Mermaid** | Manual | 200-500 tokens | Custom architectural views | +| **PlantUML ref** | Manual | Minimal | Enterprise/IDE integration | + +#### MCP Tools for Architecture Visualization + +**Archy MCP** (phxdev1, April 2025): +- Auto-generates Mermaid from GitHub repos or text descriptions +- Supports: flowcharts, class diagrams, sequence diagrams +- URL: [pulsemcp.com/servers/phxdev1-archy](https://www.pulsemcp.com/servers/phxdev1-archy) + +**Mermaid MCP** (hustcc, 61.4K users): +- Custom themes, background colors +- Real-time rendering + +**Blueprint MCP** (ArcadeAI): +- Text descriptions → technical diagrams +- Async job management + +#### Inline Example (CLAUDE.md) + +```markdown +## Architecture Overview + +\`\`\`mermaid +classDiagram + class UserService { + +authenticate() + +getProfile() + } + class AuthProvider { + <> + +validate() + } + UserService --> AuthProvider +\`\`\` +``` + +#### When to Use + +- OOP codebases >20 modules with complex inheritance +- Java/Spring projects with deep polymorphism +- When Serena symbol overview is insufficient + +#### Recommended Workflow + +1. **Try Serena first**: `get_symbols_overview` + `find_symbol` (zero maintenance) +2. **If insufficient**: Use **Archy MCP** to auto-generate class diagrams +3. **Last resort**: Manual inline Mermaid for custom views + +#### Key Insight + +> "Context structure matters more than context size" — Explicit relationships improve LLM reasoning on OOP architectures. + +**Source**: [LinkedIn discussion (Jan 2026)](https://www.linkedin.com/posts/tigraff_uml-claude-wibecoding-activity-7420595633826258944-gGO5) + +**Note**: Pattern reported on Java/Spring project. Not validated at scale. Alternative Serena + grepai achieves similar results with zero maintenance. + --- ## Alternative Providers (Community Workarounds) diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml index 632cfd8..3fddf0a 100644 --- a/machine-readable/reference.yaml +++ b/machine-readable/reference.yaml @@ -4,7 +4,7 @@ # Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code version: "3.11.6" -updated: "2026-01-24" +updated: "2026-01-25" # ════════════════════════════════════════════════════════════════ # DEEP DIVE - Line numbers in guide/ultimate-guide.md @@ -260,6 +260,14 @@ deep_dive: ai_ecosystem_goose: "guide/ai-ecosystem.md:1116" ai_ecosystem_goose_comparison: "guide/ai-ecosystem.md:1132" ai_ecosystem_context_packing: "guide/ai-ecosystem.md:1208" + # Architecture Diagrams as Context (advanced pattern) - Added 2026-01-25 + architecture_diagrams_input: "guide/ai-ecosystem.md:1379" + architecture_diagrams_mcp_tools: + - "Archy MCP: https://www.pulsemcp.com/servers/phxdev1-archy" + - "Mermaid MCP: 61.4K users" + - "Blueprint MCP (ArcadeAI)" + llm_oop_research: "https://dl.acm.org/doi/10.1145/3639474.3640052" + architecture_diagrams_source: "https://www.linkedin.com/posts/tigraff_uml-claude-wibecoding-activity-7420595633826258944-gGO5" ai_ecosystem_voice_to_text: "guide/ai-ecosystem.md:449" ai_ecosystem_alternative_providers: "guide/ai-ecosystem.md:959" voice_refine_skill: "examples/skills/voice-refine/SKILL.md" @@ -279,6 +287,10 @@ deep_dive: cowork_workflows: "https://github.com/FlorianBruniaux/claude-cowork-guide/tree/main/workflows" cowork_section: "guide/ai-ecosystem.md:760" cowork_ultimate_guide: 10759 + # Appendix + appendix_a_file_locations: 14087 + appendix_b_faq: 14263 + faq_clawdbot_vs_claudecode: 14265 # ════════════════════════════════════════════════════════════════ # DECISION TREE (most important - en premier)