How I built Dance Coach by directing Claude Code
The detail behind section 03 of the Dance Coach case study: the guides I worked from, how I directed the agent, the data model, the problems I caught, and how the project's source-of-truth documents changed.
Guides that shaped my decisionsWhat each guide is and how I applied it
Open Vector
A curriculum for building with AI agents that sets itself against vibe coding. It has you plan the system first, check what the agent produces, and understand why it works.
Before any building, the foundation units covered the terminal, Git, deployment, systems thinking, data modeling, and information architecture. They end with a VECTOR.md file: a single document describing the product, which the agent treats as the source of truth.
AI Fluency
An Anthropic course, AI Fluency: Framework & Foundations. Its four skills shaped what I handed to the agent and how I checked its work:
- Delegation: deciding which work to give the agent and which to keep, such as judgment about dance technique
- Description: writing prompts with enough context and constraints to build the right thing
- Discernment: checking the agent's output instead of trusting it
- Diligence: owning what ships, including security and accuracy
People + AI Guidebook
Google PAIR's design guidance for AI products. I used two exercises from its User Needs + Defining Success chapter: Evidence of User Need, to check whether AI was the right tool for this need, and Specify and Align the AI Problem, to define what the AI must do and how it could learn the wrong goal. My answers are in Defining the AI problem.
How I directed the buildPrompts, the source of truth, doc checks, and an architecture review
A sequence of prompts, run in order. Each prompt was one feature with its dependencies stated: storage, then pose analysis, then the dashboard, then auth. Thirteen prompts produced the working core loop. Any decision that changed a prompt I hadn't run yet had to be flagged, along with what needed updating.
VECTOR.md as the source of truth. One document described the users, the loop, the data model, and the current state. The agent read it at the start of every session, and I updated it after each milestone.
A check that the docs match the code. VECTOR.md once said sign-in was installed and the user and team tables existed. Neither was true. A script now checks the doc's countable claims against the repo (migration count, installed dependencies, API routes).
An architecture review. I asked for a review of the whole system and tracked the results in ARCHITECTURE-DEBT.md, ranked by cost: four items closed, eleven open.
Data model: nouns and verbsWhat the system stores, who acts on it, and how the model changed
Noun | What it is | Verbs |
|---|---|---|
Team | Connects an instructor to their students | Instructor creates it; student joins it |
Choreo piece | A named assignment with a reference video | Instructor uploads and publishes it; student selects and watches it |
Practice take / Submission | A student's take, practice or final | Student records, uploads, practices again, submits |
Analysis | Pose comparison and per-count score | AI scores it; student reviews it during practice; instructor reviews it on a submission |
Instructor note | Feedback on a final take, hidden until released | Instructor writes and releases it; student reads it |
How the model changed. My first nouns-and-verbs exercise (Aug 6) had students review AI feedback, then choose to share it with the instructor and ask questions. I changed it to practice, then submit, so the instructor reviews every final take. "Share AI feedback" and "Ask questions" were dropped, and "Release feedback" was added.
Problems I caughtWhere the agent was wrong, and the production stack
Problem | How I caught it | What changed |
|---|---|---|
Wrong dance knowledge (hip action, weight transfer) | My training as a dancer | Hip action is modeled as a pelvic tilt driven by knee extension. Weight transfer requires foot placement plus torso and hip alignment. |
Android app crashed on upload | Testing on my phone | 720p recording and compression before upload (a 118.7 MB clip became 11.8 MB). No crash since. |
Debug logs never reached a real device | Expected logs were missing | Fixed the logging call release builds drop, and treated every earlier on-device conclusion as unverified. |
Unreleased feedback readable by anyone with the URL | Reviewing API responses | Roles verified on the server |
Storage rejected files over 100 MB | Real student videos | Moved storage from Cloudinary to Cloudflare R2 |
Stack: Expo (Android), React dashboard on Vercel, FastAPI and Postgres on Railway, Cloudflare R2, Clerk, MediaPipe.
How the two files changed34 versions of VECTOR.md and 17 of CLAUDE.md, Aug 2 to Sep 8
Both files are in the project's Git history, so every committed version is recorded. Most changes happened between Aug 7 and Aug 12, while the core loop was being built. VECTOR.md grew from 146 lines to 572, and CLAUDE.md from 50 to 161.
Date | What changed |
|---|---|
Aug 2–4 | CLAUDE.md written for a general coaching app: students upload practice videos and instructors add notes. No VECTOR.md yet. |
Aug 7 | VECTOR.md written, and CLAUDE.md rewritten to match. The product became the reference-video model: the instructor uploads a reference, students practice as often as they want, then submit a final take. Both files added the two feedback tiers. Technique is judged against the instructor's reference rather than fixed thresholds. |
Aug 8 | Current State filled in as the thirteen prompts finished. Either reference video (music or counts) became enough. |
Aug 10 | Storage moved from Cloudinary to Cloudflare R2 because of the 100 MB file limit. The filming rule was replaced by detecting each video's direction, because real footage didn't follow the rule. |
Aug 11–12 | Both files had said sign-in was installed and the user, team and enrollment tables existed. Neither was true. After sign-in was built, I corrected both files and added the script that checks them against the repo. |
Aug 18–20 | Decided every screen should work at both phone and laptop width, with two screen-width breakpoints. |
Sep 8 | Renamed from Paso to Dance Coach. |
What the history shows.
- Most of the growth is recorded decisions, not new features. Current State explains why each choice was made, so a later session doesn't undo it.
- The files were wrong about facts that can be counted. Correcting them by hand didn't stop new errors, so a script now fails when the files and the code disagree.
- The product model was settled on Aug 7. Later edits recorded how the build met real conditions: file sizes, how people actually film, and what release builds log.