Workshop 1 — AI for experimentalists

Aim. By the end of today you know how to use AI to help you build the things our lab builds with it: websites, videos and tutorials, PCB design, data acquisition and fitting, laser locking, hardware control, software. You do it with an AI coding agent — Claude Code in VS Code, working on your files: it reads them, writes code, runs commands and reports back — and you learn the method that makes its output trustworthy.

Outline. Setup and preparation check → introduction to AI and the tools we use → our "AI method" in 5 steps → Project 1: build a web app (a simulator or a game) → Project 2: control a microcontroller over the net with your phone.

Think about what you want to make! Suggestions for Project 1: loading a freight train game · an inverted pendulum simulator · phase-locking coupled pendula · unfair golf · billiards · a calculator or simulator for something from your research.

Prerequisite: the preparation is done — VS Code with the Claude Code extension signed in, a course folder, the class repository downloaded, a free Cloudflare account connected to GitHub. Bring your laptop and a USB-C cable (the instructor has spares); the ESP32 board is provided.

1 · Setup and preparation check

Everyone has their laptop prepared, Claude access working, and the tutor repository downloaded: the class repository class-board-2026 (a repository is a project folder whose complete history is kept by git, the version-history tool; on GitHub it also lives online) is on your laptop and opens in VS Code. Open Claude Code in it and type /tutor L1: the tutor greets you in English or Mandarin and checks your setup with you. If anything is missing, fix it now with the tutor — the rest of the day builds on it. The check covers both deployment accounts: signed in to GitHub, and a Cloudflare account connected to GitHub — you may need both today.

The tutor does the mechanical work and you approve it — creating the project folder and repository, enabling GitHub Pages, the project-wall entry, the secrets check. You do the part that is the learning: write the vision, review the plan, name the test, report what you see, and press Commit / Sync Changes in Source Control. The instructor is not the help desk during class; the tutor is — only when the tutor cannot fix it do you go to the instructor.

2 · Introduction to AI and the tools we use

A short primer, in the slides (PDF). The topics, each with its rule of thumb:

• How large language models work. Text becomes tokens, tokens become numbers; one operation repeated — predict the next token. Sampling is deliberately random: fluency is not the same thing as correctness. Training fits the weights once; inference just runs them — the model does not learn from your conversation (unless your data is used for training, so keep secrets and unpublished results out of it).
• Attention and context. To predict the next word the model looks back over every earlier word. Every message resends the whole conversation, so a long chat gets slower and more expensive per message; the unchanged beginning is cached — stable instructions and documents first, volatile text last. Keep context small: one topic per session.
• Context rot. A dropped-in PDF or image is a very expensive prefix, resent on every turn and mostly noise. Use Markdown (plain text with light formatting): let a separate session read each file and write a detailed text summary; work from that.
• Models. Haiku, Sonnet, Opus and Fable are the same idea at different scale, at roughly 1 : 3 : 5 : 10 the cost per token. The strong model plans and checks; cheap models do the work — in subagents with their own fresh context, in parallel. Chinese open-source models are cheaper but weaker and a security risk; they are not allowed.
• Reviewing. Never let the author grade its own work. An independent reviewer with a different view — a fresh Claude session that has not seen the work; tests written from the plan before the work starts; loop, do not hope.
• Long projects. Documentation, handovers and fresh sessions: a new session reads CLAUDE.md, the plan and the last handover; at about half the context window it writes the handover and commits; then a fresh session. The disk is the memory.
• CLAUDE.md, memory, skills, MCP, hooks, extensions — the six places you put what the agent should know, and what each costs in the window. Prefer hooks for anything that must always happen.
• Workflow must-dos. Put all needed data in the prompt · one topic per session · summarise files first · cheap workers, strong planner · verify independently.
• Failure modes. Hallucinations follow from the process: plausible, not verified; a confident tone is not confidence; rare facts, exact numbers and citations are where guessing shows. Beyond hallucination: it invents specifics, agrees with you, makes small errors in correct-looking structure, drops requirements, and errors multiply (95 % per step is 36 % over 20 steps). Rule: use AI where checking is easier than doing. Agent failures — gaming the test, claiming without running, scope creep, loops, destructive actions — are caught by mechanism (hooks, git, tests), not by reading harder. In some sense hallucination is creativity: testing and validation put it in the right places.
• Tools. Four ways to run an agent — Claude Cowork, Claude Design, other vendors' agent apps, VS Code + agents; our choice: VS Code + the Claude Code extension (low lock-in; your code, configuration and history stay yours). Made a mistake? Stop the execution, then rewind — do not poison your context. Context full? Start a new session: "Please finish what you are working on and document anything from this session that may be useful to future Claude sessions in .md files in this directory and a handover.md file to allow Claude to continue our work in a new session." Compaction is lossy — documentation is better. Check your usage often.
• Git. Version control is the safety net, the record and the way you collaborate — with people and with an agent. Four words: repository, commit (a named snapshot with a message), diff, history. The loop edit → stage → commit, entirely from VS Code's Source Control panel — no terminal required. Branches: main always runs. GitHub keeps a shared copy: push, pull, clone, pull request (a request to merge your changes, reviewed first). .gitignore keeps raw data, generated output and secrets out. With an agent: commit before, ask it to commit as it goes, review the diff not the file, give it a branch, never let it rewrite history.
• Deployment, for free. GitHub for code, GitHub Pages for static pages, Cloudflare Pages + Workers for apps with a backend, YouTube (unlisted) for video, Hugging Face Spaces and Zenodo for demos and data. Say "Deploy this" — Claude does the wiring. The loop: commit → push → the host builds → live. Secrets never go in the repository; they live in the host's environment settings.
• Apps that talk to you. Telegram (a token from @BotFather — the easiest start), the LINE Messaging API (what everyone in Taiwan has), ntfy.sh for notifications only; a webhook on a Cloudflare Worker. Start with Telegram, then port to LINE. Tokens are passwords. Gmail, Sheets and Drive from code; an LLM inside your app through an API key (keys are money); voice in, voice out. Two ways AI makes software smarter: A — AI-written code (the default) · B — an LLM in the loop (reach for it at the hard step).
• Video. Script first, pictures last: document → script → narration → visuals timed to the audio. The lab's pipeline is public (show-your-work). Pictures of hardware: Blender (scriptable, from CAD) and Unreal (scenery). Label generated imagery.

3 · Our "AI method" in 5 steps

The most important slide in the talk.

1. Vision. Describe what you want, with as much detail as possible.
2. Specification / Plan. Get AI to produce a detailed specification — plan the project! Break the project into many small tasks with testable deliverables. Ask AI to ask you questions!
3. Review. Review the plan, and have AI review the plan to identify improvements and flaws — in a fresh Claude session that has not seen the work, so the author does not grade its own plan.
4. Code (using agent swarms). Tell AI to run swarms of agents in parallel to complete the build.
5. Test / Debug / Verify. Ensure your plan and specification include methods to test the code. Fix problems one at a time.

Iterate: the first plan is never the last plan. Never trust AI without testing and verifying.

4 · Project 1 — Build a web app (a simulator or a game)

What do you want to make? Suggestions: loading a freight train game · an inverted pendulum simulator · phase-locking coupled pendula · unfair golf · billiards · a calculator or simulator for something from your research.

1. Decide what to make. Give it its own folder and its own public GitHub repository under your personal account (a repository is a project folder whose complete history is kept by git; on GitHub it also lives online). The tutor checks it and prompts you to push at every milestone.
2. Follow the "AI method" to produce a working local demo.
3. Deploy it on the web (publish it so it is live at a public address). Which host depends on what you built, and you may need both: a static page → GitHub Pages, straight from the repository; anything with a backend, a bot webhook or a secret → Cloudflare Pages + Workers.
4. Create a report that explains the concept or game in detail.
5. Make the project website — the GitHub Pages site of the repository, at https://<user>.github.io/<repo>/: a title, what it is and why it is interesting, how it works, a picture, GIF or short video of it working, what was verified, and links to the live app (…/app/) and to the repository.
6. Improve the presentation: Markdown → slides → website → YouTube video (optional extension).
7. Add it to the project wall — the tutor prepares your entry (one JSON file and one picture) and you push it.

Each project = its own folder and its own public repository, with a public project website — not just a README. GitHub Pages hosts the project website and any static app; anything with a backend, a bot webhook or a secret goes on Cloudflare Pages + Workers — you may need both, so have both accounts ready. Either redeploys on every push. The instructor's pendulum-example and csv-scope-example are examples of Project-1-style builds.

5 · Project 2 — Control a microcontroller over the net with your phone

Aim: create a phone app that lets you control and measure from hardware — the ESP32 (a small WiFi microcontroller board; ours is the Jinhua ESP32-S3, NT$400, provided) — over WiFi. Follow the "AI method".

1. Step 1 — the hardware-validation baseline. Flash the class repository's reference firmware (the program that runs on the microcontroller) and phone app onto your own ESP32-S3 (flash = write it onto the board over USB; the first flash of a new board needs BOOT + RST once). The board becomes its own WiFi access point instrument-XXXX. Join it from your phone or laptop (password instrument), type http://192.168.4.1 into the browser, control the LED and read the live values. Three tips: stay connected when the phone warns there is no internet · on Android, switch mobile data off · type the http:// yourself. Starting from a known working hardware baseline is an essential part of any experimental physics workflow — it separates hardware problems from software problems.
2. Step 2 — your own app, by the "AI method". Its own folder and its own public GitHub repository, like Project 1. For example: a phone app that controls the brightness and colour of the ESP32's LED; then measure something and show it live on the phone. The class firmware stays the fallback if your own build stalls — and it is the base for Project 3.
3. Make the project website (GitHub Pages of the repository): title, what it is and why it is interesting, how it works, a picture, GIF or short video of it working, what was verified, a link to the repository — and, since an app that runs on the board has no public address, a short video of it working instead of a live link.
4. Add it to the project wall — the tutor prepares the entry, you push it.

Camera. For anyone who wants to try a camera app, one unit of the ESP32-S3-N16R8-CAM 開發板 + OV3660 鏡頭 (Jinhua #41395) is available.

6 · Between workshops

Before the next workshop: complete the preparation, improve your apps, build and have fun. The apps are your Project 1 and Project 2 — push at every milestone, keep the project websites and the project wall current.

Preparation for Workshop 2:

• Install KiCad 10 (the free program we draw the schematic and lay out the printed circuit board in) and open it once, so it finishes configuring its libraries — see Preparation.
• Create a JLCPCB account (the board factory; parts come from its own parts library).

Your part of the class board is assigned at the start of Workshop 2. If you are stuck, ask the tutor first, then e-mail the instructor.

7 · Beyond the baseline

The hardware is the shared baseline — fixed by budget and timeline. Everything else is open: the software, the firmware, the app, and everything around the instrument. Whenever you are ahead, ask: what problem in my lab could this solve? Talk to your instrument from LINE or Telegram — the extension we most encourage: push notifications when a value drifts or an alarm fires, and bot commands that read a value or switch a module output from your phone, from anywhere. Just build something great.

8 · Materials

• Slides: Workshop 1 — AI for experimentalists (PDF). Video recordings are not online.
• Workbook on GitHub: ch. 0 — preparation · ch. 1 — Workshop 1.
• Reference repositories, as examples of Project-1-style builds: pendulum-example (live) · csv-scope-example (live).
• The project wall — everyone's projects, live (repository; the README has the entry format).
• The tutor: /tutor L1 in the class repository.
• See also the AI resources.