A beginner-friendly workshop for going from messy idea to working app using Claude Code and AI agents.
Goal: Take a brain dump of an idea and turn it into something running in your browser (localhost) in 1-2 hours.
Audience: Anyone! Works for complete beginners, designers, PMs, musicians, artists - not just engineers. If you've used ChatGPT before, you can do this.
For technical folks: Hi, I'm also technical. This guide includes explanations for beginners. Don't write it off - the workflow and agent patterns are useful regardless of your experience level. Trust me. Just skip the basics you already know.
Before we dive in, here's what some terms mean:
Terminal - A text-based way to talk to your computer. Instead of clicking icons, you type commands. It looks like a black or white window with text. Also called "command line" or "shell."
- Mac: Search for "Terminal" in Spotlight (Cmd + Space), or find it in Applications → Utilities → Terminal
- Windows: Search for "Command Prompt" or "PowerShell" in the Start menu. Or better: install Windows Terminal from the Microsoft Store
GitHub - A website where people store and share code. Think of it like Google Drive but for code projects. You don't need to know how to code to use it - we're just downloading files from it.
Localhost - Your own computer acting as a mini website server. When you see localhost:3000 in your browser, that's a website running on YOUR machine, not the internet. Only you can see it.
Comment - In code examples below, you'll see lines starting with #. These are comments - notes for humans that the computer ignores. They explain what the next line does.
Agent - A set of instructions that tells Claude how to behave for a specific task. Think of it like giving someone a job description before they start working. "You're a planner, here's what you do..."
One thing that surprises people: Claude Code asks your permission before doing things on your computer. This is a safety feature, not a bug!
You'll see prompts like:
Claude wants to run: npm install
Allow? (y/n)
What to do:
- Read what it's asking to do
- If you're unsure, just ask: "Explain what this command does before I approve it"
- Claude will break it down in plain English
- Then decide whether to approve
Don't be scared by technical-looking commands. You can always ask Claude to explain. That's literally what it's there for.
Sign up at claude.ai and upgrade to Pro.
Can't afford it? Ask around - if you know someone with Claude Pro, they may be able to share a guest pass with you. Claude offers these to Pro subscribers to share with friends.
On Mac:
- Press
Cmd + Spaceto open Spotlight - Type "Terminal" and press Enter
- A window with a text prompt should appear
On Windows:
- Press the Windows key
- Type "Command Prompt" or "PowerShell"
- Click to open it
- (Or install Windows Terminal for a nicer experience)
You should see a blinking cursor waiting for you to type. That's it - you're in!
Follow the official quickstart guide.
After installing, test that it works:
# This command asks Claude Code to print its version number
# If it prints something like "1.0.0", you're good!
claude --version# This checks if Git is installed
# If it prints a version number, you have it
git --versionIf you don't have Git, that's okay for this workshop. You can install it later if you want.
Or pick from our suggestions below. Something small you wish existed!
- Pick one AI tool for everyone - This workshop uses Claude Code. Don't mix tools (Claude vs Gemini vs ChatGPT) or you'll spend the whole time debugging different interfaces.
- Clone/download this repo so you can share the prompts
- Test the full flow yourself at least once
- Have the Claude Code usage page bookmarked to help people check their limits
Start with introductions. Go around and have everyone share:
- Their name
- Their experience with AI tools:
- "I use ChatGPT daily for work"
- "I've tried the AI thing in Google search results"
- "I built a whole app with Cursor last week"
- "I have no idea what any of this is"
- What project idea they want to work on today (or "I don't know yet")
Start with yourself and a simple project idea you'll use as the demo example (e.g. a todo list app). This does two things: helps you gauge the room, and gets people excited hearing each other's ideas.
- Pair people up - Put terminal newbies with someone more comfortable. Driver/navigator style works great.
- Regroup every 10-15 min - Quick "where is everyone?" check-ins prevent people from silently struggling
- Celebrate loudly - When someone gets their first "it's running in my browser!" moment, make noise about it
- Walk through the prompts - Don't just tell people to "use the planner agent." Open the prompt file, read through it together, explain what each section does. This demystifies what's happening.
- Be prepared for questions - See "Bonus Topics for Q&A or Extended Sessions" at the bottom of this page. You don't have to have answers to everything, I find sharing a description of what current industry discussions look like on a topic + where to go for more information can be helpful.
- Demo time is magic - Have everyone share their screen for 1-2 min and show what they built. Even "it shows a button that doesn't work yet" is a win. The excitement is contagious.
- Clear ending ritual - Say explicitly: "That's the official end! If you want to hang and ask questions, I'll be here for another 15-20 min. But no pressure to stay."
- Share next steps - Point them to the "What's Next" section of this README
- Fewer agents = faster dopamine hit. Start with Planner → Builder only.
- TDD burns tokens fast - save for later sessions
- People need to SEE the prompts, not just use them abstractly
- The "it's running!" moment is everything. Optimize for getting there fast.
- End clearly so people don't feel awkward about leaving
Open your terminal (see glossary above if you forgot how).
# Create a new folder for your project
# "mkdir" means "make directory" (directory = folder)
mkdir my-project
# Move into that folder
# "cd" means "change directory"
cd my-project
# Start Claude Code
claudeYou should see Claude Code start up and greet you.
Check your usage limits: Open console.anthropic.com/settings/usage in your browser. This shows how much you've used and what's left. Keep this tab open during the workshop.
Before setting anything up, let's understand what each agent actually is. Open the /prompts folder and read through each one together:
Planner Agent (prompts/planner.md)
- Takes your messy idea and asks clarifying questions
- Proposes a tiny MVP (minimum viable product)
- Creates a
plan.mdfile with scope, acceptance criteria, and tasks - Key line: "The goal is to get something running fast, not to build something perfect"
Builder Agent (prompts/builder.md)
- Reads the plan and implements Phase 1 only
- Gets it running as a web app you can open in your browser
- Explains every command before asking permission
- Key line: "Ship it!"
Verifier Agent (prompts/verifier.md) - Optional
- Adds simple tests or a manual checklist
- Keeps it light - just enough confidence that it works
The whole point of reading through these is to demystify what's happening. Agents aren't magic - they're just detailed instructions that shape how Claude approaches your project. Take your time here - understanding what's in these prompts makes everything else click.
Now we're going to create persistent agents that you can reuse anytime. This is what makes the workflow fast and repeatable.
In Claude Code, type:
/agents
This opens the agent setup wizard - an interactive menu that walks you through creating an agent.
Why are we doing this manually instead of having Claude auto-generate agents? Claude CAN generate agents for you, and that's useful later. But for learning, walking through the wizard yourself helps you understand what agents actually are - just text files with a name, description, and instructions. Doing it manually demystifies the magic.
Walking through the wizard:
The wizard will ask you for several things. Here's what to enter for each agent:
1. Create the Planner agent:
| Field | What to enter |
|---|---|
| Type | Choose "project" (stores it in this project folder) |
| Name | planner |
| Description | "Turns messy brain dumps into clear project plans with MVP scope and tasks" |
| System Prompt | Copy and paste everything inside the ``` code block from prompts/planner.md |
| Tools | Leave blank (inherits all tools - that's fine for now) |
| Model | Leave as default or choose "inherit" |
2. Create the Builder agent:
| Field | What to enter |
|---|---|
| Type | "project" |
| Name | builder |
| Description | "Implements Phase 1 of a plan as a web app running on localhost" |
| System Prompt | Paste from prompts/builder.md |
| Tools | Leave blank |
| Model | Leave as default |
3. Create the Verifier agent (optional):
| Field | What to enter |
|---|---|
| Type | "project" |
| Name | verifier |
| Description | "Adds lightweight tests or verification checklists" |
| System Prompt | Paste from prompts/verifier.md |
| Tools | Leave blank |
| Model | Leave as default |
What just happened? The wizard created markdown files in .claude/agents/ in your project folder. That's it - agents are just text files! You can open them in any text editor and see exactly what they contain. No magic, just configuration.
Why do this? Once these agents are set up, you can use them anytime by just saying "use the planner agent to..." You'll see the agent name appear as Claude works, which helps you understand what's happening. Plus, you won't have to dig up and copy-paste prompts every time.
Note: If you're in a hurry, you CAN just copy-paste the prompts directly without creating persistent agents. But setting them up properly is a skill worth learning - it's what makes this workflow actually fast in real use.
Just get your messy idea out. Don't worry about structure or being "correct."
Tip: Consider using Wispr (free) or Wispr Flow (paid) for voice-to-text. Why? Because AI models handle messy human speech surprisingly well, and talking is 3-4x faster than typing. You can literally ramble your idea out loud and paste the transcript. But typing works fine too!
Example brain dumps (Claude can handle all of these - messy is fine!):
"gift planning app"
"ok so like I want something where I can track my music practice? like what I practiced and for how long and maybe my mood or whatever and then it shows me streaks so I stay motivated"
"I have this problem where I keep having ideas for things I want to build or projects or whatever and they're scattered everywhere - some in notes app, some in voice memos, some I just forget entirely. I want like a place to dump all of them and have it somehow organize them for me, maybe cluster by theme or tag them or something? and then help me figure out which ones to actually pursue. basically an idea compost bin that turns chaos into plans. idk if thats too much but yeah"
Now use your planner agent:
Use the planner agent to turn this idea into a plan:
[paste your brain dump here]
The agent will:
- Ask 3-5 clarifying questions
- Propose a tiny MVP
- Create a
plan.mdwith scope, acceptance criteria, and Phase 1 tasks
Review the plan. Give feedback. Ask it to revise until you're happy. This is a conversation!
Now use your builder agent:
Use the builder agent to implement Phase 1 from plan.md.
The agent will:
- Build the minimal version
- Run it locally as a web app
- Give you a URL like
http://localhost:3000to open in your browser
This is a good time to catch up. While Claude is building, you can answer questions, help people who are behind, or discuss what's happening. The agent does the heavy lifting - you just approve permissions as they come up.
When Claude asks permission: Remember, you can always say "Explain what this command does first." Don't just approve things you don't understand - use it as a learning moment.
If you have time, use the verifier agent:
Use the verifier agent to check that the main features work.
Share your screen and show what you built! Even "it loads and shows one thing" is a win. The group energy at this point is usually amazing.
| Agent | What It Does | When to Use |
|---|---|---|
| Planner | Turns messy ideas into clear plans | Always start here |
| Builder | Implements Phase 1 as a web app you can see in browser | After you have a plan |
| Verifier | Adds light tests or checklist | Optional, after building |
| Agent | What It Does | When to Use |
|---|---|---|
| Business Analyst | Prioritizes features, cuts scope | When idea is too big |
| TDD Developer | Test-driven implementation | When quality > speed |
Find all prompts in the /prompts folder.
- Practice log - Track what you practiced, minutes, mood; weekly summary
- Setlist planner - Drag/drop songs, total duration, key changes warning
- Lyric fragments organizer - Dump fragments, cluster themes, export drafts
- Art prompt queue - Ideas + tags + "next up" queue
- Commission tracker - Status board: inquiry → sketch → final → delivered
- Palette vault - Save hex palettes, name and search them
- Idea compost - Dump random ideas, organize into clusters and plans
- Meeting to actions - Paste notes → tasks + owners + due dates
- Gift idea generator - Person + constraints → ranked gift list
Rule of thumb: If it needs login/OAuth, payments, or deployment to the real internet - save it for later. Keep it local!
This section is important. Read it before you start.
Claude Code runs commands on YOUR computer. That's powerful, but it means:
- Back up your laptop before the workshop if you have important stuff on it
- Ideally, use a secondary/old laptop if you have one lying around - think of it as your "toy box" for experimenting
- If something goes wrong, it's on your machine
True story: I was running agents autonomously on my home server. They kept creating Docker images without cleaning up old ones. Eventually I ran out of disk space and the whole server locked up. I had to physically reset it. It was fine because it was an experimental server I had created for the express purpose of toying around, and I was doing some pretty complicated stuff compared to what we're doing today, but move forward with caution.
Lesson: Agents are powerful but they don't AUTOMATICALLY think about things like "am I filling up the hard drive?" unless you have the right prompting/guardrails set up (advanced). Keep an eye on things.
When Claude asks to run a command:
- Read what it's asking - Even if it looks technical
- Ask for explanation - "What does this command do?" is always valid
- Then decide - You're the human in the loop
Example interaction (technical person):
Claude: I'd like to run: rm -rf node_modules
You: What does that command do?
Claude: This deletes the node_modules folder, which contains
downloaded code libraries. We're doing this to reinstall
them fresh and fix a version problem.
You: Ok, approved.
Example interaction (non-technical person):
Claude: I'd like to run: rm -rf node_modules
You: I have no idea what that means. Can you explain it
like I've never used a terminal before?
Claude: Sure! This command deletes a folder called "node_modules".
That folder contains a bunch of helper code that other
programmers wrote - think of it like ingredients for a recipe
that we downloaded from the internet. Sometimes these
ingredients get stale or conflict with each other, so we
delete them and download fresh ones. It's like clearing out
your pantry and restocking.
You: What's the risk? Could this break something?
Claude: Good question! The risk is low here. We're only deleting
downloaded code, not YOUR code or files. The worst case is
we'd need to re-download those ingredients, which takes a
minute or two. Your actual project files are safe.
You: Ok that makes sense, approved.
The point is: you can always ask Claude to explain more simply, and to tell you the risks. It will meet you where you are.
Claude Code has a flag called --dangerously-skip-permissions that lets Claude run commands without asking you first. People sometimes call this "YOLO mode."
The honest truth: This makes things go WAY faster. Like, 10x faster. Lightning speed. No constant approvals, just Claude doing its thing.
Personal note: I use YOLO mode regularly. When I'm in the zone and want to move fast, it's a game-changer. But I'm accepting real risk when I do that, and I've set up my environment to minimize the damage if something goes wrong. That took time and technical understanding to get right.
The risks are real. Claude might:
- Install things you didn't want
- Delete files it shouldn't
- Make changes you can't easily undo
- Fill up your disk space without you noticing
My recommendation: Get yourself a "toy laptop" - an old computer or a cheap refurbished one - specifically for experimenting with autonomous agents. Run YOLO mode there, not on your main machine with all your important stuff. That way you get the speed benefits without the stress.
For this workshop: Keep permissions ON. Learn the workflow first, speed it up later.
Long-term: I do encourage you to eventually get comfortable enough to make the jump to YOLO mode when appropriate. It unlocks a different level of productivity. But it's an advanced move that requires:
- Technical understanding of what commands do
- A proper risk assessment of your environment
- Backups and a machine you're okay experimenting on
- Experience with Claude so you can anticipate what it might do
This is a "graduate to it when you're ready" thing, not a "never do this" thing. The speed gains are real and worth pursuing - just do it thoughtfully.
Here's an honest list of things that might happen:
- Software conflicts - Claude installs a program that doesn't play nice with something you already have
- Messy folders - Claude creates a bunch of files and your project folder gets cluttered
- Port conflicts - Claude tries to run a server but something else on your computer is already using that spot (you'll see an error like "port already in use")
- Disk space - Claude keeps creating stuff without cleaning up old versions, and eventually your hard drive fills up
- Wrong file edited - Claude misunderstands which file you meant and changes the wrong one
None of these will destroy your computer. But they can be annoying to fix if you're not expecting them. Having backups and paying attention to what Claude is doing prevents most headaches.
Your Claude Pro subscription has limits. Here's how to not burn through them:
Important note: These tips are specifically for this beginner workshop where we want to get to a working demo quickly without running out of tokens. As you get more comfortable with Claude Code, you'll develop your own style and may choose to use tokens differently. Don't take these as hard rules for all situations - they're training wheels for today.
- Keep scope tiny - One feature, one screen, one file
- Get the happy path working first - Skip edge cases initially
- Use Planner → Builder only - The simpler flow uses fewer tokens
/clear- Clears your conversation and starts fresh. Use this between major tasks./compact- Summarizes your conversation to reduce context size. Use when things feel slow.
Having more specialized agents (like a Business Analyst doing detailed prioritization, or a TDD Developer writing dozens of tests) uses a LOT more tokens. Those agents exist in /prompts/advanced because they're valuable for real projects - they help you build better software. But for a first workshop, we skip them to get to the fun part faster.
Once you're comfortable with the basics, definitely explore the advanced agents. They're powerful for projects where quality and thoroughness matter more than speed.
You built something! Here's where to go from here:
The Multiverse School - This is personally what helped me learn a lot of this stuff. Highly recommend for:
- Advanced prompt engineering techniques
- Building autonomous agentic systems
- Going deeper on pretty much anything we touched on today
- Add more specialized agents - The system-prompts repo has my latest production-quality agents: full Requirements → Business Analyst → Project Manager → TDD Developer → QA Engineer pipeline, plus Incident Manager and System Analyst for ops work
- Create your own agents - Write custom prompts for your specific workflows
- Use Claude to write agents - Ask: "Help me write an agent prompt for [your use case]"
- Verification-Driven Development (VDD) - A pattern where a "builder" AI and an "adversarial reviewer" AI iteratively improve code. The reviewer tries to find flaws, the builder fixes them, repeat until solid. Learn more
- Agent chains - String multiple agents together (Requirements → BA → PM → Dev → QA)
- Autonomous loops - Have agents work continuously until done (with appropriate guardrails!)
The best way to learn is to keep making things. Try:
- Building something for a friend
- Recreating a simple tool you use daily
- Automating something tedious in your life
These tools are powerful. Some things to think about:
- You're responsible for the output - If Claude writes code with bugs or security issues, it's your code now
- Review before deploying - Never put AI-generated code in production without understanding it
- Be honest about AI use - If you're using AI to help with work, be transparent about it where appropriate
- Claude can see what you paste into it
- Don't paste sensitive data (passwords, API keys, private info) into prompts
- Your conversation may be used to improve the model (check Anthropic's data policy)
This is important and often overlooked: AI models are trained on human-generated data, and humans come with biases.
Think about it like this: we all go through HR training about treating people fairly, but people still don't always follow it. The biases exist even when we know better. The same thing happens with AI - the training data reflects the real world, including its unfairness.
This isn't hypothetical. There are documented cases:
- Amazon scrapped an AI hiring tool in 2018 because it discriminated against women - it was trained on resumes from a male-dominated industry and learned to downgrade resumes containing words like "women's" (as in "women's chess club captain")
- Research from University of Washington (2024) found that LLMs ranking resumes favored white-associated names 85% of the time and never favored Black male-associated names over white male-associated names
What does this mean for you?
- It's not the end of the world, but don't bury your head in the sand either
- Be aware that AI outputs may reflect societal biases
- If you're building something that affects people (hiring, lending, recommendations), take extra care
- Question outputs that seem to reflect stereotypes
- Anthropic and others are actively researching ways to reduce bias, but it's an ongoing challenge
If you want to learn more:
- Anthropic's work on pretraining data filtering - how they try to filter harmful content from training data
- Nature: Ethics and Discrimination in AI Recruitment - academic deep-dive on the hiring algorithm problem
The goal isn't to make you paranoid - it's to make you thoughtful. If you want to build a better world tomorrow, being aware of these issues is part of that.
The field is moving fast. Some honest observations:
- These tools are getting better rapidly - what's hard today may be easy in 6 months
- The skills you're learning (prompting, breaking down problems, working with AI) will remain valuable
- "AI will take our jobs" vs "AI will augment us" is a false binary - the reality is more nuanced
- The people who learn to work WITH these tools effectively will have significant advantages
This isn't just for "SF techies." If you're reading this and you built something today, you're already ahead of most people. Keep going.
- Claude Code Quickstart
- Claude Code Usage Dashboard - Check your limits here
- Claude Prompting Best Practices
- The Multiverse School - Highly recommended for going deeper on everything here
- Wispr - Voice to text for faster brain dumps
- VDD: Verification-Driven Development - Advanced adversarial verification pattern
Think about what YOUR friends might be curious about. Here are some topics that often come up, with starter resources if you want to go deeper:
1. How do these models actually work? LLMs are transformer-based neural networks trained to predict the next word in a sequence. They don't "think" like humans - they're very sophisticated pattern matchers. Understanding this helps set realistic expectations.
- Large Language Models - Wikipedia (good technical overview)
- What is a Context Window? - IBM (explains the "memory" limitation)
2. What's actually happening when I use Claude Code? This is important: Claude is not running on your computer. When you type something in Claude Code, here's what happens:
- Your message gets sent over the internet to Anthropic's servers
- Claude (running on their computers) reads your message and figures out what you want
- Claude decides what to do - maybe read a file, run a command, write some code
- Claude sends back instructions: "I want to run this command on your computer"
- Claude Code (the app on YOUR computer) asks your permission, then runs it locally
- The output gets sent back up to Anthropic's servers so Claude can see what happened
- Claude decides: "Am I done? Do I need to do more? Should I ask the human something?"
- This loops until Claude decides the task is complete, then it gives you a summary
So it's a back-and-forth: your computer ↔ Anthropic's servers ↔ your computer. Claude thinks in the cloud, but actions happen on your machine.
- Claude Code: Behind the Scenes of the Agentic Loop (great technical deep-dive)
- Anthropic: Claude Code Best Practices (official docs on the "gather context → act → verify → repeat" loop)
3. How companies attempt to make models helpful and safe(r) with varying success Anthropic uses "Constitutional AI" - the model is given a set of principles (a "constitution") and learns to critique and revise its own outputs. It's trained through a combination of human feedback and AI self-supervision. This problem has not been solved and there are ways to have this unintentionally broken.
4. Security deep-dive: What are the real risks? Beyond the basics we covered, there's prompt injection, data exfiltration risks, and the challenge of trusting AI-generated code. See above note on "unintentionally breaking" things. Good topic if you have security-minded folks in the room.
5. AI bias and fairness Models are trained on human-generated data, which includes human biases. This isn't hypothetical - there are documented cases of AI systems showing racial and gender bias in hiring, lending, and other domains.
6. The economics and environmental impact Running these models means running (often GPU-heavy) workloads in data centers, which translates into electricity use, cooling (sometimes water), and real costs/constraints on power + infrastructure. Who pays for that? What's the environmental cost? What happens when everyone is using 10x more compute?
- IEA: electricity demand, data center growth, grid constraints, and scenario-based projections
- OECD: framework for thinking clearly - direct/indirect paths, measurable vs. uncertain, where data gaps still are
7. Where is this all going? Agents, autonomous systems, AGI timelines, job market impacts. People have strong feelings and questions here. You don't need to have answers - facilitating the discussion is valuable.
Pro tip: You don't need to be an expert on all of these. "I don't know, but here's a resource" is a perfectly good answer. The goal is to open doors, not have all the answers.
Open an issue or reach out!