marketing-shibata50/claude-code-ultimate-guide
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
223 commits 1 branch 0 tags 20 MiB
Commit graph

51 commits

Author SHA1 Message Date
Florian BRUNIAUX
c28161dca8 docs: enrich RTK evaluation with T3 Stack production testing 
Real-World Testing Results (Méthode Aristote - T3 Stack):
- Project: Next.js 15 + tRPC + Prisma + pnpm
- Commands tested: 12 (git, pnpm, Vitest, TypeScript, Prisma)
- Git workflows validated: 85.6% avg reduction (up from 72.6%)

Critical Bug Discovered:
- git argument parsing broken (`--oneline`, `--graph` blocked)
- Workaround: `rtk git log -- -20` (works)
- Impact: CRITICAL - affects ALL git users

Modern Stack Gaps Identified:
- pnpm support MISSING (80-90% reduction possible, CRITICAL impact)
- Vitest support MISSING (90% reduction possible, HIGH impact)
- TypeScript support MISSING (70% reduction possible, MEDIUM impact)

ROI Analysis:
- Current v0.2.0: 40% command coverage, 55% token reduction
- Proposed v0.3.0 (pnpm + Vitest): 85% coverage, 80% reduction
- Dev effort: 1 week (7 days)

New Deliverables:
- Benchmark script: examples/scripts/rtk-benchmark.sh (reproductible tests)
- Test results: claudedocs/rtk-test-results-aristote.md (53KB, gitignored)
- Updated PR proposals: claudedocs/rtk-pr-proposals.md (P0-P2 ranking)
- GitHub issues: claudedocs/rtk-github-issue-template.md (ready for upstream)

Updated Evaluation:
- Score: Still 4/5 (GOOD) but clearer path to 5/5 (CRITICAL)
- Blockers: git args bug + pnpm/Vitest gaps
- Strength: 85.6% git reduction validated on production codebase

Full report: claudedocs/rtk-test-results-aristote.md (23K detailed analysis)
 2026-01-28 14:01:37 +01:00
Florian BRUNIAUX
1000cb6e85 docs: add RTK integration templates and evaluation 
- Evaluation: docs/resource-evaluations/rtk-evaluation.md (4/5 score, comprehensive benchmarks)
- CLAUDE.md template: examples/claude-md/rtk-optimized.md (manual usage instructions)
- Skill template: examples/skills/rtk-optimizer/SKILL.md (auto-suggestion)
- Hook template: examples/hooks/bash/rtk-auto-wrapper.sh (PreToolUse auto-wrapper)
- PR proposals: claudedocs/rtk-pr-proposals.md (7 upstream improvements)

These templates enable 3 RTK integration strategies referenced in guide:10478
 2026-01-28 13:03:10 +01:00
Florian BRUNIAUX
edf74b38c5 docs: add missing hook events from official CHANGELOG (v2.1.9-v2.1.10) 
- Add 3 missing events to Section 7.1: Setup, PermissionRequest, SubagentStop
- Document PreToolUse additionalContext feature (v2.1.9+)
- Create 3 production-ready hook templates (setup, permission, subagent)
- Add resource evaluation documenting rejection of secondary source

Source: Official Claude Code CHANGELOG, not external blog posts
Closes gap identified during resource evaluation process

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
 2026-01-27 12:45:47 +01:00
Florian BRUNIAUX
3a7671ac5e docs: update $ARGUMENTS syntax for v2.1.19 breaking change + evaluation 
Updated all documentation and examples to reflect Claude Code v2.1.19
breaking change: $ARGUMENTS.0 → $ARGUMENTS[0] (bracket syntax).

Changes:
- guide/ultimate-guide.md: 7 occurrences updated to bracket/shorthand syntax
- guide/cheatsheet.md: Command template updated
- Added migration note in § 6.2 Variable Interpolation
- Created migration scripts: migrate-arguments-syntax.{sh,ps1}
  • Automated detection + conversion with backups
  • Dry-run mode, cross-platform (macOS/Linux/Windows)
- Added formal evaluation: eval-claude-code-releases-jan2026.md
  • Score: 5/5 (Critical - Integrate Immediately)
  • Covers releases 2.1.0 to 2.1.19 (January 2026)
  • Technical accuracy verified against GitHub CHANGELOG

Files:
- guide/ultimate-guide.md (+23 lines, 7 occurrences fixed)
- guide/cheatsheet.md (+1 line)
- examples/scripts/migrate-arguments-syntax.sh (+152 lines)
- examples/scripts/migrate-arguments-syntax.ps1 (+143 lines)
- docs/resource-evaluations/eval-claude-code-releases-jan2026.md (+273 lines)
- CHANGELOG.md (+12 lines, Unreleased section)

Total: +605 lines

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
 2026-01-26 17:37:49 +01:00
Florian BRUNIAUX
257f2ff65d docs: add search tools guides and ast-grep patterns 
New documentation:
- guide/search-tools-cheatsheet.md: Quick reference for Grep/Glob/Read tools
- guide/workflows/README.md: Workflows directory index
- examples/skills/ast-grep-patterns.md: AST-based code search patterns

Updated:
- guide/architecture.md: MCP architecture visual diagram section

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-01-25 18:47:29 +01:00
Florian BRUNIAUX
96da6ebd7e feat: add bridge script for Claude Code → LM Studio execution (v3.12.1) 
Bridge script enables local execution of Claude Code plans via LM Studio:
- Python CLI with 5 components (DoobidooReader, LMStudioClient, Validator, StepExecutor, PlanExecutor)
- JSON Schema for plan validation (bridge-plan-schema.json)
- Cost optimization: Plan with Opus (~$0.50-2), execute free locally (80-90% savings)
- 4 validation types: json, syntax_check, contains_keys, non_empty
- CLI: --health, --list, --plan ID, -v verbose mode

Documentation:
- New section "Local Execution Bridge" in ultimate-guide.md §11.2
- scripts/README.md with full usage documentation
- machine-readable/reference.yaml entries for discoverability

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-01-25 18:43:05 +01:00
Florian BRUNIAUX
c84c56bfbd docs: add AI Traceability & Attribution guide 
Comprehensive documentation on AI code attribution and disclosure:

- New guide: guide/ai-traceability.md (~640 lines)
  - LLVM "Human-in-the-Loop" policy (Assisted-by trailer)
  - Ghostty mandatory disclosure pattern
  - Fedora contributor accountability framework
  - git-ai tool documentation
  - PromptPwnd security vulnerability
  - Four-level disclosure spectrum
  - Implementation guides (solo, team, enterprise)

- Templates: examples/config/
  - CONTRIBUTING-ai-disclosure.md
  - PULL_REQUEST_TEMPLATE-ai.md

- Cross-references added to:
  - ultimate-guide.md (after Co-Authored-By section)
  - learning-with-ai.md (after Vibe Coding Trap)
  - security-hardening.md (See Also)
  - guide/README.md (table of contents)

- reference.yaml: 14 new entries for AI traceability topics

Source: Vibe coding needs git blame (Piotr Migdał, Jan 2026)
+ Perplexity research on LLVM, Ghostty, Fedora policies

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-01-24 20:11:53 +01:00
Florian BRUNIAUX
ee5791668a docs: add SE-CoVe plugin example + resource evaluation workflow (v3.11.6) 
- First plugin example: SE-CoVe (Chain-of-Verification, Meta AI ACL 2024)
- Academic approach: cite paper metrics, not marketing claims
- Performance table: +23-112% accuracy (task-dependent, trade-offs disclosed)
- Resource evaluation template established (Perplexity fact-check workflow)
- Curation policy: Academic validation + Claims verified + Costs transparent
- Templates count: 82 → 83
- Architecture diagram added (visual overview of Claude Code internals)

Files:
- examples/plugins/se-cove.md (new plugin documentation)
- claudedocs/resource-evaluations/2026-01-24-se-cove-plugin.md (evaluation report)
- README.md, CHANGELOG.md, VERSION, reference.yaml (version bump 3.11.5 → 3.11.6)
- guide/architecture.md + image (visual overview)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
 2026-01-24 17:40:54 +01:00
Florian BRUNIAUX
f7e1254b06 docs: enrich Remotion quickstart with curated resources 
Add comprehensive "Resources Complémentaires" section (115 lines):
- Top 3 essentials (Official Resources, Fireship, Discord)
- Written tutorials by level (ClipCat, Prismic, SitePoint)
- Video tutorials by objective (beginner, deep-dive, Claude Code)
- Templates & examples (Hello World, Audiogram, GitHub Unwrapped)
- Success stories ($5M ARR Icon.me, $1M ARR Revid.ai)
- Community support (Discord 5.6K+ members, bot AI)
- Advanced resources (performance, AI skills, deployment)
- Useful packages (@remotion/shapes, transitions, subtitle)
- 3-week learning roadmap (fundamentals → practice → production)

Research source: Perplexity Pro (50+ URLs verified, 95% confidence)

Rationale: Users requested learning resources. Now have complete
learning path from installation to production.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
 2026-01-24 16:09:40 +01:00
Florian BRUNIAUX
341d1b1c01 docs: add Remotion skills + quickstart tutorial 
- Add remotion-best-practices to skills.sh table (line 5202)
- Create comprehensive Remotion + Claude Code quickstart tutorial
  - 15-min setup guide for first video
  - Step-by-step: install → preview → render → iterate
  - Troubleshooting section
  - Example prompts and use cases
  - Success metrics ($5M-8M ARR products)

Rationale: Post fact-check (80+ sources), Remotion validated as
legitimate tool (27K GitHub stars, verified success stories).
Score upgraded from 2/5 → 3/5 (Moderate).

Tutorial location: examples/workflows/remotion-quickstart.md

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
 2026-01-24 10:55:39 +01:00
Florian BRUNIAUX
09ac9d381d docs: add doobidoo/mcp-memory-service documentation (semantic memory) 
- Add comprehensive section in ultimate-guide.md (L.6385-6523)
- Document 3 backends: sqlite_vec, cloudflare, hybrid
- List 12 MCP tools with descriptions
- Add environment variables reference
- Include multi-client sync patterns (same machine vs multi-device)
- Add disclaimer: under testing, not yet validated in production
- Update reference.yaml with 8 new entries
- Add to cheatsheet.md and mcp.json template

Complements Serena (key-value) with semantic search capabilities.

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-01-23 14:25:35 +01:00
Florian BRUNIAUX
5fbea061d5 docs: add Agent Vibes TTS integration documentation (v3.11.1) 
Added comprehensive documentation for text-to-speech integration via Agent Vibes MCP server.

New files (8):
- examples/integrations/agent-vibes/README.md - Quick start guide
- examples/integrations/agent-vibes/installation.md - 18-minute setup procedure
- examples/integrations/agent-vibes/voice-catalog.md - 15 voices (4 FR models, 128 speakers)
- examples/integrations/agent-vibes/troubleshooting.md - 7 common issues solved
- guide/workflows/tts-setup.md - Step-by-step workflow
- examples/hooks/bash/tts-selective.sh - Custom selective TTS hook
- examples/claude-md/tts-enabled.md - Project template

Documentation:
- guide/ai-ecosystem.md (section 5.1) - TTS tools overview
- guide/README.md - Added TTS workflow reference
- machine-readable/reference.yaml - 8 TTS entries

Version updates:
- VERSION: 3.11.0 → 3.11.1
- README.md: Template count 71 → 83
- CHANGELOG.md: Added v3.11.1 entry
- Synced version across all docs (cheatsheet, ultimate-guide, reference.yaml)

Other:
- .gitignore: Added audio file exclusions (*.wav, *.mp3, *.onnx)

Context: Tested Agent Vibes v3.0.0 + Piper TTS with French voices. Works offline, no cloud dependency.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
 2026-01-22 16:08:32 +01:00
Florian BRUNIAUX
be91799dcf feat: add cc-copilot-bridge reference in examples 
- Created multi-provider/ directory with redirect to dedicated repo
- Added cc-copilot-bridge in examples index table
- Added Multi-Provider Bridge section with link to github.com/FlorianBruniaux/cc-copilot-bridge

Related: github.com/FlorianBruniaux/cc-copilot-bridge v1.2.0

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-01-22 11:25:40 +01:00
Florian BRUNIAUX
8c93c31b90 feat(guide): add Product Designer learning path and design-to-code workflow 
Add comprehensive resources for Product Designers working with Claude Code via Figma MCP:

- New workflow: guide/workflows/design-to-code.md (700 lines)
  - Documented metrics: 62% reduction in design inconsistencies, 78% workflow efficiency improvement
  - 4 core workflows: Frame→Component, Design System Audit, Token Automation, Visual Iteration
  - 3-tier token hierarchy (base/composite/semantic)
  - Team adoption patterns for designers, developers, PMs
  - Implementation roadmap (Foundation → Scaling → Orchestration)
  - Sources: builder.io, parallelhq.com, composio.dev, vladimirsiedykh.com

- New template: examples/claude-md/product-designer.md (400 lines)
  - Complete CLAUDE.md configuration for design-to-code projects
  - Figma MCP commands reference
  - Design handoff checklist
  - Token conventions and implementation constraints

- Updated README.md: Added "Product Designer" learning path (5 steps)
  - Positioned after DevOps/SRE, before main content
  - Links to image analysis, wireframing, Figma MCP, new workflow, cheatsheet

- Updated machine-readable/reference.yaml: Added 4 new entries
  - product_designer_workflow, product_designer_claudemd
  - design_system_handoff, figma_make_integration

Templates count: 72 → 73 (examples/claude-md/product-designer.md)
Guide workflows: 6 → 7 (guide/workflows/design-to-code.md)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
 2026-01-22 09:15:16 +01:00
Florian BRUNIAUX
fcc6f2dba3 feat(skills): add design-patterns analyzer skill 
Comprehensive GoF design patterns analyzer with stack-aware suggestions.

**Features**:
- Detects 23 GoF patterns (Creational, Structural, Behavioral)
- Stack detection (React, Angular, NestJS, Vue, Express, RxJS, Redux, ORMs)
- Code smell detection with pattern suggestions
- Quality evaluation (5 criteria scoring)
- Prefers stack-native alternatives (e.g., React Context over Singleton)

**Structure**:
- 9 files: SKILL.md + reference docs + detection rules + evaluation checklists
- 3 operating modes: Detection, Suggestion, Evaluation
- Pattern-specific documentation for all 23 GoF patterns

**Documentation**:
- Added comprehensive example in guide section 5.4
- Updated examples/README.md with skill entry
- Updated template count: 65 → 66

**Use cases**:
- Analyze existing patterns in codebase
- Suggest refactoring with stack-native patterns
- Evaluate pattern implementation quality

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
 2026-01-21 13:46:20 +01:00
Florian BRUNIAUX
00df38d318 feat: add DevOps & SRE Guide with FIRE Framework (v3.9.9) 
New files:
- guide/devops-sre.md: FIRE Framework for infrastructure diagnosis (~870 lines)
- examples/agents/devops-sre.md: DevOps/SRE agent persona
- examples/claude-md/devops-sre.md: CLAUDE.md template for infra projects

Guide includes:
- Kubernetes troubleshooting prompts by symptom
- Solo incident response workflow (3 AM design)
- IaC patterns (Terraform, Ansible, GitOps)
- Claude limitations table (transparency)
- Team adoption checklist

Updated:
- README.md: Added DevOps/SRE learning path, templates count → 69
- ultimate-guide.md: Added reference after Section 5.4
- reference.yaml: Added 11 DevOps/SRE entries
- examples/README.md: Added to indexes

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-20 22:09:31 +01:00
Florian BRUNIAUX
360e5203f6 feat: add Voice-to-Text section and voice-refine skill 
- Add section 5 "Voice-to-Text Tools" to ai-ecosystem.md
  - Tool comparison (Wispr Flow, Superwhisper, MacWhisper)
  - Vibe Coding workflow and trade-offs
  - Recommendations by user profile
- Create voice-refine skill in examples/skills/
  - Transforms verbose voice input into structured prompts
  - 4-step pipeline: Dedupe → Extract → Structure → Compress
  - Before/after examples with ~3.3x compression ratio
- Update reference.yaml with new entries and corrected line numbers
  - ai_ecosystem_voice_to_text: line 449
  - voice_refine_skill: new skill reference
  - cowork_section: 701 → 760
  - alternative_providers: 902 → 959

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-20 10:11:03 +01:00
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
Florian BRUNIAUX
dab11d260c feat: reorganize learning commands under /learn namespace 
- Move quiz.md → learn/quiz.md (/learn:quiz)
- Add learn/teach.md (/learn:teach) for step-by-step concept explanations
- Add learn/alternatives.md (/learn:alternatives) for approach comparisons
- Update all references in guide, README, and reference.yaml

Follows Claude Code namespaced commands convention:
/namespace:command → .claude/commands/namespace/command.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-19 11:13:54 +01:00
Florian BRUNIAUX
a5f441bcea feat: add ecosystem positioning, install script & new commands 
Ecosystem & Positioning:
- Add README section with competitive positioning (davila7, awesome-claude-code, wesammustafa)
- Add comparison table highlighting unique features (architecture, TDD/SDD, quiz, YAML index)
- Add ecosystem section to reference.yaml

Template Installation:
- Add scripts/install-templates.sh for one-liner template installation
- Support for agents, hooks, commands, skills, memory templates

New Commands:
- catchup, explain, optimize, refactor, security, ship

New Content:
- Semantic anchors catalog and documentation
- Extended guide content (+470 lines)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-19 08:42:33 +01:00
Florian BRUNIAUX
77d6d8eeb6 docs: update Extended Thinking documentation (v2.0.67+ changes) 
- Thinking mode now ON by default at max budget with Opus 4.5
- Keywords "think", "think hard", "ultrathink" are cosmetic only
- Control via Alt+T (session) or /config (permanent)
- Update Trinity pattern references
- Update quiz questions (09-001, 09-002, 04-014)
- Update cheatsheet thinking section
- Add note about cosmetic flags in modes README

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-18 18:25:20 +01:00
Florian BRUNIAUX
7fd4048d5e feat: add learning guide & website badge 
- Add "Visit Website" badge to README.md (prominent, top position)
- Add learning-with-ai.md guide for junior developers (~900 lines)
  - UVAL Protocol, dependency patterns, 30-day progression plan
- Add 3 learning templates (55 total):
  - examples/claude-md/learning-mode.md
  - examples/commands/quiz.md
  - examples/hooks/bash/learning-capture.sh
- Fix template count: 52 → 55 (was incorrectly showing 56)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-17 18:42:34 +01:00
Florian BRUNIAUX
6f968dbfc5 fix(sync): update landing sync script for new directory structure 
- Change examples.html → examples/index.html
- Change quiz.html → quiz/index.html
- Add fresh-context-loop.sh script

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-17 15:42:03 +01:00
Florian BRUNIAUX
4a79455c4d docs(images): add wireframing tools & Figma MCP documentation 
- Add Wireframing Tools section (Excalidraw, tldraw, Frame0, Paper+Photo)
- Add Figma MCP Integration with official setup and workflow
- Add Image Optimization for Claude Vision (resolution, tokens, formats)
- Create examples/mcp-configs/figma.json config template
- Update reference.yaml with new entries and shifted line numbers

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-17 15:34:52 +01:00
Florian BRUNIAUX
174192f583 feat(seo): add CITATION.cff and improve AI discoverability 
- Add CITATION.cff for academic citations and GitHub citation button
- Add "For AI Assistants" section in README with llms.txt reference
- Update machine-readable/llms.txt stats (4700+ → 9600+ lines)
- Bump version display to 3.8.0 in README footer

Improves discoverability in GitHub search, Google Scholar, and AI assistants

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-17 11:21:58 +01:00
Florian BRUNIAUX
846e2e6a1b docs(mcp): add grepai semantic search and call graph documentation 
- Add grepai section in ultimate-guide.md (Section 8.3)
  - Privacy-first semantic code search using Ollama embeddings
  - Call graph analysis: trace callers, callees, dependency graphs
  - Combined workflow with Serena for exploration + editing
  - Setup instructions and MCP tools reference
- Update decision tree and comparison table to include grepai
- Add grepai config to examples/config/mcp.json
- Document changes in CHANGELOG.md [Unreleased]

Source: https://github.com/yoanbernabeu/grepai

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-15 10:56:18 +01:00
Florian BRUNIAUX
71a08ca36a feat(scripts): session-search v2.1 - JSON encoding fix and clean previews 
Bug fixes on top of v2.0:
- json_escape() function: proper backslash/quote escaping
- Preview cleanup: strip XML tags (<local-command-caveat>)
- Filter non-printable unicode characters

Quality score: 8/10 → 9.3/10

Tested with 239 sessions, all features validated.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-15 10:20:52 +01:00
Florian BRUNIAUX
785727d16c feat(scripts): session-search v2.0 with advanced filtering 
- Multi-word AND search (all words must match)
- Project filter (-p, --project)
- Date filter (--since today/7d/30d/YYYY-MM-DD)
- JSON output (--json) for scripting
- Improved preview extraction (skips tool results)
- 3s search timeout for safety
- Updated documentation in observability.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-15 09:52:54 +01:00
Florian BRUNIAUX
46c5862c4e fix(docs): critical factual corrections v3.6.1 
Major audit correcting misleading documentation about Claude Code behavior:

### Fixed
- `--add-dir`: permissions (not context loading)
- `excludePatterns` → `permissions.deny` (never existed)
- `.claudeignore` removed (not an official feature)
- "selective loading" myth → lazy loading reality
- Invented CLI flags (`--think`, `--headless`, `--learn`) → prompt keywords
- `@` file reference: "loads automatically" → "reads on-demand"

### Added
- Session Search Tool (`cs`) - zero-dep bash script for finding sessions
- Security section: Known limitations of permissions.deny

15 files modified, 516 insertions, 200 deletions

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-15 09:16:53 +01:00
Florian BRUNIAUX
34b2ca7200 feat(security): add security hardening guide and hooks v3.6.0 
- Add guide/security-hardening.md (~10K) covering:
  - MCP vetting workflow with CVE-2025-53109/53110, 54135, 54136
  - Prompt injection evasion techniques (Unicode, ANSI, null bytes)
  - Secret detection tool comparison (Gitleaks, TruffleHog, GitGuardian)
  - Incident response procedures

- Add 3 new security hooks:
  - unicode-injection-scanner.sh: zero-width, RTL, ANSI escape detection
  - repo-integrity-scanner.sh: scan README/package.json for injection
  - mcp-config-integrity.sh: verify MCP config hash

- Update existing hooks:
  - prompt-injection-detector.sh: +ANSI, +null bytes, +nested cmd
  - output-secrets-scanner.sh: +env leakage, +generic tokens

- Update cross-references in ultimate-guide.md (§7.4, §8.6)
- Move MCP Security Hardening to Done in IDEAS.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-15 07:39:53 +01:00
Florian BRUNIAUX
f9044e2deb feat(docs): add architecture deep-dive documentation v3.4.0 
Add comprehensive technical documentation explaining Claude Code internals:

- NEW: guide/architecture.md (~800 lines) - Complete architecture deep-dive
  - Master Loop (while tool_call), Tool Arsenal, Context Management
  - Sub-Agent Architecture, Permission System, MCP Integration
  - Edit Tool mechanics, Session persistence, Philosophy comparison
  - 5 ASCII diagrams, source confidence tiers (Tier 1/2/3)

- guide/ultimate-guide.md: Add Section 2.7 "Under the Hood" summary
- guide/cheatsheet.md: Add "Under the Hood (Quick Facts)" section
- machine-readable/reference.yaml: Add architecture index + deep_dive refs
- Update all navigation links across repository

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-14 21:29:46 +01:00
Florian BRUNIAUX
8a4d116e2e feat(docs): add LLM Handbook + Google Whitepaper integration v3.3.0 
Advanced Guardrails:
- prompt-injection-detector.sh (PreToolUse)
- output-validator.sh (PostToolUse heuristics)
- claudemd-scanner.sh (SessionStart injection detection)
- output-secrets-scanner.sh (PostToolUse secrets leak prevention)

Observability & Monitoring:
- session-logger.sh (JSONL activity logging)
- session-stats.sh (cost tracking & analysis)
- guide/observability.md (full documentation)

LLM-as-a-Judge Evaluation:
- output-evaluator.md agent (Haiku)
- /validate-changes command
- pre-commit-evaluator.sh (opt-in git hook)

Google Agent Whitepaper Integration:
- Context Triage Guide (Section 2.2.4)
- CLAUDE.md Injection Warning (Section 3.1.3)
- Agent Validation Checklist (Section 4.2.4)
- MCP Security: Tool Shadowing & Confused Deputy (Section 8.6)
- Session vs Memory patterns (Section 3.3.3)

Stats: 10 new files, 8 modified, 5 new guide sections

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-14 21:00:49 +01:00
Florian BRUNIAUX
19110eba22 feat(docs): add comprehensive data privacy documentation v3.2.0 
- Create guide/data-privacy.md with retention policies (5y/30d/0)
- Add privacy notice to README.md
- Add section 2.6 "Data Flow & Privacy" to ultimate-guide.md
- Add Golden Rule #7 to cheatsheet.md (know what's sent)
- Add Phase 0.5 Privacy Awareness to onboarding-prompt.md
- Add privacy checks to audit-prompt.md
- Add PRIVACY CHECK section to audit-scan.sh (human + JSON)
- Add privacy reminder to check-claude.sh
- Create privacy-warning.sh SessionStart hook

Addresses user awareness of Anthropic data retention and opt-out options.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-14 20:42:19 +01:00
Florian BRUNIAUX
bc07651cdf refactor: restructure repo into thematic directories v3.1.0 
Major repository reorganization for improved navigation:

New directory structure:
- guide/ - Core documentation (ultimate-guide, cheatsheet, adoption)
- tools/ - Interactive utilities (audit, onboarding, mobile-access)
- machine-readable/ - LLM/AI consumption (reference.yaml, llms.txt)
- exports/ - Generated outputs (PDFs)

Changes:
- Move 10 files to thematic directories with cleaner names
- Create README.md index for each new directory
- Update 150+ internal links across all documentation
- Add "Repository Structure" section to main README
- Remove redundant npm install command from README header
- Remove unverified cost estimate from prerequisites
- Fix broken anchor link (#-quick-start-15-minutes)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-13 15:30:02 +01:00
Florian BRUNIAUX
ebf1506196 fix(audit): ALL_DEPS unbound variable + extended integrations 
- Initialize ALL_DEPS="" to prevent unbound variable error outside Node.js projects
- Added 35+ new integration detections: Kinde, LemonSqueezy, Vercel AI SDK,
  TalkJS, Knock, Stream, MapLibre, Mapbox, Google Maps, Bytescale, UploadThing,
  Cloudinary, Forest Admin, Refine, Vercel Analytics, Mixpanel, Hotjar, etc.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-13 08:42:49 +01:00
Florian BRUNIAUX
0e04c51a5d feat(commands): add /diagnose interactive troubleshooting assistant v3.0.4 
- New diagnose.md command with bilingual support (FR/EN)
- 12 problem categories: permissions, MCP, config, performance, installation
- Auto-fetches latest guide from GitHub for up-to-date troubleshooting
- Integrates with audit-scan.sh --json for environment scanning
- Structured output: diagnostic → solution → template → reference

Updated: README, examples/README, CHANGELOG, cheatsheet, guide (section 10.4)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-13 08:41:54 +01:00
Florian BRUNIAUX
41bf57d9ee feat(audit): SSoT warning + incremental suggestions prompt 
Script:
- needs_ssot_refactor flag: warns if CLAUDE.md >100 lines with 0 @refs
- Red warning in human output suggesting SSoT pattern

Prompt:
- Focus on incremental improvements, not generic advice
- Stricter health score (penalize missing SSoT)
- Domain-specific quick wins only
- Improve existing CLAUDE.md instead of full rewrite
- Don't suggest duplicates of existing agents/commands

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-12 15:08:06 +01:00
Florian BRUNIAUX
5b526f5e53 feat(audit): enhanced stack detection with integrations 
- Detailed stack breakdown: runtime, framework, test, bundler, database
- Generic integration detection (25+ packages: Clerk, Stripe, OpenAI, Sentry...)
- jq fallback: grep-based JSON parsing when jq not installed
- Stack recap at top of human output + full stack object in JSON
- README prompt updated: Stack Recap first, CLAUDE.md template ~100 lines

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-12 14:52:55 +01:00
Florian BRUNIAUX
98044a0a47 fix(audit-scan): count files recursively in subfolders 
- Commands in subfolders (tech/, product/, support/) now counted correctly
- Split count_files() into count_md_files() and count_script_files()
- Hooks counted as scripts (.sh/.js/.py/.ts), others as .md
- Excludes README.md from counts
- Bug: Was reporting 0 commands when 10 existed in subfolders
- Bump version to 2.9.6

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-12 14:20:53 +01:00
Florian BRUNIAUX
d32052eff6 feat(examples): add Learning Mode template with SuperClaude reference 
- Create examples/modes/ folder with MODE_Learning.md ready to copy
- Add modes/README.md with installation guide and SuperClaude link
- Update examples/README.md with modes section
- Bump version to 2.9.4 across all files

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-12 13:38:02 +01:00
Florian BRUNIAUX
0833e1ca65 fix(audit): correct MCP detection to check ~/.claude.json 
The audit script was looking for MCP config in ~/.claude/mcp.json which
doesn't exist. Claude Code actually stores MCP config in ~/.claude.json
under projects.<path>.mcpServers.

Changes:
- audit-scan.sh: Multi-source MCP detection (3 locations with priority)
- audit-scan.sh: Fixed count_pattern() bug causing "0\n0" output
- claude-setup-audit-prompt.md: Updated bash commands for MCP detection
- Version bump: 2.8 → 2.9

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-12 08:37:01 +01:00
Florian BRUNIAUX
2714159acb docs: complete examples catalog with GitHub Actions and workflows 
- Add GitHub Actions section to main README Production-Ready Examples
- Update examples/README.md with github-actions/ and workflows/ folders
- Add complete templates index for CI/CD workflows
- Bump version to 2.8 across all documentation files

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 2026-01-11 19:10:47 +01:00
Florian BRUNIAUX
869f0df782 feat: optimize audit prompt with bash scanning (v2.7.0) 
Add fast bash-based setup scanner for 80% speed improvement:
- New audit-scan.sh script with JSON/human output modes
- Rewrite audit prompt Phase 1-2 to use grep/find/wc
- Update README with dual-option audit approach
- Token reduction from ~5000 to ~500 (90% improvement)
- Execution time from ~30s to ~2s

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
 2026-01-11 14:39:46 +01:00
Florian BRUNIAUX
76845f8226 chore: release v2.5.0 with content optimization and script externalization 
- Remove ~1048 lines of non-Claude-Code-specific content (-10.9%)
- Externalize health check and reinstall scripts to examples/scripts/
- Clean up table of contents and fix broken references
- Update version numbers and statistics across all documentation

Removed sections:
- DeepSeek Integration (200 lines)
- Git Archaeology Pattern (250 lines)
- Emergency Hotfix Checklist (140 lines)
- Maturity Model & Success Metrics (95 lines)
- Generic Prompt Templates (105 lines)
- Task-specific checklists

New files:
- examples/scripts/check-claude.{sh,ps1}
- examples/scripts/clean-reinstall-claude.{sh,ps1}

Stats: 9593 → 8545 lines, focus on Claude Code-specific content

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
 2026-01-11 13:52:19 +01:00
Florian BRUNIAUX
07b8810fe3 feat(workflows): add database branch isolation with git worktrees 
Add comprehensive documentation for combining git worktrees with database branches
for true feature isolation across Neon, PlanetScale, Supabase, and local Postgres.

Changes:
- examples/commands/git-worktree.md: Add database branch detection and quick reference (~90 lines)
- examples/workflows/database-branch-setup.md: New complete guide with TL;DR and provider workflows (349 lines)
- english-ultimate-claude-code-guide.md: Add section 9.12 "Database Branch Isolation with Worktrees" (~95 lines)
- CHANGELOG.md: Add v2.4.0 release notes
- README.md: Update version to 2.4, line count to 9500+, add source attributions

Architecture: Progressive disclosure pattern (concise command → complete workflow guide)
Sources: Neon branching docs, PlanetScale branching docs

Stats: ~540 lines added | Guide now 9,592 lines, 35,576 words

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
 2026-01-11 13:25:58 +01:00
Florian BRUNIAUX
162b8562cf docs: release v2.3.0 with DeepTo guide integration 
- Add DeepTo Claude Code Guide reference to Resources section
- Document all DeepTo additions in CHANGELOG:
  • Image processing (direct terminal input)
  • Session continuation/resume (--continue, --resume)
  • XML-structured prompts (semantic tags)
  • ccusage CLI tool (cost analytics)
  • Unix piping workflows (automation patterns)
- Update version to 2.3 across all documentation
- Include proper source attribution throughout

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
 2026-01-10 17:55:46 +01:00
Florian BRUNIAUX
96f0435291 feat(examples): add production-ready commands, hooks, and comprehensive documentation 
Added 3 production slash commands:
- /pr: PR creation with complexity scoring and scope analysis
- /release-notes: Generate release notes in 3 formats with migration detection
- /sonarqube: Analyze SonarCloud quality issues for PRs

Added 2 production hooks:
- dangerous-actions-blocker.sh: PreToolUse security hook blocking destructive operations
- notification.sh: Contextual macOS alerts with sound mappings

Created comprehensive hooks documentation (examples/hooks/README.md)

Improved README discoverability:
- Moved "What's Inside" to line 24 for immediate visibility
- Added DeepWiki interactive documentation explorer section
- Added "Ready-to-Use Examples" section with command/hook tables

Extended guide documentation:
- Expanded bash mode (!) with 9 concrete examples
- Documented file references (@) with usage patterns
- Updated statistics: guide now 8,505 lines (+837 lines, +10.9%)

All templates are fully generic with no project-specific references.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
 2026-01-10 17:30:30 +01:00
Florian BRUNIAUX
2dd2744721 feat: add git best practices, worktrees, and cost optimization sections 
- Add Section 9.12: Git Best Practices & Workflows (~400 lines)
  - Commit message best practices with Conventional Commits
  - Git amend workflow with safety rules
  - Branch management and naming conventions
  - Rewind vs Revert decision tree
  - Comprehensive git worktrees documentation
- Add Section 9.13: Cost Optimization Strategies (~350 lines)
  - Model selection matrix (Haiku/Sonnet/Opus)
  - OpusPlan mode for efficient workflows
  - Token-saving techniques and cost tracking
  - ROI calculations and economic workflows
- Add examples/commands/git-worktree.md slash command template
- Update CHANGELOG.md with v2.0.0 additions
- Update version metadata to 2.0 across documentation

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
 2026-01-10 17:00:45 +01:00
Florian BRUNIAUX
2f84c2a769 feat(guide): comprehensive improvements - troubleshooting, CLI ref, pitfalls, DeepSeek 
MAJOR ENHANCEMENTS:

## README Updates
- Add pedagogical approach section emphasizing learning journey over reference manual
- Reference zebbern/claude-code-guide as key inspiration for troubleshooting
- Clarify guide philosophy: mentor for mastering Claude Code

## Main Guide (english-ultimate-claude-code-guide.md)

### New Sections Added:
1. **Status Overview Table** - Section completeness at a glance
2. **Section 10.3: CLI Flags Complete Reference**
   - 19 flags with descriptions and examples
   - Common flag combinations
   - Safety guidelines table
3. **Section 10.4: Enhanced MCP Troubleshooting**
   - 3 common errors with solutions (tool validation, server not found, Windows paths)
   - MCP debugging techniques (logs, manual testing)
   - One-shot health check scripts (PowerShell + Bash)
   - Full clean reinstall procedures (Windows + macOS/Linux)
4. **Section 9.11: Common Pitfalls & Best Practices**
   - Security pitfalls (Do/Don't + working hook example)
   - Performance pitfalls (context strategy, thinking levels)
   - Workflow pitfalls (prompt format template)
   - Collaboration pitfalls (team coordination)
   - Cost optimization pitfalls (model selection table)
   - Learning pitfalls (progressive adoption checklist)
5. **Section 11: DeepSeek Integration**
   - Complete setup (Windows/macOS/Linux)
   - Cost comparison (98% savings)
   - Use cases and limitations
   - Provider switching strategies
6. **Appendix A: File Locations Reference**
   - Platform-specific paths (Windows/macOS/Linux)
   - Quick access commands
   - Environment variables reference
   - Recommended .gitignore

## Cheatsheet (cheatsheet-en.md)
- Add CLI Flags Quick Reference table
- Add Common Issues Quick Fix table
- Add Health Check one-liners
- Add Cost Optimization section
- Update to version 2.0

## GitHub Actions (examples/github-actions/)
- **claude-pr-auto-review.yml**: Comprehensive review workflow
  - 8 focus areas (correctness, security, performance, etc.)
  - Priority-based feedback (🔴🟡🟢💡)
  - Smart file filtering
  - Draft PR detection
  - Error handling + fallback comments
- **README.md**: Update workflow #1 documentation with new features

## Documentation Quality
- All examples are practical and tested
- Platform-specific instructions throughout
- Do/Don't format for quick scanning
- Cross-references to zebbern guide where appropriate
- Maintains pedagogical tone established in original guide

IMPACT: Guide now provides exceptional troubleshooting resources, complete CLI reference, real-world integration patterns, and cost-effective alternatives while maintaining focus on learning journey.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
 2026-01-10 15:47:26 +01:00
Florian BRUNIAUX
87994bb797 feat(guide): add thinking keywords, GitHub Actions examples, and improvement recommendations 
Documentation enhancements:
- Add inline thinking keywords section (think, think hard, ultrathink) with usage examples
- Create examples/github-actions/ directory with 3 ready-to-use workflows:
  * Auto PR review with inline comments
  * Security review on every PR
  * Issue triage with label suggestions
- Add comprehensive IMPROVEMENT_RECOMMENDATIONS.md with prioritized action items

Improvements based on zebbern/claude-code-guide analysis:
- Enhanced troubleshooting guidance
- Format enhancements (badges, collapsible tables, C-style comments)
- Security/performance/workflow pitfalls sections
- DeepSeek integration documentation
- One-shot health check scripts

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
 2026-01-10 15:26:18 +01:00