How florianbruniaux/claude-code-ultimate-guide works
1. This repo is a documentation platform, not a single app. Its core product is the “Claude Code Ultimate Guide,” and the repository is organized around source content, machine-readable indexes, interactive utilities, and publication automation.
2. The primary content layer lives under guide/. It is the canonical human-readable knowledge base: the main guide (guide/ultimate-guide.md), deep-dive sections (guide/core/, guide/security/, guide/ops/, guide/workflows/, guide/roles/, guide/ecosystem/), and diagram pages (guide/diagrams/). These files are the source of truth for the website, PDF/EPUB exports, and the MCP server.
3. The examples/ tree is the repository’s pattern library. It holds concrete templates for agents, slash commands, hooks, skills, plugins, configs, scripts, and workflow examples. Architecturally, this is the “implementation catalog” that supports the conceptual guide: readers move from theory in guide/ to copyable patterns in examples/.
4. The quiz/ subsystem is a separate interactive product built from YAML question banks and a small JavaScript CLI app (quiz/src/). It turns the guide into a knowledge-checking workflow with scoring, profiles, and topic categories. The quiz depends on the content structure of the guide, but runs independently as a local Node-based app.
5. machine-readable/ is the indexing layer for automation and AI consumption. reference.yaml, llms.txt, and the release/content YAML files provide structured pointers into the guide and related artifacts. This layer is important because it is used by the landing-site search and by AI tools that need compact, deterministic context rather than full-text scraping.
6. The mcp-server/ directory is the main runtime integration boundary. It is a TypeScript MCP server packaged for npx use, exposing tools for searching and reading guide content, browsing examples, comparing releases, and querying threats. Internally it uses dedicated modules for content loading, caching, section reading, search, changelog parsing, and URL resolution, so it acts as a query API over the repository’s documentation corpus.
7. The repo’s automation layer sits in scripts/ and .github/workflows/. These scripts generate exports, preprocess guide content, update release data, validate onboarding material, and synchronize indexes/versioning. GitHub Actions then consume those outputs to rebuild exports and trigger the landing-site deployment, making publication a repeatable pipeline rather than a manual copy-paste process.
8. Security is a first-class subsystem rather than a topic buried in the guide. The security model is distributed across guide/security/, machine-readable/threat-db.yaml, and the security-focused example hooks/commands under examples/hooks/ and examples/commands/. The repo explicitly treats prompt injection, malicious skills, MCP trust, sandboxing, and data leakage as architectural concerns.
9. The docs/resource-evaluations/ tree is the curation and evidence layer. It contains structured reviews of external articles, tools, and ecosystem signals, which are then folded back into the guide’s recommendations. This creates a feedback loop: external research is evaluated, summarized, and incorporated into the canonical docs.
10. The publishing boundary is split between source and generated artifacts. Source content lives in Markdown/YAML/JS/TS/scripts, while outputs include PDFs, EPUBs, recap cards, exported landing content, and release assets under exports/ and related generated files. That separation matters for the diagram: content flows from source docs into indexes, exports, and deployment targets.
11. Operationally, the repo is maintained as a living knowledge base with versioning and daily refreshes. Files like CHANGELOG.md, VERSION, recap-hashes.json, and the release-update scripts indicate that the guide is continuously recompiled and re-indexed as Claude Code evolves.
12. The external-facing surfaces are the GitHub Pages landing site, downloadable guide artifacts, the MCP package, and the quiz CLI. In architectural terms, the repo supports three consumption modes: read the guide directly, query it through MCP/CLI automation, or consume generated/exported assets through the website and releases.
Main entry points: ultimate-guide.md Ultimate Guide · README.md Examples · index.ts MCP Server · reference.yaml Machine Indexes
Components 21
Canonical content
Human-authored guide source and its main topic sections
- Ultimate Guide · Main human-readable source of truth for the repo
guide/ultimate-guide.md - Core Topics · Foundational concepts, releases, glossary, and architecture
guide/core/architecture.md - Security · Safety, sandboxing, privacy, and governance guidance
guide/security/production-safety.md - Workflows · Operational patterns and end-to-end usage workflows
guide/workflows/README.md - Diagrams · Curated diagram pages for navigating the documentation system
guide/diagrams/README.md
Pattern library
Copyable examples for agents, commands, hooks, skills, and workflows
- Examples · Implementation catalog of reusable templates and patterns
examples/README.md - Agents · Representative agent templates and role definitions
examples/agents/planner.md - Commands · Slash-command examples for review, security, and workflow automation
examples/commands/security.md - Hooks · Event-driven guardrails, checkpoints, and session instrumentation
examples/hooks/README.md - Skills · Packaged reusable skills and sub-workflows
examples/skills/guide-recap/SKILL.md
Runtime surfaces
MCP server and quiz CLI that query or consume the guide
- MCP Server · TypeScript service exposing repository content as tools and resources
mcp-server/src/index.ts - Quiz CLI · Node-based knowledge-checking workflow over the guide
quiz/src/index.js - Search Guide · MCP search entrypoint over the guide corpus
mcp-server/src/tools/search-guide.ts - Threats Tool · MCP access to the security and threat knowledge layer
mcp-server/src/tools/threats.ts - Question Bank · Topic-based YAML questions that mirror the guide structure
quiz/questions/01-quick-start.yaml
Publication automation
Scripts and workflows that preprocess, export, and refresh repo artifacts
- Machine Indexes · Deterministic YAML and text indexes for automation and AI tools
machine-readable/reference.yaml - Release Data · Versioned release and changelog metadata used by refresh flows
machine-readable/claude-code-releases.yaml - Export Scripts · Scripts that preprocess guide content and generate distributable outputs
scripts/generate-guide-exports.sh - GitHub Actions · Workflows that rebuild exports and trigger landing-site deployment
.github/workflows/rebuild-guide-exports.yml
Research and curation
External evaluations folded back into the guide
- Resource Evaluations · Structured external research and evidence folded back into recommendations
docs/resource-evaluations/README.md
Published artifacts
Generated or distributable outputs
- Exports · Generated guide outputs and distributable assets
exports/README.md
Connections 29
- Ultimate Guide → Core Topics: structures · Main guide decomposes into core concepts and reference sections
- Ultimate Guide → Security: covers · Security is a first-class topic in the canonical guide
- Ultimate Guide → Workflows: covers · Workflows are documented as repeatable operating patterns
- Ultimate Guide → Diagrams: navigates · Diagram pages provide a visual entry to the guide
- Ultimate Guide → Examples: maps to · Concepts in the guide are grounded in copyable examples
- Examples → Agents: contains · Agent templates form one major example family
- Examples → Commands: contains · Command templates are part of the pattern library
- Examples → Hooks: contains · Hooks provide guardrails and event-driven automation patterns
- Examples → Skills: contains · Skills package reusable sub-workflows and behaviors
- Ultimate Guide → Machine Indexes: indexed by · Structured indexes expose guide content for deterministic lookup
- Machine Indexes → Release Data: includes · Release and changelog metadata are part of the machine-readable layer
- Machine Indexes → MCP Server: feeds · MCP tools consume the structured content indexes
- Ultimate Guide → MCP Server: queried via · The MCP server provides programmatic access to the documentation corpus
- MCP Server → Search Guide: exposes · Search is a primary MCP capability over the guide
- MCP Server → Threats Tool: exposes · Security/threat queries are exposed as a dedicated tool
- Quiz CLI → Question Bank: loads · The CLI runs against topic-based YAML questions
- Question Bank → Ultimate Guide: checks · Quiz content mirrors the guide’s structure and concepts
- Resource Evaluations → Core Topics: informs · Evaluations and external research feed back into recommendations
- Resource Evaluations → Security: informs · Security evaluations shape the repo’s defensive guidance
- Export Scripts → Exports: builds · Scripts generate PDFs, EPUBs, recap cards, and related artifacts
- Export Scripts → Machine Indexes: updates · Build scripts refresh machine-readable indexes and derived data
- GitHub Actions → Export Scripts: runs · GitHub Actions orchestrate the export and refresh scripts
- GitHub Actions → Exports: publishes · Workflows rebuild and deliver generated artifacts
- GitHub Actions → MCP Server: deploys · Automation also packages the MCP integration boundary
- Security → Threats Tool: anchors · Security guidance is surfaced through the threat-query tool
- Hooks → Security: implements · Security-oriented hooks operationalize the safety model
- Commands → Workflows: implements · Commands instantiate workflow patterns from the guide
- Agents → Workflows: implements · Agent templates operationalize collaborative workflows
- Diagrams → Core Topics: summarizes · Visual pages synthesize the core architecture