How it works

Spec-Driven Development is a small learning platform: hands-on courses for engineers building with ai. It hosts several courses, and every course follows the same shape so you never have to learn a new interface. Each course is a folder of markdown lessons, JSON quizzes, instructor notes, and a glossary, with a course.json that lists its modules and lesson order. The catalog lists what is available now and what is coming.

The idea that runs through every course is spec-driven development: write down what "correct" means before you build, build so the result can be measured, and then improve with evidence instead of vibes. Courses organize their lessons into phases (for example Analyze, Measure, Improve), and each lesson page tells you which phase you are in.

Every course also has a running example, a small fictional world that every lesson reuses so you learn the ideas rather than a new setting each time. The course page introduces it, and Eve uses it in her explanations.

Each lesson page has the same shape, top to bottom:

1. Header: module, lesson number, minutes, and the verb.
2. What you'll learn: three to five "you can…" objectives.
3. Why this matters: a short story from the plant shop showing the pain the lesson removes.
4. Numbered sections: concept, then a tiny example, then a slightly harder one. If a section has no example, it is not finished.
5. Key terms: chips that link to the glossary.
6. Check your understanding: multiple choice, graded instantly with an explanation for every option.
7. Apply it: a short answer and a free response, graded by Eve against a rubric.
8. Homework (after L5 and L9): a bigger project, also rubric-graded.
9. Instructor notes: a collapsed panel for whoever is teaching: talking points, a live demo, misconceptions, timing.
10. Mark complete and previous / next links.

Callouts flag different kinds of content. Here is each one, live:

Eve is an agent built with eve, Vercel's framework for durable agents, running on Claude models reached through Vercel AI Gateway. She lives in the drawer on the right (the Ask Eve button in the top bar opens it on any page). She has a written set of instructions (who she is, how she teaches, what she never does) and five tools of her own: read a lesson, read a course overview, list the courses, look up a glossary term, and read a quiz (without its answers). Every question you send carries the page you are on (the course, the lesson, the course's teaching notes), so on a lesson page she reads the full text of that lesson with her tool before explaining it. That is why she can answer "what does section 3 mean?" without you pasting anything. On the catalog or progress pages she knows which courses exist and can recommend where to start.

Highlight to ask

Select any text in a lesson (or in a quiz question) and a small Ask Eve pill appears above it. Click it and the passage is attached to your next question, with four quick actions: Explain this simply, Give me another example, Why does this matter?, and Quiz me on this. You can also type your own question. Try it on this paragraph.

Rules she follows

• Answer first, then one tiny example, then the general rule. Short by default.
• On quiz and homework questions she guides (hints, pointers to the lesson, checking your reasoning) rather than writing the answer for you.
• She defines terms the first time she uses them and never assumes a machine-learning background.
• She can be wrong. Check important claims against the lesson text.

Memory

Each lesson (and each course page) has its own conversation. It is a durable eve session: the transcript lives with the session on the server, and once Eve has read a lesson it stays in that session's memory, so later questions do not pay to read it again. Your browser tab only remembers the session id, which is why the conversation picks up where you left it after navigating away or reloading, and why it is gone when the tab closes. Chats are never written to the platform database, and each session has a spending cap, so a runaway conversation cannot cost more than about a dollar. The new conversation button in the drawer starts a fresh session.

Every course uses the same two kinds of questions, graded two different ways on purpose. (The AI agents course teaches exactly this distinction in its Lesson 5, so the platform practices what that course preaches.)

The judge is set up the way a good evaluation should be:

• Binary criteria. Each question has a rubric of three to six criteria. The judge marks each one met or not met, with a one-sentence note. No 1–5 scores.
• The score is computed in code. Score = criteria met ÷ total criteria. You pass at 70% or more. The model never picks the number.
• A model answer as the boundary example. The judge sees a strong reference answer so it knows what "good" looks like, but it is told to accept different wording and different valid approaches.
• Rubrics live on the server. Your browser only sends your answer and the question id, so nothing you type can change the rubric.
• Feedback you can act on. Two to five sentences, strengths, concrete improvements, then the model answer if you want it. You can grade again as many times as you like, and ask Eve to explain the feedback without giving the answer away.

Your best score per question is what shows up in the sidebar and on the progress page.

• No login. The first time you open the site, the server sets an anonymous cookie with a random id. That id is the only thing tying your progress together.
• Two copies of progress. Your browser keeps a copy in local storage so the site feels instant. If the platform is deployed with a Neon Postgres database, the server keeps the durable copy too, and the two are merged when you load a page (newest wins).
• What is stored: which lessons you started or completed in each course, and each quiz attempt (course, question id, your answer, score, pass/fail, and the feedback). What is not stored: your chats with Eve, your name, your email.
• Reset from the progress page erases both copies.

The whole platform is one Next.js app. Pages are rendered on the server from each course's markdown files; the interactive parts (Eve, quizzes, progress) run in the browser and talk to a few small API routes, and to Eve's own agent service.

A question to Eve, step by step

1. You highlight a sentence in a lesson and click Ask Eve, then pick Explain this simply.
2. The browser sends your question to Eve's agent at /eve/v1/… with the passage quoted inside it and the page context (course, lesson, tutor notes) attached to that one turn. The first message creates a durable session for this lesson; later ones continue it.
3. eve runs the turn as a workflow. Eve's instructions tell her to read a lesson before explaining it, so she calls her get_lesson tool (you see a small "Reading the lesson" chip), gets the lesson text back, and writes her answer.
4. The model call goes to Vercel AI Gateway, which forwards it to Claude with streaming on, and each chunk of text is streamed to your browser as an event. That is why the answer appears word by word. The session then waits for your next message, with the lesson already in its memory.
5. Only the session id is kept in your browser tab, so coming back to the lesson resumes the same conversation. Nothing from the exchange is written to the platform database.

Grading a written answer, step by step

1. The browser sends the course id, lesson id, question id, and your answer to /api/grade.
2. The server looks up the rubric and model answer for that question (they never leave the server).
3. It asks the model for a strictly structured JSON result: one met / not-met verdict per rubric criterion, a feedback paragraph, strengths, and improvements. The request uses structured outputs, so the shape is guaranteed.
4. The server computes the score from the verdicts, decides pass / fail at 70%, and returns everything along with the model answer.
5. Your browser shows the feedback card and records the attempt (locally, and in the database if one is configured).

The pieces

Cost

A tutor turn or a grading call with the default model costs on the order of a cent or two, thanks to prompt caching and short answers. Finishing a whole course with heavy tutor use is a few dollars. Usage and spend are visible in the Vercel dashboard under AI Gateway, where the owner can set limits.

• Edit a lesson: open content/courses/<course>/lessons/<slug>.md, change the text, save. Callouts use the :::example Title … ::: syntax shown above.
• Add a quiz question: edit content/courses/<course>/quizzes/<slug>.json. Multiple choice needs an answer and an explanation per option; written questions need a rubric and a modelAnswer.
• Add a course: copy content/courses/_template to a new folder, fill in course.json, and write the lessons. It appears in the catalog on the next build. docs/ADDING_A_COURSE.md walks through it.
• Change Eve: her persona and rules in agent/instructions.md, her tools in agent/tools/, her model and limits in agent/agent.ts. Run npm run eve:eval afterwards.
• Run locally: Node 24, npm install, put an AI_GATEWAY_API_KEY from the Vercel dashboard in .env.local, npm run dev (this starts the site and the eve dev server together).
• Deploy: import the repository into Vercel and deploy; the eve agent deploys as a service of the same project. With OIDC federation enabled on the project, Eve authenticates with the gateway automatically; otherwise add AI_GATEWAY_API_KEY. Add a Neon database whenever you want progress to survive across devices.

The design documents are in the repository: docs/ARCHITECTURE.md, docs/UI_PLAN.md, docs/AUTHOR_BRIEF.md (how to write a lesson), docs/ADDING_A_COURSE.md, and a plan per course under docs/courses/.

Each course page lists its own credits and sources. Eve and the grader run on Claude models from Anthropic, reached through Vercel AI Gateway; Eve herself is built with eve, Vercel's agent framework. The platform itself is built on open source: Next.js, Tailwind CSS, the Vercel AI SDK, Drizzle, and Neon.