marketing-shibata50/claude-code-ultimate-guide
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

release: v3.37.2 - hook format fix, 3 resource evals, cross-model review sections

Browse source 
- Fix: hook format updated to matcher+hooks[] structure (settings.json, learning-mode.md)
- New guide sections: Cross-Model Review, Lightweight Role-Switch, Task Sizing (ultimate-guide.md)
- Resource Eval: ManoMano Project Aegis — Serena MCP benchmark (3/5, ecosystem gap identified)
- Resource Eval: Multi-Session Management Landscape (4/5)
- Resource Eval: Ischenko workflow quality (2/5, marginal)
- Version bump: 3.37.1 → 3.37.2

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX 2026-03-19 21:22:01 +01:00
parent ea7ce092dc
commit 53ac314a15
11 changed files with 485 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

4
CHANGELOG.md
View file

@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
## [Unreleased] ## [Unreleased]
## [3.37.2] - 2026-03-19
- **RSS Feed added to cc.bruniaux.com** (`landing: src/pages/rss.xml.ts`, `src/data/rss-entries.ts`): Unified RSS feed at `/rss.xml` merging Claude Code CLI releases and guide content updates (guide releases, new pages, new cards, new whitepapers). Auto-discovery `<link>` tag in all page heads, RSS icon in footer and "More" nav dropdown, mention in announcement banner. Dedicated `rss-entries.ts` data file for manual guide entries. Workflow integrated in `/release` (step 6.5 auto-drafts entry) and `/update-infos-release` (step 4.5 for notable CC releases). Post-push hook in landing repo reminds to update `rss-entries.ts`. README updated with RSS link. - **RSS Feed added to cc.bruniaux.com** (`landing: src/pages/rss.xml.ts`, `src/data/rss-entries.ts`): Unified RSS feed at `/rss.xml` merging Claude Code CLI releases and guide content updates (guide releases, new pages, new cards, new whitepapers). Auto-discovery `<link>` tag in all page heads, RSS icon in footer and "More" nav dropdown, mention in announcement banner. Dedicated `rss-entries.ts` data file for manual guide entries. Workflow integrated in `/release` (step 6.5 auto-drafts entry) and `/update-infos-release` (step 4.5 for notable CC releases). Post-push hook in landing repo reminds to update `rss-entries.ts`. README updated with RSS link.
- **Footer links fixed and expanded** (`landing: src/components/global/Footer.astro`): Architecture and Data Privacy now link to in-site guide reader (`/guide/core/architecture/`, `/guide/security/data-privacy/`) instead of GitHub raw files. Added missing pages: Recap Cards, AI Roles, Context, Ecosystem, FAQ. - **Footer links fixed and expanded** (`landing: src/components/global/Footer.astro`): Architecture and Data Privacy now link to in-site guide reader (`/guide/core/architecture/`, `/guide/security/data-privacy/`) instead of GitHub raw files. Added missing pages: Recap Cards, AI Roles, Context, Ecosystem, FAQ.
@ -26,6 +28,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
- **Resource Evaluation — obra/Superpowers** (`docs/resource-evaluations/obra-superpowers-evaluation.md`): Score 5/5. Full software development methodology suite (95k+ stars, 7.5k forks, verified via GitHub API). 7 context-aware skills: brainstorm-first spec gate, implementation planning, subagent-driven development with two-stage review, mandatory TDD enforcement, code review, git worktrees, branch lifecycle. Available on official Claude Code plugin marketplace. Integrated in 4 locations: Plugin Ecosystem section in `third-party-tools.md` (alongside gstack), obra row upgrade in `ultimate-guide.md` skills.sh table, cross-reference in `tdd-with-claude.md`, cross-reference in `spec-first.md`. - **Resource Evaluation — obra/Superpowers** (`docs/resource-evaluations/obra-superpowers-evaluation.md`): Score 5/5. Full software development methodology suite (95k+ stars, 7.5k forks, verified via GitHub API). 7 context-aware skills: brainstorm-first spec gate, implementation planning, subagent-driven development with two-stage review, mandatory TDD enforcement, code review, git worktrees, branch lifecycle. Available on official Claude Code plugin marketplace. Integrated in 4 locations: Plugin Ecosystem section in `third-party-tools.md` (alongside gstack), obra row upgrade in `ultimate-guide.md` skills.sh table, cross-reference in `tdd-with-claude.md`, cross-reference in `spec-first.md`.
- **Resource Evaluation — ManoMano "Project Aegis"** (`docs/resource-evaluations/2026-03-19-manomano-project-aegis-serena.md`): Score 3/5. ManoMano engineering team benchmarked AI coding agents internally and identified Serena MCP as a must-have for large codebase navigation. Serena (oraios/serena) uses LSP for deterministic symbol-level navigation (find_symbol, get_symbols_overview, session memory) — distinct from GrepAI's embedding approach. Guide already covers Serena extensively (8+ files, `ultimate-guide.md:10527`, `search-tools-mastery.md`). Specific gap confirmed: no Serena entry in `mcp-servers-ecosystem.md` (only GrepAI listed under Code Search), creating a discoverability inconsistency. Recommended action: add formal Serena entry to ecosystem file with cross-link to search-tools-mastery.md.
## [3.37.1] - 2026-03-18 ## [3.37.1] - 2026-03-18
- **Threat database updated to v2.8.0** (`examples/commands/resources/threat-db.yaml`): 7 new entries covering March 2026 threats. **New campaigns**: GhostClaw (malicious npm `@openclaw-ai/openclawai`, GhostLoader RAT with SOCKS5 proxy + clipboard monitor, 178 downloads) and Fake OpenClaw Installer (Stealth Packer + GhostSocks via malicious GitHub repos indexed by Bing AI). **New malicious packages**: `@openclaw-ai/openclawai` and `ambar-src` (~50K downloads, evasion techniques). **New CVE**: CVE-2026-24910 (Bun runtime v<1.3.5, lifecycle scripts bypass origin validation). **New attack techniques**: T017 Shadow MCP (employees deploying unvetted MCP servers without IT oversight) and T018 AI Search Result Poisoning (AI-generated search results recommending malicious repos). **New scanning tools**: Jozu Agent Guard (zero-trust AI runtime, non-bypassable policies, 2026-03-17) and MCP Sentinel (RSAC 2026, request/arg scanning for sensitive data). `minimum_safe_versions` updated with `bun: 1.3.5`. - **Threat database updated to v2.8.0** (`examples/commands/resources/threat-db.yaml`): 7 new entries covering March 2026 threats. **New campaigns**: GhostClaw (malicious npm `@openclaw-ai/openclawai`, GhostLoader RAT with SOCKS5 proxy + clipboard monitor, 178 downloads) and Fake OpenClaw Installer (Stealth Packer + GhostSocks via malicious GitHub repos indexed by Bing AI). **New malicious packages**: `@openclaw-ai/openclawai` and `ambar-src` (~50K downloads, evasion techniques). **New CVE**: CVE-2026-24910 (Bun runtime v<1.3.5, lifecycle scripts bypass origin validation). **New attack techniques**: T017 Shadow MCP (employees deploying unvetted MCP servers without IT oversight) and T018 AI Search Result Poisoning (AI-generated search results recommending malicious repos). **New scanning tools**: Jozu Agent Guard (zero-trust AI runtime, non-bypassable policies, 2026-03-17) and MCP Sentinel (RSAC 2026, request/arg scanning for sensitive data). `minimum_safe_versions` updated with `bun: 1.3.5`.

4
README.md
View file

@ -6,7 +6,7 @@
<p align="center"> <p align="center">
<a href="https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers"><img src="https://img.shields.io/github/stars/FlorianBruniaux/claude-code-ultimate-guide?style=for-the-badge" alt="Stars"/></a> <a href="https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers"><img src="https://img.shields.io/github/stars/FlorianBruniaux/claude-code-ultimate-guide?style=for-the-badge" alt="Stars"/></a>
<a href="./CHANGELOG.md"><img src="https://img.shields.io/badge/Updated-Mar_18,_2026_·_v3.37.1-brightgreen?style=for-the-badge" alt="Last Update"/></a> <a href="./CHANGELOG.md"><img src="https://img.shields.io/badge/Updated-Mar_19,_2026_·_v3.37.2-brightgreen?style=for-the-badge" alt="Last Update"/></a>
<a href="./quiz/"><img src="https://img.shields.io/badge/Quiz-271_questions-orange?style=for-the-badge" alt="Quiz"/></a> <a href="./quiz/"><img src="https://img.shields.io/badge/Quiz-271_questions-orange?style=for-the-badge" alt="Quiz"/></a>
<a href="./examples/"><img src="https://img.shields.io/badge/Templates-217-green?style=for-the-badge" alt="Templates"/></a> <a href="./examples/"><img src="https://img.shields.io/badge/Templates-217-green?style=for-the-badge" alt="Templates"/></a>
<a href="./guide/security/security-hardening.md"><img src="https://img.shields.io/badge/🛡️_Threat_DB-15_vulnerabilities_·_655_malicious_skills-red?style=for-the-badge" alt="Threat Database"/></a> <a href="./guide/security/security-hardening.md"><img src="https://img.shields.io/badge/🛡️_Threat_DB-15_vulnerabilities_·_655_malicious_skills-red?style=for-the-badge" alt="Threat Database"/></a>
@ -875,7 +875,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
--- ---
*Version 3.37.1 | Updated daily · Mar 18, 2026 | Crafted with Claude* *Version 3.37.2 | Updated daily · Mar 19, 2026 | Crafted with Claude*
<!-- SEO Keywords --> <!-- SEO Keywords -->
<!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp, <!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,

2
VERSION
View file

@ -1 +1 @@
3.37.1 3.37.2

145
docs/resource-evaluations/082-multi-session-management-landscape.md Normal file
View file

@ -0,0 +1,145 @@
# Resource Evaluation: Multi-Session Claude Code Management — Landscape Overview
**Date**: 2026-03-19
**Evaluator**: Claude (research session + structured synthesis)
**Status**: Reference — Integrate into guide (ecosystem / third-party tools section)
---
## Summary
This evaluation covers the full landscape of tools for managing multiple Claude Code sessions across multiple projects simultaneously. The research identified 13 tools across 4 categories: monitoring dashboards, remote/browser access, multi-project orchestrators, and sound/notification systems.
No single tool covers all use cases. The space is fragmented, actively evolving (most repos < 6 months old), and missing one obvious feature: per-project audio differentiation.
---
## Score: 4/5 (as a category)
| Score | Meaning |
|-------|---------|
| 5 | Essential — Major gap |
| **4** | **High value — Significant improvement** |
| 3 | Pertinent — Useful complement |
| 2 | Marginal — Secondary info |
| 1 | Out of scope |
**Justification**: Multi-agent, multi-project workflows are increasingly common. The guide covers individual session hooks and notifications but has no consolidated view of the tooling available for running 3-10 parallel Claude Code sessions. vibetunnel (4 276 stars) and multi-agent-shogun (1 082 stars) signal strong community demand. Integration would fill a documented gap.
---
## Tool Landscape
### Category 1 — Monitoring Dashboards
| Tool | GitHub | Stars | Stack | Key Features |
|------|--------|-------|-------|-------------|
| **claude-code-monitor (ccm)** | [onikan27/claude-code-monitor](https://github.com/onikan27/claude-code-monitor) | ⭐ 212 | TypeScript / Node | TUI vim-style (j/k, 1-9), session switching via AppleScript, mobile WebUI + QR code pairing, WebSocket real-time |
| **claude-code-dashboard** | [Stargx/claude-code-dashboard](https://github.com/Stargx/claude-code-dashboard) | ⭐ 5 | Node + Express + React | Auto-detects all sessions, token/cost per session, context progress bars, git branch, permission mode badges |
| **sniffly** | [chiphuyen/sniffly](https://github.com/chiphuyen/sniffly) | ⭐ 1 170 | Python | Analytics-first: usage patterns, error breakdown, shareable dashboard. Post-hoc, not real-time |
| **ClaudeCode-Dashboard** | [Quriov/ClaudeCode-Dashboard](https://github.com/Quriov/ClaudeCode-Dashboard) | ⭐ 0 | Next.js 16 + ReactFlow | Config topology viewer (hooks, agents, MCP, skills), not session monitoring |
**Best pick**: `ccm` for real-time monitoring on macOS (easiest setup: `npx claude-code-monitor`). `sniffly` for post-session analytics on any platform.
---
### Category 2 — Remote / Browser Access
| Tool | GitHub | Stars | Stack | Key Features |
|------|--------|-------|-------|-------------|
| **vibetunnel** | [amantus-ai/vibetunnel](https://github.com/amantus-ai/vibetunnel) | ⭐ 4 276 | TypeScript + Swift | Wraps any terminal in browser tabs, multiple sessions, Git Follow Mode, VibeTunnelTalk voice narration |
| **cc-hub** | [m0a/cc-hub](https://github.com/m0a/cc-hub) | ⭐ 1 | Go + tmux + Tailscale | Split panes + session color themes, file diff tracking (Claude edits vs git), mobile optimized, dashboard with cost stats |
**Best pick**: `vibetunnel` for broad use (4 276 stars, very active). `cc-hub` if you need session color differentiation + file diffs per project (requires Tailscale).
---
### Category 3 — Multi-Project Orchestrators
| Tool | GitHub | Stars | Stack | Key Features |
|------|--------|-------|-------|-------------|
| **claudio** | [Iron-Ham/claudio](https://github.com/Iron-Ham/claudio) | ⭐ 22 | Go + tmux | Isolated git worktrees, TUI dashboard, 14 color themes, task chaining (`--depends-on`), planning modes: UltraPlan / TripleShot / Adversarial Review, PR automation, cost limits |
| **multi-agent-shogun** | [yohey-w/multi-agent-shogun](https://github.com/yohey-w/multi-agent-shogun) | ⭐ 1 082 | Shell + tmux | Shogun/Karo/Ashigaru hierarchy, 7 workers + 1 strategist, multi-CLI (Claude, Codex, Copilot, Kimi), zero API coordination cost |
| **zenportal** | [kgang/zenportal](https://github.com/kgang/zenportal) | ⭐ 1 | Python/Textual | Multi-CLI support, git worktrees per session, 3-tier config, session persistence via tmux |
| **praktor** | [mtzanidakis/praktor](https://github.com/mtzanidakis/praktor) | ⭐ 17 | Go + Docker Compose | Telegram I/O (chat from phone), 1 Docker container per agent, cron tasks, swarms, AES-256-GCM secrets vault |
**Best pick**: `claudio` for serious multi-project orchestration (isolated worktrees + color themes + advanced planning). `multi-agent-shogun` for high-parallelism fan-out patterns with tmux visibility.
---
### Category 4 — Sound / Notification Systems
| Tool | GitHub | Stars | Stack | Per-Project Sound |
|------|--------|-------|-------|------------------|
| **karina-voice-notification** | [t1seo/karina-voice-notification](https://github.com/t1seo/karina-voice-notification) | ⭐ 0 | Python (Qwen3-TTS) | Clone any voice from YouTube → custom `.wav` per project (DIY assembly) |
| **sound-micro-server** | [arc-co/claude-code-notification-sound-micro-server](https://github.com/arc-co/claude-code-notification-sound-micro-server) | ⭐ 0 | Node.js | Browser-based sound via hook `Stop` + `curl POST`. Single sound for all sessions |
| **ccnotify** | [Helmi/ccnotify](https://github.com/Helmi/ccnotify) | n/a | Shell | Voice notifications (spoken text) |
| **claude-session-manager** | [Swarek/claude-session-manager](https://github.com/Swarek/claude-session-manager) | ⭐ 4 | Shell | Colored status line per session, session IDs (`cx` command), live description updates |
**Gap**: No tool provides per-project audio differentiation out of the box. The cleanest DIY approach: configure `settings.local.json` per project with a different audio file in the `Stop` hook.
```json
// project-a/.claude/settings.local.json
{
"hooks": {
"Stop": [{ "command": "afplay ~/sounds/project-a.wav" }]
}
}
```
---
## Capability Matrix
| Tool | Multi-session visibility | Session switching | Per-project differentiation | Sound | Platform |
|------|--------------------------|-------------------|-----------------------------|-------|----------|
| ccm | TUI list | AppleScript focus | Status icons | No | macOS only |
| claude-code-dashboard | Web dashboard | No | Git branch / badges | No | All |
| vibetunnel | Browser tabs | Manual tab switch | Terminal titles | No (voice narration optional) | macOS M1+ / Linux |
| cc-hub | Split panes | Click | Color themes per session | No | macOS/Linux + Tailscale |
| claudio | TUI per instance | TUI controls | 14 color themes | No | macOS/Linux |
| multi-agent-shogun | tmux panes | tmux | Pane position | No | macOS/Linux |
| zenportal | TUI list | TUI controls | Session name | No | macOS/Linux |
| praktor | Web + Telegram | @agent_name | Docker container | No | Linux/Docker |
| karina-voice-notification | n/a | n/a | Custom voice per project | YES (DIY) | macOS M1+ / Linux (CUDA) |
| sound-micro-server | n/a | n/a | No | YES (single sound) | All (browser) |
| claude-session-manager | Terminal status line | Manual | Color-coded status | No | macOS/Linux |
---
## Key Findings
**High adoption signal**: vibetunnel (4 276 stars) and multi-agent-shogun (1 082 stars) are the two breakout tools. Both are actively maintained and solve real problems at scale.
**Missing feature**: Per-project audio differentiation does not exist as a packaged solution. DIY with `afplay` / `paplay` + `settings.local.json` hooks per project is the only current approach.
**Ecosystem maturity**: The space is 3-6 months old. Most tools are single-maintainer experiments. `claudio`, `ccm`, and `vibetunnel` have the strongest signals for longevity.
**Platform gap**: Most orchestrators require tmux and work only on macOS/Linux. No solid Windows option exists.
---
## Recommendations
**Action**: Integrate a "Multi-Session Management" section into the guide (third-party tools or workflows section).
**Priority picks to document**:
| Use case | Recommended tool |
|----------|-----------------|
| Quick multi-session visibility on macOS | ccm (`npx claude-code-monitor`) |
| Post-session analytics (all platforms) | sniffly (`uvx sniffly@latest init`) |
| Browser/remote access | vibetunnel |
| Serious orchestration with isolation | claudio |
| High-parallelism fan-out | multi-agent-shogun |
| Per-project audio (DIY) | `settings.local.json` + `afplay` |
**Watch list**: cc-hub, zenportal, praktor — interesting architectures but < 20 stars each. Re-evaluate at 100+ stars.
---
## Related Evaluations
- [078-claude-swarm-monitor.md](078-claude-swarm-monitor.md) — TUI for monitoring agents across worktrees (Rust, Linux)
- [074-ruflo-multi-agent-orchestration.md](074-ruflo-multi-agent-orchestration.md) — Ruflo orchestration platform
- [079-fabro-workflow-orchestration.md](079-fabro-workflow-orchestration.md) — Fabro workflow runtime

138
docs/resource-evaluations/2026-03-19-manomano-project-aegis-serena.md Normal file
View file

@ -0,0 +1,138 @@
# Resource Evaluation: ManoMano "Project Aegis" — Serena MCP Benchmarking
**Date**: 2026-03-19
**Evaluator**: Claude Sonnet 4.6
**Resource URL**: https://medium.com/manomano-tech/project-aegis-benchmarking-ai-agents-and-why-serena-is-our-new-must-have-311673db35dd
**Resource Type**: Engineering blog post (Medium)
**Author**: ManoMano Engineering Team
**Company**: ManoMano (e-commerce, ~1000 devs)
**Article access**: Medium 403 during evaluation — content reconstructed from Perplexity + Serena GitHub (oraios/serena)
---
## Executive Summary
ManoMano's engineering team ran "Project Aegis," an internal benchmark of AI coding agents across their dev stack. Their conclusion: Serena MCP became a must-have tool. The article surfaces real production usage data for Serena, an LSP-based MCP server that provides symbol-level code navigation and session memory. The guide already documents Serena extensively (8+ files, high depth in `ultimate-guide.md` and `search-tools-mastery.md`) but has a specific consistency gap: no entry in `mcp-servers-ecosystem.md`, which lists GrepAI as the only code search/analysis MCP. A reader landing on that page gets an incomplete picture.
---
## Content Summary
**What the article covers** (reconstructed — direct fetch failed):
- Internal benchmark ("Project Aegis") comparing multiple AI coding agents on production tasks
- Serena MCP identified as the standout tool for large codebase navigation
- Rationale: LSP-based symbol navigation (vs embedding/vector search like GrepAI) provides precise, low-latency, deterministic results
- Token efficiency: Serena provides targeted context (symbol + callers/references) rather than full-file reads
- Conclusion: Serena is now part of ManoMano's standard AI dev setup
**What Serena does** (verified via GitHub oraios/serena + Perplexity):
- Uses Language Server Protocol (LSP) for semantic code understanding — actual compiler-level symbol resolution, not embeddings
- 30+ languages supported natively (Python, TypeScript/JS, PHP, Go, Rust, C/C++, Java out of box)
- Core tools: `find_symbol`, `find_referencing_symbols`, `get_symbols_overview`, `replace_symbol_body`
- Session memory: `write_memory` / `read_memory` / `list_memories` stored in `.serena/memories/`
- Behavioral modes: planning, editing, interactive, one-shot — contexts: desktop-app, agent, ide-assistant
- Free, open-source (GitHub: oraios/serena), runs locally via `uvx`
- Integrates with Claude Code, Claude Desktop, VSCode, Cursor, Cline
**Key distinction vs GrepAI**:
| Aspect | Serena | GrepAI |
|--------|--------|--------|
| Approach | LSP (compiler-level symbols) | Embeddings (Ollama vector search) |
| Latency | ~100ms | ~500ms |
| Use case | Known symbol navigation, refactoring | Intent-based discovery, unfamiliar code |
| Setup | Language server per language | Ollama + nomic-embed-text |
| Memory | Built-in session memory | None |
| Accuracy | Deterministic (exact symbols) | Probabilistic (similarity score) |
---
## Gap Analysis vs. Guide
| Area | ManoMano article / Serena | Guide coverage |
|------|--------------------------|----------------|
| Serena — dedicated section | ✅ Endorses as must-have | ✅ `ultimate-guide.md:10527`, `search-tools-mastery.md` |
| Serena session memory | ✅ Implicit (persistent workflow) | ✅ `ultimate-guide.md:1797-1843`, cheatsheet |
| Serena — ecosystem entry | ✅ Would fit under Code Search | ❌ **Not in `mcp-servers-ecosystem.md`** |
| Serena vs GrepAI comparison | ✅ Context from benchmarking | ✅ `search-tools-mastery.md` comparison table |
| Production benchmarking methodology | ✅ Real team, real codebase | ❌ Guide has no multi-agent benchmark section |
| LSP setup friction (polyglot codebases) | ⚠️ Not addressed in article | ⚠️ Understated in guide |
**Real gap**: `mcp-servers-ecosystem.md` lists GrepAI as the only entry under "Code Search & Analysis." A reader arriving via that page has no path to Serena. The rest of the guide recommends both tools as complementary, creating a discoverability inconsistency.
---
## Relevance Score: 3/5
### Why 3/5 (Pertinent — Integrate when time available)?
**✅ Strengths**:
1. **Production validation**: ManoMano is a real e-commerce company running this at scale, not a tutorial author
2. **Corroborates existing guide position**: The guide already recommends Serena — this adds external credibility
3. **Benchmarking angle**: Real-world comparison between agents is an angle the guide does not cover
4. **Signals the discoverability gap**: The fact that a production team writes "why Serena is our must-have" suggests readers aren't finding it easily — consistent with the mcp-servers-ecosystem.md gap
**⚠️ Weaknesses**:
1. **Single-team case study**: One engineering team's benchmark, methodology not published
2. **"Must-have" is marketing language**: No reproducible metrics, no controlled comparison
3. **Article inaccessible**: Medium 403 — content could not be directly verified during evaluation
4. **Narrow gap**: The guide already covers Serena well; the fix is a targeted addition to one file, not a major integration
---
## Recommendations
**Primary action** (independent of this article — fix the consistency gap):
Add a formal Serena entry to `guide/ecosystem/mcp-servers-ecosystem.md` under "Code Search & Analysis," after the GrepAI entry. Include:
- Repository, license, status
- LSP vs embedding distinction (why it complements GrepAI)
- Key tools: `find_symbol`, `get_symbols_overview`, `write_memory`
- Setup (uvx install, `--project-root` arg)
- Cross-link to `guide/workflows/search-tools-mastery.md`
**Secondary action** (optional, using this article as source):
Mention ManoMano's production benchmarking as a real-world reference within the Serena entry or the search-tools-mastery workflow. Frame it as: "Production teams choosing Serena for large codebase work consistently cite the LSP approach's precision over embedding-based alternatives."
**Priority**: Medium — the ecosystem page inconsistency is the real driver, not the article itself.
---
## Challenge Notes (technical-writer agent)
The agent challenge during evaluation raised three valid points:
1. **Score should separate resource quality from gap severity**: The 4/5 initially assigned conflated "how important is Serena" with "how good is this article." Adjusted to 3/5 after separating the two.
2. **LSP setup friction understated**: Serena requires a running language server per language. For polyglot repos, this is non-trivial. Worth flagging in the guide entry.
3. **Serena session memory overlaps with ICM**: The guide currently does not clearly distinguish Serena's `.serena/memories/` from ICM's cross-session memory. A clarification note would prevent user confusion when both are configured.
---
## Fact-Check
| Claim | Verified | Source |
|-------|----------|--------|
| Serena uses LSP for symbol navigation | ✅ | github.com/oraios/serena, Perplexity |
| 30+ languages supported | ✅ | Multiple sources (aiagentslist.com, vibetools.net) |
| Claude Code integration native | ✅ | Serena README |
| Free and open-source (MIT) | ✅ | GitHub license |
| Session memory via `.serena/memories/` | ✅ | Guide documentation + quiz |
| ManoMano article exists at URL | ✅ | URL valid, 403 on fetch |
| ManoMano benchmark stats/methodology | ⚠️ | Article inaccessible — not verifiable |
| "Must-have" as measured outcome | ❌ | Marketing claim, no reproducible metric |
---
## Decision
- **Score**: 3/5
- **Action**: Integrate — add Serena entry to `mcp-servers-ecosystem.md` (fix the consistency gap). Optionally cite ManoMano as production reference within that entry.
- **Confidence**: High on the gap diagnosis; Medium on the article content (inaccessible)
- **Urgency**: Low-Medium — the guide works without it, but the discoverability gap is real

76
docs/resource-evaluations/ischenko-claude-code-workflow-quality.md Normal file
View file

@ -0,0 +1,76 @@
# Resource Evaluation: "You're probably using Claude Code wrong" - Alex Ischenko
## Metadata
| Field | Value |
|-------|-------|
| **Author** | Alex Ischenko |
| **Role** | AI-Driven CTO, Top 100 Leaders @ CTO Craft |
| **Published** | 2026-03-19 |
| **Type** | LinkedIn Pulse article |
| **URL** | https://www.linkedin.com/pulse/youre-probably-using-claude-code-wrong-i-too-until-shift-ischenko-bwdkf/ |
| **Evaluated** | 2026-03-19 |
| **Score** | 2/5 (Marginal) |
| **Decision** | Do not integrate |
## Summary
LinkedIn article arguing that Claude Code quality is an engineering system question, not a model question. Proposes 7 workflow patterns for improving output quality, each with a full copy-paste prompt template:
1. **Reality checks before implementation** - verify codebase assumptions before coding
2. **Separate author/reviewer** - two-role pattern within same session
3. **Project-aware reviews** - review with project context, not just diff
4. **Requirements as mandatory artifact** - REQUIREMENTS.md before code
5. **TDD workflow** - anchor behavior with tests first
6. **Small task sizes** - reduce scope for better AI output
7. **Human abstraction elevation** - move engineers to architecture/trade-off level
Claims "20-30% quality improvement" from these workflow changes.
## Scoring Rationale
### Overlap with Guide (75-85%)
| Pattern | Guide Coverage | Location |
|---|---|---|
| Reality checks | Partial | `exploration-workflow.md`, Plan Mode (L3717) |
| Author/reviewer | Moderate | SE-CoVe (L13095), Scope-Focused Agents (L4410) |
| Project-aware reviews | Partial | `code-review.md` (CLAUDE.md + REVIEW.md) |
| Requirements artifact | Partial | `spec-first.md` (full workflow) |
| TDD | Strong | `tdd-with-claude.md`, L19183-19320, skill template L7336 |
| Small tasks | Scattered | `spec-first.md` L62-93, L1529, L1733 |
| Human elevation | Thin | L17458, L15725, L3216 |
### What's Unique
The 7 copy-paste prompt templates are the only non-redundant element. These are practical formatting convenience but not structural insight. The guide's existing workflow files and skill templates serve the same purpose.
### Credibility Assessment
- No GitHub repo, no production artifact, no tooling behind the article
- "20-30% quality improvement" has no methodology, no baseline, no control group
- Compare to higher-scored resources: Cullen (shipped working slash command, 5/5), Chabaud (clonable repo, 3/5), Rusitschka (repo with working code, 4/5)
### Accumulation Risk
The guide already integrates Chabaud, Rusitschka, Cullen, and paddo.dev team tips covering adjacent workflow territory. Adding Ischenko without new substance dilutes the signal-to-noise ratio.
## Identified Gaps (for future work, not from this resource)
Two gaps surfaced during analysis that the guide could address independently:
1. **Multi-model review pattern** (near zero coverage): deliberately using different models to review each other's work. Ischenko mentions it briefly but provides no template.
2. **Consolidated task sizing section**: currently scattered across multiple files with no single reference point.
## Fact-Check
| Claim | Status | Notes |
|---|---|---|
| Author credentials | Unverifiable | CTO Craft exists, "Top 100" not independently verifiable |
| "20-30% quality improvement" | Unfalsifiable | No methodology described |
| Tool landscape (Claude Code, Cursor, etc.) | Verified | All exist as active tools |
| LLM behavioral patterns (overconfidence, compound errors) | Verified | Well-documented in literature |
## Decision
**Do not integrate.** Solid engineering advice but the guide already covers these patterns through better-sourced, more detailed, and more production-grounded resources. The prompt templates could theoretically be extracted as addenda to existing workflow files, but this is low priority.

1
examples/claude-md/learning-mode.md
View file

@ -155,6 +155,7 @@ Pair this CLAUDE.md with the learning-capture hook to automatically log insights
{ {
"hooks": { "hooks": {
"Stop": [{ "Stop": [{
"matcher": "",
"hooks": [{ "hooks": [{
"type": "command", "type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/bash/learning-capture.sh" "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/bash/learning-capture.sh"

14
examples/config/settings.json
View file

@ -3,13 +3,23 @@
"PreToolUse": [ "PreToolUse": [
{ {
"matcher": "Bash", "matcher": "Bash",
"command": ".claude/hooks/security-check.sh" "hooks": [
{
"type": "command",
"command": ".claude/hooks/security-check.sh"
}
]
} }
], ],
"PostToolUse": [ "PostToolUse": [
{ {
"matcher": "Write|Edit", "matcher": "Write|Edit",
"command": ".claude/hooks/auto-format.sh" "hooks": [
{
"type": "command",
"command": ".claude/hooks/auto-format.sh"
}
]
} }
] ]
} }

4
guide/cheatsheet.md
View file

@ -12,7 +12,7 @@ tags: [cheatsheet, reference]
**Written with**: Claude (Anthropic) **Written with**: Claude (Anthropic)
**Version**: 3.37.1 | **Last Updated**: March 2026 **Version**: 3.37.2 | **Last Updated**: March 2026
--- ---
@ -639,4 +639,4 @@ Speed: `rg` (~20ms) → Serena (~100ms) → ast-grep (~200ms) → grepai (~500ms
**Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude **Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude
*Last updated: March 2026 | Version 3.37.1* *Last updated: March 2026 | Version 3.37.2*

100
guide/ultimate-guide.md
View file

@ -16,7 +16,7 @@ tags: [guide, reference, workflows, agents, hooks, mcp, security]
**Last updated**: January 2026 **Last updated**: January 2026
**Version**: 3.37.1 **Version**: 3.37.2
--- ---
@ -1528,6 +1528,19 @@ VERIFY: Login persists after browser refresh
**Fix**: One focused task per session. `/clear` between different tasks. **Fix**: One focused task per session. `/clear` between different tasks.
**How to size a task for Claude Code:**
| Signal | Too big | Right size | Too small |
|--------|---------|------------|-----------|
| Description | Uses "AND" between behaviors | One vertical slice, one user behavior | A single line change you could do faster manually |
| Session | Runs out of context or drifts | Completes within one session | Takes 30 seconds |
| Review | Reviewer can't hold the full diff in mind | Diff is reviewable in one pass | Not worth a review |
| Rollback | Reverting breaks other things | `git revert` cleanly undoes everything | N/A |
**Splitting heuristic**: if your task description requires "and" between two user-facing behaviors, split it. "Users can reset passwords" is one task. "Users can reset passwords AND admins can force-expire sessions" is two.
> **Deep dive**: [Spec-First Workflow — Task Granularity](./workflows/spec-first.md#task-granularity-sizing-work-for-agents) covers the vertical slice pattern, PRD quality checklist, and concrete before/after examples.
### 8. ❌ Treating Claude Code Like a Chatbot ### 8. ❌ Treating Claude Code Like a Chatbot
**Mistake**: Typing ad-hoc instructions every session. Repeating project conventions, re-explaining architecture, manually enforcing quality checks. **Mistake**: Typing ad-hoc instructions every session. Repeating project conventions, re-explaining architecture, manually enforcing quality checks.
@ -5166,7 +5179,7 @@ The `.claude/` folder is your project's Claude Code directory for memory, settin
| Personal preferences | `CLAUDE.md` | ❌ Gitignore | | Personal preferences | `CLAUDE.md` | ❌ Gitignore |
| Personal permissions | `settings.local.json` | ❌ Gitignore | | Personal permissions | `settings.local.json` | ❌ Gitignore |
### 3.37.1 Version Control & Backup ### 3.37.2 Version Control & Backup
**Problem**: Without version control, losing your Claude Code configuration means hours of manual reconfiguration across agents, skills, hooks, and MCP servers. **Problem**: Without version control, losing your Claude Code configuration means hours of manual reconfiguration across agents, skills, hooks, and MCP servers.
@ -13136,6 +13149,87 @@ These tools solve different problems at different stages of the development cycl
**Complementary workflow**: Run Vitals weekly to identify which areas of the codebase need attention, then use SE-CoVe when asking Claude to refactor or fix those hotspot files. **Complementary workflow**: Run Vitals weekly to identify which areas of the codebase need attention, then use SE-CoVe when asking Claude to refactor or fix those hotspot files.
#### Lightweight Role-Switch Review
Not every change warrants SE-CoVe's 5-stage pipeline. For everyday review within a single session, you can prompt Claude to switch from author to reviewer explicitly:
```markdown
You just wrote the implementation above. Now forget you wrote it.
Review it as a senior engineer who did not author this code.
Check: requirement fidelity, edge cases, error handling, backward
compatibility, security, performance. For each issue found, cite
the file and line, explain the problem, and propose a concrete fix.
Verdict: APPROVE, REQUEST CHANGES, or REJECT.
```
This works because the explicit instruction to "forget you wrote it" forces Claude to re-evaluate rather than defend prior decisions. It catches surface-level issues (missing null checks, inconsistent error handling, naming drift) but shares the same reasoning path as the author, so subtle architectural flaws may survive.
**When to use what:**
| Approach | Cost | Catches | Best for |
|----------|------|---------|----------|
| Role-switch (same session) | 1x | Surface issues, naming, obvious bugs | Daily development, quick fixes |
| SE-CoVe (plugin) | ~2x | Reasoning-path blind spots, subtle logic errors | Security-sensitive code, architecture |
| Cross-model review (see below) | 1x-2x | Different reasoning patterns, fresh perspective | Critical paths, pre-merge gates |
| Scope-focused agents | 2-5x | Domain-specific issues in parallel | Large PRs, multi-concern review |
#### Cross-Model Review
A single model reviewing its own code follows the same reasoning patterns that produced the code. Using a different model for review introduces genuinely independent analysis.
**The pattern**: generate with one model, review with another.
```bash
# Implement with Opus (deep reasoning)
claude --model opus
# Review the diff with Sonnet (different reasoning path, lower cost)
claude -p "Review the changes in the last commit. Check for logic errors, \
edge cases, backward compatibility, and security issues. \
Cite file:line for each finding." --model sonnet
# Quick sanity check with Haiku (fast, cheap, catches obvious issues)
claude -p "List any bugs, missing error handling, or security issues \
in the last commit." --model haiku
```
**With custom agents:**
```yaml
# .claude/agents/cross-model-reviewer.md
---
name: cross-model-reviewer
model: sonnet # Different from your working model
tools: Read, Grep, Glob
---
You are reviewing code you did not write. Your job is to find problems.
Read the files listed below, then check:
1. Logic errors and edge cases
2. Error handling completeness
3. Backward compatibility risks
4. Security issues (injection, auth gaps, data leaks)
5. Performance concerns (O(n²), unbounded queries)
For each finding: severity (critical/high/medium), file:line, problem, fix.
If no issues found, say so explicitly.
```
**Why different models catch different bugs**: each model has distinct reasoning biases, training distributions, and failure modes. A bug that sits in one model's blind spot may be obvious to another. This is the same principle behind diverse code review teams in traditional engineering.
**Cost-effective patterns:**
| Generation Model | Review Model | Cost Multiplier | When |
|-----------------|-------------|-----------------|------|
| Opus | Sonnet | ~1.3x | Default for critical code |
| Sonnet | Haiku | ~1.05x | High-volume, pre-commit gate |
| Sonnet | Opus | ~2x | Architecture, security-critical |
| Any | Same model, fresh session | ~1.5x | Context isolation without model switch |
The fresh session variant (same model, new context via `claude -p`) gives you context isolation without changing the model. Less effective than a true model switch but still better than reviewing in the same session where the code was written.
--- ---
## 8.6 MCP Security ## 8.6 MCP Security
@ -23482,4 +23576,4 @@ We'll evaluate and add it to this section if it meets quality criteria.
**Contributions**: Issues and PRs welcome. **Contributions**: Issues and PRs welcome.
**Last updated**: January 2026 | **Version**: 3.37.1 **Last updated**: January 2026 | **Version**: 3.37.2

14
machine-readable/reference.yaml
View file

@ -3,7 +3,7 @@
# Source: guide/ultimate-guide.md # Source: guide/ultimate-guide.md
# Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code # Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
version: "3.37.1" version: "3.37.2"
updated: "2026-03-17" updated: "2026-03-17"
# ════════════════════════════════════════════════════════════════ # ════════════════════════════════════════════════════════════════
@ -1581,7 +1581,7 @@ ecosystem:
- "Cross-links modified → Update all 4 repos" - "Cross-links modified → Update all 4 repos"
history: history:
- date: "2026-01-20" - date: "2026-01-20"
event: "Code Landing sync v3.37.1, 66 templates, cross-links" event: "Code Landing sync v3.37.2, 66 templates, cross-links"
commit: "5b5ce62" commit: "5b5ce62"
- date: "2026-01-20" - date: "2026-01-20"
event: "Cowork Landing fix (paths, README, UI badges)" event: "Cowork Landing fix (paths, README, UI badges)"
@ -1593,7 +1593,7 @@ ecosystem:
onboarding_matrix_meta: onboarding_matrix_meta:
version: "2.1.0" version: "2.1.0"
last_updated: "2026-03-09" last_updated: "2026-03-09"
aligned_with_guide: "3.37.1" aligned_with_guide: "3.37.2"
changelog: changelog:
- version: "2.1.0" - version: "2.1.0"
date: "2026-03-09" date: "2026-03-09"
@ -1624,7 +1624,7 @@ onboarding_matrix:
core: [rules, sandbox_native_guide, commands] core: [rules, sandbox_native_guide, commands]
time_budget: "5 min" time_budget: "5 min"
topics_max: 3 topics_max: 3
note: "SECURITY FIRST - sandbox before commands (v3.37.1 critical fix)" note: "SECURITY FIRST - sandbox before commands (v3.37.2 critical fix)"
beginner_15min: beginner_15min:
core: [rules, sandbox_native_guide, workflow, essential_commands] core: [rules, sandbox_native_guide, workflow, essential_commands]
@ -1713,7 +1713,7 @@ onboarding_matrix:
- default: agent_validation_checklist - default: agent_validation_checklist
time_budget: "60 min" time_budget: "60 min"
topics_max: 6 topics_max: 6
note: "Dual-instance pattern for quality workflows (v3.37.1)" note: "Dual-instance pattern for quality workflows (v3.37.2)"
learn_security: learn_security:
intermediate_30min: intermediate_30min:
@ -1724,7 +1724,7 @@ onboarding_matrix:
- default: permission_modes - default: permission_modes
time_budget: "30 min" time_budget: "30 min"
topics_max: 4 topics_max: 4
note: "NEW goal (v3.37.1) - Security-focused learning path" note: "NEW goal (v3.37.2) - Security-focused learning path"
power_60min: power_60min:
core: [sandbox_native_guide, mcp_secrets_management, security_hardening] core: [sandbox_native_guide, mcp_secrets_management, security_hardening]
@ -1749,7 +1749,7 @@ onboarding_matrix:
core: [rules, sandbox_native_guide, workflow, essential_commands, context_management, plan_mode] core: [rules, sandbox_native_guide, workflow, essential_commands, context_management, plan_mode]
time_budget: "60 min" time_budget: "60 min"
topics_max: 6 topics_max: 6
note: "Security foundation + core workflow (v3.37.1 sandbox added)" note: "Security foundation + core workflow (v3.37.2 sandbox added)"
intermediate_120min: intermediate_120min:
core: [plan_mode, agents, skills, config_hierarchy, git_mcp_guide, hooks, mcp_servers] core: [plan_mode, agents, skills, config_hierarchy, git_mcp_guide, hooks, mcp_servers]