Last active
January 6, 2026 02:41
-
-
Save nicolasmendonca/401baf8586b2789366f962deb55d071a to your computer and use it in GitHub Desktop.
Revisions
-
nicolasmendonca revised this gist
Jan 6, 2026 . 1 changed file with 144 additions and 0 deletions.There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode charactersOriginal file line number Diff line number Diff line change @@ -0,0 +1,144 @@ ⏺ HTML Output Style Guidelines Base HTML Template <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <title>Page Title</title> <!-- Google Sans Code Font (Playful theme) --> <link href="https://fonts.googleapis.com/css2?family=Google+Sans+Code:wght@300..800&display=swap" rel="stylesheet"> <!-- Tailwind CSS --> <script src="https://cdn.tailwindcss.com"></script> <script> tailwind.config = { theme: { extend: { fontFamily: { 'playful': ['"Google Sans Code"', 'monospace'], }, colors: { primary: { 50: '#fef3ff', 100: '#fce8ff', 500: '#d946ef', 600: '#c026d3', 700: '#a21caf' }, secondary: { 50: '#ecfeff', 100: '#cffafe', 500: '#06b6d4', 600: '#0891b2' }, } } } } </script> <!-- Flowbite CSS --> <link href="https://cdn.jsdelivr.net/npm/flowbite@2.5.2/dist/flowbite.min.css" rel="stylesheet"> <!-- Prism.js Syntax Highlighting (Tomorrow Night theme) --> <link href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css" rel="stylesheet"> <!-- Mermaid for diagrams --> <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script> </head> <body class="bg-gray-50 dark:bg-gray-900 font-playful"> <!-- Content sections go here --> <!-- Flowbite JS --> <script src="https://cdn.jsdelivr.net/npm/flowbite@2.5.2/dist/flowbite.min.js"></script> <!-- Prism.js Core + Languages --> <script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js"></script> <script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-typescript.min.js"></script> <script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js"></script> <script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-json.min.js"></script> <script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-yaml.min.js"></script> <!-- Initialize Mermaid --> <script>mermaid.initialize({ startOnLoad: true, theme: 'default' });</script> </body> </html> --- Code Syntax Highlighting (Prism.js) TypeScript <pre><code class="language-typescript"> import amqplib from 'amqplib'; const connection = await amqplib.connect('amqp://localhost'); const channel = await connection.createChannel(); </code></pre> Bash/Shell <pre><code class="language-bash"> docker compose up -d bun run dev </code></pre> JSON <pre><code class="language-json"> { "queue": "orders", "durable": true } </code></pre> Available Prism.js Languages - prism-typescript - TypeScript/JavaScript - prism-bash - Shell commands - prism-json - JSON configuration - prism-yaml - YAML/Docker compose files --- Mermaid Diagrams Embed diagrams using <pre class="mermaid">: <pre class="mermaid"> flowchart LR P[Producer] --> E[Exchange] E --> Q1[Queue 1] E --> Q2[Queue 2] Q1 --> C1[Consumer 1] Q2 --> C2[Consumer 2] </pre> Diagram Types | Type | Use Case | |-----------------|-----------------------------| | flowchart | Process flows, architecture | | sequenceDiagram | Request/response cycles | | classDiagram | System architecture, types | | erDiagram | Data relationships | --- Flowbite Component Mapping | Section | Component | Purpose | |----------------|-------------------------------|----------------------------| | Lesson Content | Cards + Typography | Conceptual explanations | | Architecture | Mermaid <pre class="mermaid"> | Visual diagrams | | Code Examples | Tabs | Multi-language code blocks | | Step-by-Step | Timeline + Cards | Sequential tasks | | Criteria | Checklist (checkboxes) | Verifiable outcomes | | Hints | Accordion (collapsed) | Progressive reveal | | Solutions | Accordion (nested) | Full code solutions | | Tips/Warnings | Alerts (info/warning) | Important callouts | | Navigation | Sidebar + Breadcrumb | Page navigation | | Progress | Progress bar | Completion tracking | --- Quick Reference CDN URLs: - Tailwind: https://cdn.tailwindcss.com - Flowbite CSS: https://cdn.jsdelivr.net/npm/flowbite@2.5.2/dist/flowbite.min.css - Flowbite JS: https://cdn.jsdelivr.net/npm/flowbite@2.5.2/dist/flowbite.min.js - Prism CSS: https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-tomorrow.min.css - Prism JS: https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js - Mermaid: https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js - Google Sans Code: https://fonts.googleapis.com/css2?family=Google+Sans+Code:wght@300..800&display=swap -
Jan 4, 2026 .There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode charactersOriginal file line number Diff line number Diff line change @@ -0,0 +1,774 @@ # Tutorial Generator Template This document provides Claude Code with complete instructions for generating structured, AI-guided tutorials for any technology. Follow these patterns to create tutorials that match the quality and structure of the Cloudflare Developer Platform tutorial. --- ## Table of Contents 1. [System Overview](#1-system-overview) 2. [Directory Structure](#2-directory-structure) 3. [LESSON.md Template](#3-lessonmd-template) 4. [EXERCISE.md Template](#4-exercisemd-template) 5. [HINTS.md Template](#5-hintsmd-template) 6. [CLAUDE.md Template](#6-claudemd-template) 7. [Coding Standards](#7-coding-standards) 8. [Generation Workflow](#8-generation-workflow) 9. [Quality Checklist](#9-quality-checklist) --- ## 1. System Overview ### Purpose This template enables Claude Code to autonomously generate complete, structured tutorials for any technology. The tutorials are designed to be: - **Hands-on**: Users build a real project, not isolated examples - **Progressive**: Each module builds on previous ones - **AI-guided**: Claude Code acts as an intelligent tutor - **Self-paced**: Users can work at their own speed with graduated hints ### Philosophy 1. **Learn by doing** - Concepts are introduced through practical implementation 2. **One thing at a time** - Each module adds exactly one major concept 3. **Fail safely** - Hints and solutions prevent frustration without removing challenge 4. **Real-world patterns** - Code follows production best practices ### How Claude Uses This Template When asked to generate a tutorial for a technology: 1. Read this entire template to understand the structure 2. Design an appropriate project concept for the technology 3. Plan 7-14 modules that progressively build the project 4. Generate all files following the templates below 5. Validate against the quality checklist --- ## 2. Directory Structure Every generated tutorial follows this structure: ``` <technology>-tutorial/ ├── README.md # Tutorial overview and prerequisites ├── CLAUDE.md # AI guidance instructions ├── package.json # Project metadata ├── biome.json # Linting configuration │ ├── modules/ │ ├── 00-setup/ │ │ ├── LESSON.md # Environment setup concepts │ │ ├── EXERCISE.md # Installation and first deployment │ │ └── HINTS.md # Troubleshooting setup issues │ │ │ ├── 01-<first-concept>/ │ │ ├── LESSON.md │ │ ├── EXERCISE.md │ │ └── HINTS.md │ │ │ ├── 02-<second-concept>/ │ │ └── ... │ │ │ └── XX-<final-concept>/ │ └── ... │ └── <project-name>/ # User's working directory (empty initially) └── .gitkeep ``` ### Naming Conventions - **Module directories**: `XX-descriptive-name` (e.g., `02-database`, `05-authentication`) - **File names**: Uppercase for documentation (`LESSON.md`, `EXERCISE.md`, `HINTS.md`) - **Project directory**: Lowercase, descriptive name matching the project concept --- ## 3. LESSON.md Template The LESSON.md file teaches concepts and theory before the hands-on exercise. ### Structure ```markdown # Module X: <Title> <Welcome paragraph explaining what the user will learn and why it matters.> ## Why <Technology/Concept>? <Explain the problem this solves and why this approach is preferred.> - **Benefit 1** - Description - **Benefit 2** - Description - **Benefit 3** - Description ## <Core Concept 1> <Explanation with code examples.> ### <Subconcept> ```<language> // Example code with comments explaining key parts ``` <Additional explanation as needed.> ## <Core Concept 2> <Pattern continues for each major concept.> | Feature | Description | |---------|-------------| | Feature A | What it does | | Feature B | What it does | ## <Core Concept 3> <Include practical examples that relate to the project being built.> ```<language> // Code that directly applies to the project ``` ## Next Steps In the exercise, you'll: - <Task preview 1> - <Task preview 2> - <Task preview 3> ``` ### Guidelines 1. **Length**: 100-300 lines depending on complexity 2. **Code examples**: Show patterns, not full implementations 3. **Tables**: Use for feature comparisons or API summaries 4. **Tone**: Conversational but technical 5. **Context**: Reference the project being built throughout ### Example Excerpt ```markdown # Module 2: Persistent Storage with D1 In this module, you'll add a SQLite database to your API using Cloudflare D1. ## Why D1? D1 provides: - **SQLite at the edge** - Familiar SQL syntax, globally distributed - **Zero configuration** - No connection strings or pooling - **Automatic replication** - Read replicas close to users ## Creating Tables ```sql CREATE TABLE users ( id TEXT PRIMARY KEY, email TEXT UNIQUE NOT NULL, name TEXT NOT NULL, created_at TEXT DEFAULT CURRENT_TIMESTAMP ); ``` ## Next Steps In the exercise, you'll: - Create the D1 database - Write migrations for users and documents - Update your routes to use real data ``` --- ## 4. EXERCISE.md Template The EXERCISE.md file provides hands-on tasks with clear acceptance criteria. ### Structure ```markdown # Module X Exercise: <Action-Oriented Title> ## Objectives By the end of this exercise, you will have: - [ ] <Verifiable outcome 1> - [ ] <Verifiable outcome 2> - [ ] <Verifiable outcome 3> --- ## Task 1: <Clear Action Name> <Description of what to do and why.> ```bash # Commands to run command here ``` **Requirements**: 1. <Specific requirement> 2. <Specific requirement> 3. <Specific requirement> **Acceptance Criteria**: - [ ] <Testable condition> - [ ] <Testable condition> --- ## Task 2: <Clear Action Name> <Description continues...> | Method | Path | Description | |--------|------|-------------| | GET | `/endpoint` | What it does | | POST | `/endpoint` | What it does | **Expected Response**: ```json { "key": "value" } ``` **Acceptance Criteria**: - [ ] <Testable condition> --- ## Task N: Test Your Implementation <Final validation task.> ```bash # Test commands curl http://localhost:8787/endpoint ``` **Acceptance Criteria**: - [ ] All endpoints respond correctly - [ ] Error cases are handled --- ## Summary You've accomplished: - <What was built> - <What was learned> - <What this enables for future modules> --- ## Bonus Challenges 1. **Challenge Name**: Description of optional extension 2. **Challenge Name**: Description of optional extension ``` ### Guidelines 1. **Task count**: 5-12 tasks per module 2. **Horizontal dividers**: Use `---` between every task 3. **Acceptance criteria**: Every task MUST end with testable criteria 4. **Code blocks**: Include bash commands, expected JSON, code snippets 5. **Progressive difficulty**: Earlier tasks are simpler 6. **No solutions**: Tasks describe what to do, not how (that's in HINTS.md) ### Example Task ```markdown --- ## Task 3: Create Document Routes Create `src/routes/documents.ts` with the following endpoints: | Method | Path | Description | |--------|------|-------------| | GET | `/` | List all documents | | GET | `/:id` | Get single document | | POST | `/` | Create document | | DELETE | `/:id` | Delete document | **Requirements**: 1. Create a router using `new Hono()` 2. Use proper HTTP status codes (200, 201, 204, 404) 3. Return JSON responses with consistent structure **Acceptance Criteria**: - [ ] `GET /documents` returns `{ documents: [], total: 0 }` - [ ] `POST /documents` with valid JSON returns 201 - [ ] `DELETE /documents/:id` returns 204 with no body --- ``` --- ## 5. HINTS.md Template The HINTS.md file provides graduated assistance and complete solutions. ### Structure ```markdown # Module X: Hints & Solutions > **For Claude Code**: Use this document to help users who are stuck. Start with gentle hints before revealing solutions. --- ## Expected End State After completing this module, the user should have: ``` <project-name>/ ├── src/ │ ├── index.ts │ └── <new files from this module> ├── <config files> └── <other expected files> ``` ### Key Verifications - [ ] `<command>` works without errors - [ ] `<endpoint>` returns expected response - [ ] `<feature>` behaves correctly --- ## Common Issues ### Issue: "<Error message or symptom>" **Symptoms**: What the user sees or experiences **Cause**: Why this happens **Solution**: ```bash # Commands or code to fix it ``` --- ### Issue: "<Another common problem>" **Symptoms**: ... **Cause**: ... **Solution**: ... --- ## Task-by-Task Hints ### Task 1: <Task Name> **Hint 1** (gentle): <Point them in the right direction without giving away the answer> **Hint 2** (specific): <More concrete guidance with partial code or exact steps> **Solution**: ```<language> // Complete solution code ``` --- ### Task 2: <Task Name> **Hint 1** (gentle): ... **Hint 2** (specific): ... **Solution**: ... --- ## Debugging Checklist If things aren't working: - [ ] Dependencies installed: `bun install` - [ ] Dev server running: `bun run dev` - [ ] No TypeScript errors in IDE - [ ] Correct HTTP method (GET vs POST) - [ ] Request includes proper headers - [ ] <Technology-specific checks> ### Testing Commands ```bash # Health check curl http://localhost:8787/health # Create resource curl -X POST http://localhost:8787/resource \ -H "Content-Type: application/json" \ -d '{"key": "value"}' # Additional test commands... ``` --- ## Reference to Previous Modules If something from a previous module isn't working: - **Module 0 (Setup)**: Check that `<tool>` is installed and configured - **Module 1 (<Concept>)**: Verify `<file>` exists and exports correctly ``` ### Guidelines 1. **Length**: 300-800 lines (longest of the three files) 2. **Graduated hints**: Always provide Hint 1 → Hint 2 → Solution progression 3. **Common issues**: Include 3-6 likely problems with clear solutions 4. **Debugging checklist**: Technology-specific troubleshooting steps 5. **Complete solutions**: Include full working code for every task 6. **Cross-references**: Link to previous modules when relevant --- ## 6. CLAUDE.md Template The CLAUDE.md file instructs Claude Code on how to guide users through the tutorial. ### Structure ```markdown # Claude Code Tutorial Instructions This file instructs Claude Code on how to guide users through the <Technology> tutorial. ## Tutorial Mode ### Module Structure Each module has three documents: | File | Purpose | When to Read | |------|---------|--------------| | `LESSON.md` | Concepts and theory | Share with user at module start | | `EXERCISE.md` | Tasks and acceptance criteria | Guide user through these | | `HINTS.md` | Solutions, troubleshooting | Read when user is stuck | ### Starting a Module When the user says "start module X": 1. Read `modules/XX-name/LESSON.md` 2. Summarize key concepts conversationally 3. Ask if they have questions before proceeding 4. Read `modules/XX-name/EXERCISE.md` 5. Explain the tasks and acceptance criteria 6. Help them begin implementation ### During Implementation - **Provide hints, not solutions** - Guide discovery - Point to relevant documentation when helpful - Catch common mistakes early and explain why they're problematic - Encourage frequent testing with `bun run dev` ### When User Is Stuck 1. Read `modules/XX-name/HINTS.md` 2. Use graduated hint approach: - First: Check "Common Issues" for matching symptoms - Then: Provide **Hint 1** (gentle guidance) - If still stuck: Provide **Hint 2** (specific direction) - Last resort: Show the **Solution** 3. Use "Debugging Checklist" for systematic troubleshooting ### Checking Work When user says "check my work": 1. Read their implementation in `<project-name>/` 2. Compare against "Expected End State" in HINTS.md 3. Provide constructive feedback: - What they did well - What could be improved - Any bugs or issues --- ## Coding Standards <Include relevant standards from Section 7 of this template> --- ## Common Mistakes to Watch For 1. **<Mistake 1>** - Why it's a problem and how to fix 2. **<Mistake 2>** - Why it's a problem and how to fix 3. **<Technology-specific pitfall>** - Guidance --- ## Helpful Commands ```bash # Start development bun run dev # Run tests bun test # Deploy bun run deploy # <Technology-specific commands> ``` ``` --- ## 7. Coding Standards All generated tutorials enforce these standards: ### Tooling | Tool | Purpose | |------|---------| | **Bun** | Runtime, package manager, test runner | | **Biome** | Linting and formatting | | **TypeScript** | Type safety (strict mode) | ### TypeScript Rules #### Prefer Type Inference ```typescript // GOOD: Inferred return type function add(a: number, b: number) { return a + b; } // BAD: Unnecessary explicit type function add(a: number, b: number): number { return a + b; } ``` #### No Escape Hatches ```typescript // BAD: Escape hatches const data = response as any; const user = getUser()!; // GOOD: Proper typing const data = await response.json<UserResponse>(); const user = getUser(); if (!user) throw new Error("User not found"); ``` #### Use Generics Appropriately ```typescript // GOOD: Generic for type-safe results async function fetchJson<T>(url: string): Promise<T> { const response = await fetch(url); return response.json(); } ``` ### Naming Conventions ```typescript // BAD: Obscure names const u = await getU(id); const cb = () => { ... }; // GOOD: Descriptive names const authenticatedUser = await getUserById(userId); const handleFormSubmit = () => { ... }; ``` ### Documentation Add documentation blocks to non-trivial functions: ```typescript /** * Retrieves a document from storage and returns its metadata * along with a presigned URL for downloading the content. */ async function getDocumentWithDownloadUrl(documentId: string, userId: string) { // implementation } ``` ### Error Handling ```typescript // GOOD: Proper error handling async function getDocument(context: Context, documentId: string) { const document = await db.query("SELECT * FROM documents WHERE id = ?", [documentId]); if (!document) { throw new HTTPException(404, { message: "Document not found" }); } return document; } ``` --- ## 8. Generation Workflow When generating a tutorial, follow these steps: ### Step 1: Define Scope Determine: - Target technology (e.g., Supabase, AWS Lambda, Vercel) - Skill level (beginner, intermediate, advanced) - Time estimate (4-20 hours total) ### Step 2: Design Project Concept Create a project that: - Is practical and realistic - Uses most features of the technology - Has clear, incremental milestones - Can be completed in the target timeframe **Examples by technology type**: - Backend platform → Document management API - Frontend framework → Interactive dashboard - Database → Blog with comments and search - Cloud functions → Webhook processor ### Step 3: Plan Module Progression Design 7-14 modules that: 1. Start with environment setup 2. Introduce one major concept per module 3. Build cumulatively toward the complete project 4. End with deployment/production considerations **Typical progression**: ``` 00-setup → Environment and first deployment 01-<core-feature> → Primary technology feature 02-<data> → Data persistence 03-<storage> → File/asset handling 04-<caching> → Performance optimization 05-<async> → Background processing 06-<auth> → Authentication/authorization 07-<advanced> → Advanced patterns 08-<deployment> → Production deployment ``` ### Step 4: Generate Module Files For each module, create in order: 1. `LESSON.md` - Teach the concepts 2. `EXERCISE.md` - Define the tasks 3. `HINTS.md` - Provide solutions ### Step 5: Create Support Files Generate: - `README.md` - Tutorial overview - `CLAUDE.md` - AI guidance - `package.json` - Project metadata - `biome.json` - Linting config ### Step 6: Validate Run through the quality checklist (Section 9). --- ## 9. Quality Checklist Before completing a tutorial, verify: ### Structure - [ ] Every module has exactly 3 files: LESSON.md, EXERCISE.md, HINTS.md - [ ] Module directories are numbered sequentially (00, 01, 02...) - [ ] README.md provides clear overview and prerequisites - [ ] CLAUDE.md covers all module interactions ### Content Quality - [ ] LESSON.md teaches concepts before they're needed in EXERCISE.md - [ ] EXERCISE.md tasks have clear acceptance criteria - [ ] HINTS.md provides graduated hints (gentle → specific → solution) - [ ] No forward references to concepts not yet introduced ### Technical Accuracy - [ ] All code examples are syntactically correct - [ ] Bash commands use correct syntax - [ ] Technology-specific APIs are accurate - [ ] Error handling follows best practices ### Progression - [ ] Module 00 covers complete setup (can deploy hello world) - [ ] Each module builds on previous work - [ ] Complexity increases gradually - [ ] Final module results in complete, working project ### Code Standards - [ ] TypeScript strict mode throughout - [ ] No `any`, `unknown`, `as`, or `!` escape hatches - [ ] Descriptive variable and function names - [ ] Functions have documentation blocks - [ ] Bun used for package management and running ### User Experience - [ ] Tasks are appropriately sized (15-45 minutes each) - [ ] Common issues are documented in HINTS.md - [ ] Testing commands are provided - [ ] Bonus challenges extend learning --- ## Quick Reference ### File Purposes | File | Purpose | Length | |------|---------|--------| | LESSON.md | Teach concepts | 100-300 lines | | EXERCISE.md | Hands-on tasks | 200-500 lines | | HINTS.md | Solutions & troubleshooting | 300-800 lines | | CLAUDE.md | AI guidance | 100-200 lines | | README.md | Tutorial overview | 50-100 lines | ### Key Patterns - **Acceptance Criteria**: Every task ends with testable conditions - **Graduated Hints**: Hint 1 (gentle) → Hint 2 (specific) → Solution - **Progressive Complexity**: Setup → Core → Data → Advanced → Deploy - **Cumulative Project**: One project built throughout all modules ### Common Mistakes to Avoid 1. **Forward references** - Don't mention concepts before they're taught 2. **Missing acceptance criteria** - Every task needs testable outcomes 3. **Incomplete hints** - Always provide the full solution path 4. **Inconsistent standards** - Apply coding standards uniformly 5. **Isolated examples** - Examples should relate to the project being built