Explaining Code & Educational Prompts
Relevant source files
The following files were used as context for generating this wiki page:
- PROMPTS.md
- README.md
- index.html
- .devcontainer/ (Referenced for environment setup)
- claude CLI Tool (Referenced as the primary interface)
The Explaining Code & Educational Prompts system is the core methodology of the "Vibe Coding" workflow. It enables users to bridge the gap between plain-language descriptions and functional software by utilizing Claude as a real-time pair programmer. The scope of this system covers initial project scaffolding, iterative development, and educational decomposition of generated code.
This module relies on the "Describe → Look → Refine" loop, where the user provides intent, observes the rendered result in a live preview, and uses specific prompting strategies to adjust the output. This process effectively replaces manual syntax writing with high-level architectural direction.
Sources: index.html:18-21, README.md:43-46
The Vibe Coding Workflow
The workflow is designed to be accessible to users with no prior experience, relying on a terminal-based interface to interact with the LLM.
Development Loop logic
The system operates on a continuous feedback loop:
- Describe: User inputs a "Starter" prompt.
- Look: The system automatically serves the page (via
serve .) and opens a preview. - Refine: User applies "Iterative" prompts to fix bugs or add features.
The diagram shows the iterative cycle where user descriptions are transformed into code and refined through observation.
Sources: README.md:43-48, index.html:20-22
Educational and Explanatory Prompts
Beyond building features, the system includes a specific "Explain" move intended for educational purposes. Users can query the underlying logic of the generated code to understand how specific components function.
Iteration Moves
The system categorizes prompts into specific "moves" to help users direct the AI effectively:
| Move | Purpose | Example Interaction |
|---|---|---|
| Add | Introduce new components or behaviors | "Add a streak counter" |
| Change | Modify aesthetics or existing logic | "Change colors to navy and gold" |
| Fix | Debugging errors or unintended behavior | "It's doing [x] but I want [y]" |
| Explain | Educational code analysis | "What does this part do?" |
| Polish | Professionalism and responsiveness | "Make it work on a phone" |
Sources: PROMPTS.md:73-78
Implementation Templates
The project provides five primary educational "Starter" templates that demonstrate different logic structures, from simple UI hubs to state-persistent trackers.
1. Link Hub (Static UI)
Focuses on CSS and basic HTML structure.
- Key Prompt: "Build me a clean one-page personal website..."
- Logic: Modern layout, button links, and mobile responsiveness.
Sources: PROMPTS.md:6-14
2. Interactive Calculator (Functional Logic)
Demonstrates real-time calculation and user input handling.
- Logic: Bill splitting, percentage calculations, and rounding toggles.
- Key Feature: "Make the result update the instant I change anything."
Sources: PROMPTS.md:17-27
3. Habit Tracker (State Persistence)
Introduces the concept of browser-based data storage.
- Logic: Saving data in the browser (Local Storage) so it persists across sessions.
- Architecture: Row-based history for the last 7 days.
Sources: PROMPTS.md:30-40
4. Flashcard App (State Management)
Demonstrates data manipulation and shuffling.
- Logic: Flipping cards (toggle state), shuffling arrays, and filtering ("got it" vs "review").
Sources: PROMPTS.md:43-53
5. Event Countdown (Time & Animation)
Focuses on JavaScript timers and visual triggers.
- Logic: Calculating time differences (days, hours, minutes, seconds) and triggering events (confetti) at zero.
Sources: PROMPTS.md:56-68
System Interaction Sequence
The following sequence diagram illustrates how the user interacts with the Claude CLI and the environment variables to initiate the educational coding session.
The diagram demonstrates the flow from authentication via environment variables to the automatic serving of the live preview after code generation.
Sources: README.md:21-48, index.html:18-22
Summary of Educational Commands
| Command | Usage | Context |
|---|---|---|
claude | Starts the interactive session | Terminal entry point |
export ANTHROPIC_API_KEY | Authenticates the session | Required for API access |
serve . | Starts a local web server | Typically automated by Claude |
Ctrl + C | Terminates active processes | Used for resetting the environment |
Sources: README.md:52-60
By using these prompts and commands, the system facilitates an environment where the "vibe" or intent of the user is translated into technical implementation, while maintaining a clear path for the user to query and understand the resulting code.
Sources: PROMPTS.md:73-78, README.md:62-65