The Describe-Look-Refine Loop
Relevant source files
The following files were used as context for generating this wiki page:
The Describe-Look-Refine loop is the core operational methodology of the "Vibe Coding" workflow. It enables developers to build functional web applications using plain-language instructions instead of manual code entry. By leveraging Claude as a generative engine, the process shifts the developer's role from writing syntax to directing behavior and aesthetic outcomes through iterative feedback.
Sources: README.md:28-30, index.html:26-28
Iterative Development Workflow
The loop consists of three distinct phases that facilitate rapid prototyping and refinement of single-page web applications.
Phase 1: Describe
The process begins with a "Starter" prompt. Users describe the desired application in plain English, specifying functionality, initial layout, and primary components. This description is provided to the Claude interface within the terminal or a dedicated panel.
Phase 2: Look
Upon receiving instructions, Claude generates the necessary code, which automatically replaces the contents of index.html. A live preview is triggered, typically via the serve . command, allowing the user to immediately observe the rendered output in a side tab.
Phase 3: Refine
The user identifies necessary adjustments—such as aesthetic changes, bug fixes, or additional features—and provides follow-up "Iterate" prompts. This recursive step continues until the application meets the desired specifications.
Sources: README.md:28-34, index.html:28-28, PROMPTS.md:3-6
Workflow Visualization
The following diagram illustrates the continuous cycle of the Describe-Look-Refine loop:
The diagram shows the transition from initial description through the AI generation phase to user review and subsequent refinement iterations.
Sources: README.md:28-34, index.html:26-28
Implementation Commands and Environment
The loop is supported by specific CLI tools and environment configurations within a GitHub Codespace.
Essential Commands
| Command | Purpose |
|---|---|
claude | Initiates the AI interface in the terminal to receive descriptions. |
export ANTHROPIC_API_KEY=... | Configures the session key required for Claude to process requests. |
serve . | Launches the live preview server for the "Look" phase. |
Ctrl + C | Terminates active terminal processes. |
Sources: README.md:37-45
Terminal Interaction Sequence
This sequence demonstrates the interaction between the user, the CLI environment, the AI backend, and the resulting frontend preview.
Sources: README.md:16-34
Refinement Categories
Refinement prompts generally fall into four technical categories, as defined by the "Moves that work" framework:
- Add: Inserting new components or behaviors (e.g., adding a streak counter or delete button).
- Change: Modifying existing visual or structural elements (e.g., updating color themes or layout for mobile responsiveness).
- Fix: Resolving unintended behaviors or errors identified during the "Look" phase.
- Polish: Enhancing the professional or aesthetic quality of the interface.
Sources: PROMPTS.md:65-71
Conclusion
The Describe-Look-Refine loop reduces the barrier to software creation by replacing manual coding with high-level direction. It relies on the seamless integration of a CLI-based AI assistant and a live-reloading preview environment to transform plain-language intent into working web applications.
Sources: README.md:48-52, index.html:22-24