michael-borck/programming-labs：十二个面向 AI 智能体编程的实践实验室

Twelve hands-on labs that teach programming at its newest abstraction level: you describe, an agent builds, and the durable human skills — specification, verification, decomposition, taste — are the curriculum. Zero prior programming assumed. Zero apologies for that.

▶ programminglabs.borck.education — the series front door.

Start here: read SPEAK-SOFTWARE.md (10 minutes — the thesis, the evidence model, and the kata that structure every lab), then open Lab 1.

Who this is for: anyone — built for business-minded learners who have never programmed and may never write code by hand. If you can write a clear email, you have the prerequisite.

Gear, environments, models, costs, and outside resources: RESOURCES.md — the golden path and the honest alternatives, in one place.

What you need: a GitHub account, a CLI agent (pi is the series' named path; any equivalent works), and model credits (see What it costs in the framing essay).

What you'll have at the end: twelve public repos, each holding a working product, the spec that produced it, a decision log, and a critique — a portfolio that is the evidence of the skills.

The frame

You've been handed an engineering department of one — a brilliant, tireless, overconfident intern. These labs teach you to run it. Every lab is a client brief, not an exercise. Every lab kills one specific misconception and installs one durable habit.

The labs

#	Lab	Kills the belief that…	Builds the habit of…	Status
1	Hello, Department of One	"programming isn't for me"	everything lives in a repo	✅
2	The Demo Illusion	"it works = it's done"	defining done before admiring it	✅
3	Say What You Mean	"the AI knows what I meant"	writing the spec first	✅
4	The Checklist It Can't Charm	"checking is re-reading"	acceptance checks that run	✅
5	The Flight Recorder	"one wrong move ruins it"	small commits, fearless branches	✅
6	Teach the Intern	"every chat starts from zero"	the context folder	✅
7	Trust, Then Verify	"it sounds right so it is right"	demanding evidence of done	✅
8	The Taste Test	"best is objective"	critique as a deliverable	✅
9	The Last 20%	"the hard part is the first 80%"	directing polish	✅
10	Run the Department	"big things are built in one go"	decomposition into issues	✅
11	The Audit	"the code is the only record"	reading someone else's trail	✅
12	Ship Something True	"I need permission to ship"	the full loop, owned	✅

The staff tools

Three follow-on labs turn the book's harness chapters into tools your department keeps. Each pairs with a chapter of Speak Software (the companion book) and ships a reference implementation in its speak-software/tools folder.

#	Lab	Kills the belief that…	Builds the habit of…	Status
13	Close the Gate	"I'll review it before it ships"	every repo carrying a gate that runs	✅
14	The Paper Trail	"my documents are fine — I wrote them"	the evidence trio as a checked artefact	✅
15	The Doctor Is In	"if it worked today it'll work tomorrow"	verifying the environment before the work	✅

Labs 13–14 extend the arc; Lab 15 is standalone and works on any folder.

✅ ready · 🔨 building · 💡 designed (see DESIGN.md for all twelve one-pagers, and ROADMAP.md for the build order — an unchecked box there is a promise)

The arc, in four acts: 1–3 wonder & disillusionment · 4–7 steering · 8–10 judgement · 11–12 ownership.

Each lab takes ~90 minutes, self-paced, restartable. Labs assume you've done the ones before them — except Lab 3, which was built first and doubles as the series' taster: it only needs an agent and an empty folder.

How the labs work

One repo per lab. Copy template/ into a fresh repo — it holds the four files the whole series revolves around: AGENTS.md, SPEC.md, DECISIONS.md, CRITIQUE.md.
The evidence is spec → delta → critique, never a chat transcript. What "done" means (before you build), what you overrode (and why), what you'd still change (and why).
The Replication Test is the self-check: your SPEC.md, alone, handed to a fresh agent — does it reproduce a product you'd accept? If yes, you authored a program in English.
The kata: build it (round 1) → spec it (round 2) → critique it (round 3). Done when round 2 converges and round 3 has opinions.

Getting the labs, practically

The labs are documents, not software. Each is a brief you read (here on GitHub) and carry out in your own repo with your own agent — there is no lab runner, environment, or Docker to install. One-time setup lives inside Lab 1: a GitHub account, a CLI agent, model access. Four labs ship a small provided folder (handoff-tiptop, brewcrew-a/b, bookable, stallboard) — each a single dependency-free HTML file plus its paper trail; grab them by cloning this repo or Code → Download ZIP.

Do the labs in order — the arc is designed — or jump in. Labs 3, 7, 8, 9, 11, 14 and 15 are standalone (3 needs only an agent and an empty folder; 7, 8, 9, 11 bring their own product; 14 works on any trio folder; 15 works on any folder). Labs 2, 4–6, 10, and 12 build on products you made earlier, and say so at the top; Lab 13 needs a small Python project with tests.

The toys

Six labs (1, 2, 3, 6, 7 and 9) open with a single-file interactive toy that breaks the lab's misconception in about 90 seconds — no install, no account, no network; the other six labs let their provided repos or your own products do that job. All six toys live in the sibling repo programming-toys, and the full labs ↔ toys index is in RESOURCES.md.

Course mapping

This repo is course-agnostic and numbering-agnostic — labs are named for what they teach. Adopting the series in a unit? Add a row.

Lab	Unit / module
(none yet)

For instructors: the facilitation guide (session shape, restraint rules, per-lab watch-fors, and the assessment design — viva, spec sprint, live steer) lives with the marker-calibration exemplars in the private staff repo, programming-labs-staff — teaching or evaluating the series, open an issue or email the author for access. The marking model itself is public: the evidence trio. Grade the spec by re-running it (the Replication Test is the marking instrument), the delta by reading DECISIONS.md against the commits, the critique on whether its opinions are arguable. AI use is assumed and unbounded; the graded artifacts are precisely the ones that can't be autonomous. Lab 11 is the rubric made student-facing.

Going deeper — the reference shelf

The labs deliberately live above any programming language. When you want the layer underneath, the author's book series at books.borck.education is the optional depth reference: Conversation, Not Delegation for the thinking-with-AI framework behind this series; Think Python, Direct AI for the computational-thinking spine with a real language under your fingers; Ship Python, Orchestrate AI when Labs 4, 5 and 10 make you curious what checks, version control and delivery look like at professional depth.

And when the labs make you wonder what the agent is actually doing in there — what a system prompt, a tool call, or retrieval really is — the sibling HandsOnAI toolkit teaches those mechanisms as small, readable Python that you run and open yourself. That's the layer these labs steer.

This repo eats its own dogfood

Every lab here is itself built spec-first: the series has its own DECISIONS.md, and each lab folder carries the spec it was built from. The toys are vibe-coded from their own SPEC.md files and say so. You are welcome — encouraged — to audit the authors with the same critique form we hand you.

Part of programming.borck.education, alongside the sibling toy collection Programming Toys and the HandsOnAI toolkit — the see-under-the-hood companion for when steering is no longer enough. The companion books on intentional AI collaboration live at books.borck.education.

Licence

MIT. Unit-agnostic teaching material — no institution or course branding.