Spec First, Then Forty Lines

How to read this guide

Skip to the setup →

01Start Here: Show Me the Spec

Start with one request: write your spec down. Not code, not a UI sketch. The same document the lesson notes produce for Aarav: North Star, observation, hypothesis, one named user, golden input and output pairs, and a way to verify the output. The thinking behind writing code has not changed in ten years. What has gone down is the amount of code written by hand. The work of finding the right inputs, the right output, the process between them, and the right interface still happens every time, and it happens before implementation.

Aarav, your first customer, was chosen because most people starting out are in his position: consuming content, needing to scope one thing down and take a first action.

One cadence rule for the rest of the roadmap: every lesson ends with a practice set that applies it to your own problem. Move on when your practice set shows you can implement what was taught, and not before.

02Worked Example 1, the Waveform: When the Right Interface Is Not Chat

The first spec comes from a power and performance (PnP) engineer. North Star: an AI-powered power and performance engineering workflow that cuts analyst turnaround by at least 10x (or to within 24 hours), actively used by at least three engineering teams. Observation: for every active FSDB release, a PnP engineer manually studies the waveform to find the optimal window and the matching IP utilisation for downstream flows; arrivals are unplanned, so the task slips to the next day and results are verified by hand. Hypothesis: automate the window and compute utilisation step.

Asked what interface he had in mind, he said chat. The useful push is on the user rather than the answer. The users are engineers who already run commands somewhere. Engineers spend their day in a terminal, so a command-line interface dropped into the shell they already use will beat a new chat window on adoption and friction. Claude Code is the reference case: Claude Cowork shipped with nearly the same functionality and was far less popular at launch, because the people using Claude at the time were engineers who prefer a CLI.

The verdict was not "use a CLI". It was: for a problem this niche, try at least two interfaces, start with the one that lives inside the environment the user already works in, and let the user decide. Derivation has to be validated with the end user; whoever reviews the spec is usually not a PnP engineer, and should say so.

03Worked Example 2, the Agency: Counting Inputs Before Choosing a Box

The second spec is for a creative agency. North Star: by February 2027, an AI-native creative agency that delivers a video content pipeline to startups and small brands on internal tooling, with clients able to self-serve variations or have the agency manage them. User: Benjamin, a UX designer turned entrepreneur. Input: a short brief (product, campaign, what the video must do), existing brand assets, one or two reference videos, approve or reject decisions per batch, and Rs 10,000 upfront. Output: at least two approved ad-ready videos from a batch of five, plus a brand profile and adapted template set that makes the next brief faster.

Rather than jump to an interface, run the same exercise as the lesson notes: list each input and its type.

Two scoping decisions came out of typing the inputs. First, heavy files cost money: text is close to free to store and process, video is not, so the spec caps video at 5 MB for now (an arbitrary number, chosen so the free tier survives). Second, the brand profile and template set are an output the system stores for next time rather than something the UI shows; on the second brief, Benjamin should only need to type text because his assets are already known. The spec had designed that in, which is the right instinct.

Then the interface debate. A form can collect all three inputs and could email back five videos with two recommendations, so a form is not wrong. A canvas (Figma or Magnific style) for side-by-side variations is another option. The spec's author chose chat over form for one reason: follow-ups. If a client uploads an irrelevant video, a chat can ask for a replacement inside the same conversation; a form cannot. He added that Google Flow's early version worked because it had simple buckets for each element and told you what was missing, which is still chat with structure. The argument holds. Follow-ups and revisions are the job in an agency, so the interface that makes follow-ups cheap wins.

04The Detour: Language Is the Interface

The chat-versus-form debate leads into a bigger thesis. Every piece of software in the last 50 to 60 years exists because humans could not explain things to machines. We built calculators, then CPUs, then programming languages, so that we could learn the machine's language and get work done. Around 2019 to 2020 transformers inverted this: machines began to understand ours. A recent inflection point is DHH's opening keynote at Rails World 2026. The person who built Ruby on Rails said that Ruby was 55% of his code last year and is 3% now; he writes in English and has, in his words, retired from writing code by hand.

The same shift shows up inside small teams. A design team that lived in Figma a year ago may barely open it now; the designer connects Figma to an LLM and brainstorms in language, because the end product is a deployed web or mobile app and the intermediate canvas existed only because engineering hours were expensive. One team's video pipeline went from six hours per video to under 30 minutes from idea to published reel.

Here is the nuance most people miss. "Use English" does not mean "outsource your thinking". Karpathy's line was the anchor: you can outsource your thinking, but you cannot outsource your understanding. The reason this roadmap still teaches Python (and yes, holding both beliefs at once is a little dissonant) is that the hardware in front of you does not compile English. Every prompt still becomes a deterministic language before it runs, and the translation gap is exactly where people who have never worked with a deterministic system get hurt: they expect the machine to behave like a person. Writing def respond today is how you learn to write the instruction well; tomorrow the syntax changes, the logic you had to think through does not.

05The Verifier Is Still Yours

What the Verifier's Rule says about all of this: even if AI builds every interface, judging which interface a user needs, what type each input is, and how the user should feel is a human decision. Claude can give opinions about an interface; it cannot tell you how to make your user feel something, because it has never felt anything.

Can a verifier be a person's opinion? Yes, and here is an example: a copy review built on David Ogilvy's principles, codified as 15 scoring parameters, handed to an LLM to score out of 100 with reasoning on how to improve. A verifier comes from domain expertise or lived experience and gets written down as criteria. With golden pairs from domain experts, can the verifier be a semantic similarity check (does the output carry the same aspects as the golden output)? Yes. Share the pairs with someone who knows the domain for feedback, anonymised if needed.

The gap that shows up in almost every spec, including the two above: what makes the two approved videos good? What makes the plan for Aarav a good plan? Define that and write it down as the verifier before building. It is more important to the application than the interface.

06From the Q&A: Solution-First, Gradio, Harnesses

07The Setup: Four Things

Everything after this point is for the first-time coder. The lesson notes spend most of their length on design and very little on setup, and for many people the first sitting ends at setup. The process between you and a working app has four parts: a language the machine understands (Python), a place to write and read it (an IDE), one folder with one file, and two commands.

1. Install Python from python.org/downloads. Windows: on the first installer screen tick "Add Python to PATH" before clicking Install.Mac: run the installer through. Test: open a terminal (Command Prompt or PowerShellTerminal) and type the version command. A version number is your tick.
   python --versionCopy
   python3 --versionCopy
   If it says not found, try python --version as well.
2. Install an IDE. It is a notepad for code. VS Code is free; Cursor needs a paid plan for its models. Unsure: take VS Code. Do not spend the day comparing them.
3. Make one folder and one file. Create a folder (for example 100x test on the desktop). In the IDE: File, Open Folder. Create a new file inside it called app.py. The .py tells the machine this is Python.
4. Run two commands in the IDE's terminal (View, Terminal). The second prints a local URL, http://127.0.0.1:7860. Open it in your browser.
   pip install gradioCopy
   python app.pyCopy
   pip3 install gradioCopy
   python3 app.pyCopy

Start with Hello World (the same one in the Gradio quickstart) before the chat template, so that the first thing you debug is your setup and not your logic:

Read it as the whiteboard from the lesson notes. The thing in the brackets (name) is the input. What follows return is the output. The function is the process. gr.Interface is the interface between a human and this machine.

08The Template: Forty Lines, Four That Matter

This is the template. Save it as app.py, replacing Hello World, and run it again.

Everything in it is either the interface or text you already wrote on your whiteboard. GOLDEN_INPUT and GOLDEN_OUTPUT are Aarav's golden pair pasted in as Python strings. gr.ChatInterface is the chat window; examples puts the golden input one click away so nobody has to type it. The only processing is the four lines inside respond: take the message, and if it contains the word jira return the golden output, otherwise ask a follow-up question. In Python this is how you move conditionally: if the condition is true the first return runs and nothing after it does; if it is false the first return is skipped.

There is no intelligence yet. That is deliberate. The app mocks the intelligence with the golden pair so that you can test the whole loop (input in, output out, in the interface your user will actually see) before any model is involved. In the next lesson the body of respond becomes a call to an LLM API and the answer stops depending on the word jira. The interface will not change, because the interface only cares about the input and the output and how they are presented.

Make it yours, here

Paste your golden pair and trigger word. The three lines change; the interface stays. Nothing leaves your browser.

09The Errors You Should Expect

The machine does not guess. When it stops, it is because something was not told to it. Keep a log: the exact error text, what you tried, and what fixed it. The log is worth more than the screenshot of success: it is what anyone helping you will ask for first.

Stuck for more than 20 minutes: check Troubleshooting, then ask for help (a peer, a forum, an AI assistant) with three things: the exact error message, what you already tried, and a screenshot. First-time coders should pair up; one person's fix is usually another person's blocker.

10Putting It on a Link: Hugging Face Spaces

Build and test locally first. Everything you do online is the same file; the only difference is a link other people can open. When you are ready, Hugging Face Spaces is the lowest-cost, fastest route for a Gradio app, and it is the one this guide uses. Hugging Face owns Gradio, which is why the fit is exact.

One recent policy change matters: after the NVIDIA acquisition, free hardware on Spaces is ZeroGPU only, you get two free Spaces, and a new account must be 30 days old before it can use them. The instruction: create your Hugging Face account today, even if you deploy nothing. By the time you have run the task manually and have something worth sharing, the account will be eligible. No one is asked to pay for a Space.

1. Log in at huggingface.co. Click the plus button, New Space (or go straight to huggingface.co/new-space).
2. Name it (for example fde-ui). Choose the Gradio SDK. Start blank, not from a template (the templates are not trusted; you already have tested code).
3. Hardware: the free ZeroGPU option. Visibility: public if you are happy to share the link, private otherwise.
4. Click Create. On the next screen choose Create the app.py file, paste your tested app.py, and click Commit new file.
5. Wait for the build. The Space starts your app. From the three-dot menu choose Embed this Space to get the shareable link.
6. To change anything: edit app.py in the Space and commit again.

11Before the Next Lesson

• Spec on one pageNorth Star, observation, hypothesis, one named user, at least one golden input and output pair, and the verifier (what makes the output good, written as criteria). Track B is fine.
• A screenshot of the template running on localhostWith your own golden pair in it, plus your error log, kept next to your spec.
• A Hugging Face account created todaySo the 30-day clock is running. Optional: a Spaces link if you already qualify.
• Run the task manually for your 2 to 5 usersThe golden dataset and the verifier come out of doing the job by hand, not out of the code.
• If def and return looked strange, finish the Python prerequisiteBig Binary Python prerequisite, before the next lesson. The lessons do not teach Python syntax.

Next: in Block 1 · Week 2 · The second interface: APIs, the body of respond becomes an LLM API call, which makes the app answer anything your user types and not just the word jira. Then Block 1 · Week 2 · Building APIs and the backend, then Block 1 · Week 3 · Databases and domain modelling, so conversations are stored.

Vocabulary from this guide

Rabbit holes

Write the spec. Paste the template. Get the tick. Intelligence is next.Companions: the checklist · the beginner kit