Instructor Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The Instructor Guidelines outline the necessary procedures and architectural setup required to facilitate a "Vibe Coding" session. This project is designed as a 2-hour interactive workshop where students build web applications using Claude via a terminal-based interface within GitHub Codespaces. The instructor's primary responsibilities include managing the class API key, troubleshooting environment issues, and guiding the "describe → look → refine" development loop.
Sources: README.md:3-5, README.md:52-54
Workspace Architecture and Setup
The environment is containerized using DevContainers to ensure a zero-install experience for students. The infrastructure automatically pre-installs the Claude CLI and configures it to route through a spend-capped class proxy.
Environment Configuration
The .devcontainer/ directory contains the automation logic to prepare the student workspace. This setup ensures that once a student opens a GitHub Codespace, the environment is ready for the claude command immediately after the API key is provided.
The diagram shows the automated build steps that occur when a student launches the workspace.
Sources: README.md:10-14, README.md:52-54
Session Commands
Instructors must ensure students are familiar with the following CLI operations:
| Command | Purpose |
|---|---|
export ANTHROPIC_API_KEY=... | Sets the temporary session key provided by the instructor. |
claude | Launches the interactive AI coding session. |
serve . | Manually triggers the live preview of the current project. |
Ctrl + C | Terminates active terminal processes. |
Sources: README.md:36-43
Key Management and Security
The system utilizes a temporary class key for authentication. This key is never stored in the repository and must be provided by the instructor during the live session.
- Key Distribution: The instructor displays the
ANTHROPIC_API_KEYon a shared screen. - Authentication Flow: Students export this key to their environment variables.
- Proxy Routing: All requests from the
claudeCLI are routed through a spend-capped proxy to prevent budget overruns during the workshop.
The sequence diagram illustrates the lifecycle of the API key from instructor distribution to proxy-mediated request execution.
Sources: README.md:20-25, README.md:52-54
Pedagogical Strategy: The "Vibe Coding" Loop
The core skill taught is an iterative cycle of plain-language requests and visual feedback. Instructors should guide students through the "starter" and "iterate" phases defined in the curriculum.
The Development Loop
Students follow a three-step cycle:
- Describe: Use natural language to define requirements.
- Look: Observe the changes in the automatic preview tab.
- Refine: Ask for specific modifications or fixes based on the preview.
Sources: README.md:31-33, index.html:24-28
Prompting Tiers
The PROMPTS.md file provides tiered templates for various project types. Instructors should encourage students to start with a "Starter" prompt to get a functional base, then move to "Iterate" prompts to customize the application.
| Project Type | Starter Example | Common Iterations |
|---|---|---|
| Personal Hub | One-page site with bio and links | Adding photos, changing themes, mobile optimization |
| Calculators | Tip splitter or unit converter | Custom inputs, rounding logic, instant updates |
| Trackers | Habit or workout trackers | Browser persistence (localStorage), streaks, animations |
| Study Tools | Flashcard applications | Shuffling, "review" state management, progress tracking |
Sources: PROMPTS.md:1-68
Troubleshooting and Fallbacks
Instructors are responsible for resolving technical friction points during the session.
Common Issues
- API Key Errors: If the terminal is closed, the
exportcommand must be re-run in the new terminal session. - Setup Prompts: Upon the first execution of
claude, students must manually select "Yes" when asked "Do you want to use this API key?". - Codespace Failure: In the event of persistent Codespace issues, instructors should redirect students to use
claude.aiwith the Artifacts feature enabled as a secondary platform.
Sources: README.md:26-28, README.md:47-49
Persistence Logic
For trackers and study tools, instructors should explain that the code generated by Claude should use browser-based storage (e.g., localStorage) to ensure data persists across page refreshes.
Sources: PROMPTS.md:32, PROMPTS.md:44
Summary
The Instructor Guidelines focus on managing the containerized environment, facilitating secure API access through a class proxy, and mentoring students through an iterative, natural-language-driven development cycle. By leveraging pre-configured DevContainers and tiered prompting strategies, instructors can enable students to build functional web applications within a limited 2-hour timeframe without requiring prior programming experience.