You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
### 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:
Acceptance Criteria:
Task 2:
Method
Path
Description
GET
/endpoint
What it does
POST
/endpoint
What it does
Expected Response:
{
"key": "value"
}
Acceptance Criteria:
Task N: Test Your Implementation
# Test commands
curl http://localhost:8787/endpoint
Acceptance Criteria:
All endpoints respond correctly
Error cases are handled
Summary
You've accomplished:
Bonus Challenges
Challenge Name: Description of optional extension
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
# 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:
/
├── src/
│ ├── index.ts
│ └──
├──
└──
### 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: ""
Symptoms: ...
Cause: ...
Solution: ...
Task-by-Task Hints
Task 1:
Hint 1 (gentle):
Hint 2 (specific):
Solution:
// Complete solution code
Task 2:
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
Testing Commands
# 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 (): 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
// BAD: Escape hatchesconstdata=responseasany;constuser=getUser()!;// GOOD: Proper typingconstdata=awaitresponse.json<UserResponse>();constuser=getUser();if(!user)thrownewError("User not found");
Use Generics Appropriately
// GOOD: Generic for type-safe resultsasyncfunctionfetchJson<T>(url: string): Promise<T>{constresponse=awaitfetch(url);returnresponse.json();}
Add documentation blocks to non-trivial functions:
/** * Retrieves a document from storage and returns its metadata * along with a presigned URL for downloading the content. */asyncfunctiongetDocumentWithDownloadUrl(documentId: string,userId: string){// implementation}
Error Handling
// GOOD: Proper error handlingasyncfunctiongetDocument(context: Context,documentId: string){constdocument=awaitdb.query("SELECT * FROM documents WHERE id = ?",[documentId]);if(!document){thrownewHTTPException(404,{message: "Document not found"});}returndocument;}
