Welcome to
the world of
Claude Code.
A gentle guide to building things you’ve only imagined, starting with that tube widget you’ve always wanted.
You don’t need to know how to code to build something real.
You already know how to brief a team, hold a line on a drawing, and spot a badly detailed junction at twenty paces. That instinct is the job here. Claude does the typing.
Think of Claude Code as a brilliant graduate architect on your team who types at ten thousand words a minute and has read every building manual ever written. They need a brief. They need rules. They need you to check the drawings. Give them those three things and they’ll build anything.
By the end of this guide you’ll have built your first real thing. Take your time. Every pause point in this deck is a chance to try it yourself.
A tube
widget.
Your widget.
Live delay times. Next arrivals. The lines you actually take, in one glance on your lock screen.
We’ll start with a simple web version you can play with today, then turn it into something that lives on your iPhone.
So what is Claude Code?
Imagine a coding partner who:
- → Lives in your terminal (that black window with text)
- → Reads and writes files on your computer
- → Runs commands for you
- → Never gets tired or annoyed
- → Works at whatever pace you do
That’s Claude Code. A chat window, connected to your computer, with Claude on the other end.
The whole thing,
in one picture.
Three players. That’s it.
You brief Claude. Claude builds on your computer: reading files, writing code, running commands. You watch, comment, and steer. Same dynamic as you and a good contractor, just compressed into minutes instead of months.
Let’s install it.
This takes about 5 minutes. Tick each step off as you go.
Install your tools.
We’re installing two things. Claude Code is the brain. Superset is a beautiful Mac app that lets you run Claude (and friends) in a calm, organised way, one project per window, without touching Terminal much at all.
⌘ + Space, type “Terminal”, Enter). Paste this and hit return:
⌘+Shift+G, paste ~/.superset/projects/tfl-widget, hit Enter. Your files are all there. For future projects, use the Desktop path above.
Same Claude, but with a proper home. You can see your files, the changes Claude makes, and the chat, all in one window. Later you can even run several projects at once in separate tabs. Think of Superset as the site office: Terminal was the open pavement.
Stuck on a step? Take a breath. Show whoever’s guiding you the exact error you see, they can help.
Say hello.
You’re in Claude Code. A blinking cursor is waiting. Let’s warm up.
Your first three prompts
Type each one, press Enter, watch what Claude does. No wrong answers, you’re just getting a feel.
Claude understood what you wanted, wrote to your computer, and told you what it did. That’s the whole loop. Everything else is just scaling this up.
Six words
to start with.
Learn these and you’ll understand most of what people say about AI coding. Don’t memorise them, we’ll use each one as we go, and a few more will show up along the way.
Context is
the whiteboard.
Every conversation has a shared whiteboard. Claude can only see what’s written on it right now.
What goes on the whiteboard: your messages, the files you’ve shown it, the outputs of commands it’s run.
What does not: yesterday’s chat, other projects, anything on the internet it hasn’t been shown.
sees this
The whiteboard fills up. When it does, Claude starts forgetting the earliest things you said. Keep chats focused. Start a fresh session for each new topic.
## About me
I live near Oxford Circus.
I take the Central line mornings
and Victoria line evenings.
## Rules for Claude
- Keep the design clean and modern.
- Use the real TFL line colours.
- Ask before installing anything new.
## Style
- Rounded corners, soft shadows.
- San Francisco font (the Apple one).
Memory
is a note
to itself.
The whiteboard gets wiped. Memory doesn’t.
There’s one magic file called CLAUDE.md. Whatever’s in there, Claude reads at the start of every session.
Tell it who you are, what you’re building, and how you like things. It’ll remember next time too.
CLAUDE.md is
your project code.
Every construction project has a code sheet: the rules, the conventions, the “how we do things here”. CLAUDE.md is the same thing for your project, and Claude reads it every single time you start a session.
Get this file right and Claude feels like it’s known the project for months. Get it wrong, or bloat it, and every session starts with it noisily clearing its throat.
The ideal CLAUDE.md, one page, tidy
Five rules straight from the Claude Code team.
Boris Cherny (the engineer who built Claude Code) and his team share CLAUDE.md across the whole Anthropic codebase. Here’s how they keep it healthy.
Keep it short.
Aim for under 300 lines. The best ones sit under 60. Every line goes into every session, so every line is paying rent.
Only universal things.
Don’t put rules that only apply sometimes. If it only matters in one corner of the project, make a second CLAUDE.md inside that folder.
Grow it by correction.
When Claude makes a mistake, end your correction with: “Update your CLAUDE.md so you don’t make that mistake again.” It is strangely good at writing rules for itself.
Let /init start it.
Type /init in Claude and it writes you a sensible first draft based on what your project looks like. You refine from there.
Prune it monthly.
Ask Claude: “read our CLAUDE.md and suggest what we can cut. We want it tighter.” A fresh pair of eyes keeps the project code readable.
Commit it to Git.
CLAUDE.md belongs with the project, not on your Mac. When you save checkpoints, it gets saved too. Future-you will thank past-you.
Think of CLAUDE.md as the project execution plan: site constraints, office standards, approved materials, responsibilities. Read on day one of every stage. Grows only when a lesson learned earns its place.
Five rules
to start with.
Copy these into your project’s CLAUDE.md on day one. Delete anything that doesn’t apply to you. Grow the rest as you go.
→ Full 14-rule starter: templates/CLAUDE.md.starter in ship-it. Tests-before-code and nine other rules live there, ready when you are.
There’s a well-known pattern in AI-assisted coding called the 70% problem: AI will happily get you to something that almost works, fast. The last 30% (edge cases, consistency, the little details) is where projects stall. CLAUDE.md is how you close that gap. Every rule you put in it is a small piece of taste Claude can now share with you.
Tokens, context,
and the bill.
Everything Claude does costs a tiny amount. Before we go any further it’s worth ten minutes on how that works, so nothing surprises you.
A token is about four characters.
Short message: a few tokens. A paragraph: about 100. A whole code file: several thousand. Claude’s “whiteboard” (the context window) currently holds up to a million tokens. That sounds like a lot until you start loading a whole codebase into it.
Target 50% context. Past 80%, Claude starts compacting.
When the whiteboard is half-full, Claude is at its sharpest. Past 80%, it starts compacting the earliest parts of your chat to make room, summarising what came before rather than carrying every word. Keep chats focused. Start a fresh session when you switch topics.
Costs: two ways to pay.
Pay-as-you-go (API)
Every message costs a fraction of a penny. No caps. You top up credit as needed. Great for low usage or weekend tinkering.
Subscription (Claude Code Max)
A flat monthly price with a generous daily message limit plus a weekly one. Better if you’re coding every day. If you hit the cap, Claude pauses you until the window resets.
A well-written CLAUDE.md saves you tokens because Claude starts every session oriented instead of having to re-read half the project to catch up. Writing it well is a cost control, not a cost.
Check where you’re at: /usage
Any time you want to know how much of your plan’s daily or weekly allowance you’ve used, just type /usage in the chat and hit Enter. Claude shows you:
- → Your current plan (Free, Pro, Max, Team)
- → How much of the daily limit is used, and when it resets
- → How much of the weekly limit is used, and when it resets
- → This session’s spend so far
Peek at it once a day while you’re getting used to the rhythm. After a week or two you’ll have a feel for what’s expensive and what isn’t.
Claude tells you when the window resets (usually a few hours). You can either wait, or upgrade your plan at claude.ai/settings/billing.
The status line: your dashboard.
When Claude Code is running in your terminal, a little strip at the bottom of the chat shows you everything at a glance.
To turn it on, you don’t edit any files yourself. Just tell Claude what you want to see. In the chat, type:
Claude Code writes a tiny script, saves it into your settings, and the status line appears at the bottom of the chat after your next message. No JSON to paste, no file to create.
In your tfl-widget folder, run the command above. Wait a beat, then look at the bottom of the chat. Point at each segment in turn and say aloud what it tells you. That’s the dashboard you’ll glance at a hundred times a day.
Four modes,
one shortcut.
Every time Claude wants to edit a file or run a command, it pauses and asks. That’s the default, and it’s a good place to start. Sometimes you want fewer pauses, sometimes you want none. Four modes give you that dial.
Press Shift + Tab in the chat to cycle. The status line at the bottom tells you where you are.
The bottom of your chat, one row per mode. Shift+Tab moves you down the list and back up.
Default
Claude asks before every edit and every command. Best while you’re learning, or any time you’re touching something important. The status line stays quiet.
Accept edits
Claude edits files in your project without asking. It still asks before running commands. Best when you trust the direction and would rather review the diff after. Status line shows ▸▸ accept edits on.
Plan mode
Claude reads, researches, and writes a plan, but doesn’t touch anything. When the plan looks right you approve it, and it starts building. Best before a big change. Status line shows plan mode on.
Auto mode
Claude runs without asking. A background safety check blocks the risky things: production deploys, pushing to main, deleting files it didn’t create, running code pulled from the internet. Best for long, well-scoped tasks you trust. Needs a Max, Team, or Enterprise plan. Status line shows ▸▸ auto mode on.
Even in auto mode, if you tell Claude “don’t push until I say so” or “wait for my review before deploying”, it honours that. The safety check treats those lines as hard stops until you lift them in a later message.
Press Shift + Tab a few times in your chat. Watch the status line at the bottom change as you cycle. Land back on default when you’re done exploring, that’s the mode you’ll want for most of Part 2.
The cache
(the one other word).
Claude has a kind of muscle memory. The first time it reads something, it’s slow. Reading the same thing again right after? Fast and cheap.
That’s the cache. You don’t need to manage it. Just know: staying inside one focused conversation is faster than restarting over and over.
Finish a thought before switching topics. Your wallet and your patience will thank you.
Three brains.
Pick one for the job.
There isn’t just one Claude. There’s a family. Each has its own speed, depth, and cost. Most of the time you won’t need to choose, Claude Code defaults well. But it helps to know.
The architect.
The hero.
The sprinter.
Stick with Sonnet for most of today. Reach for Opus when something feels hard and you want real thought. You can switch any time by typing /model, the / at the start tells Claude it’s a built-in shortcut, not a message.
(Version numbers move quickly. Check claude.ai for the current family if you want the freshest one.)
Tools are the verbs.
Claude talks to you in English, but inside, it works through a small set of tools. Here’s the family.
Read
Open a file and look at it. The most basic thing, Claude can see what’s already there.
Write
Create a brand new file. Claude fills it in with whatever you’ve asked for.
Edit
Change a small part of an existing file. Faster and safer than rewriting the whole thing.
Run
Run any command in the terminal, installing things, starting a server, peeking at what’s in a folder. (Inside Claude this is called “Bash”, same thing.)
Web Search & Fetch
Look things up on the internet. Read a specific page. Fetch a live API, like the TFL one.
Task (Agents)
Send a sub-job to a helper. More on this in a moment.
The first time Claude uses a tool in a new folder, it asks “is this okay?”. That’s your safety net. Say yes if you trust it, no if you want to check.
Sub-agents are
specialists.
When a job is big or distracting, Claude can spin up a helper with a single purpose, research this, review that, and get a clean answer back.
Why it matters: your main Claude stays focused on the thread of work. The helper handles the side quest.
Skills are
standard details.
An architect doesn’t re-draw the same parapet flashing on every job. You keep a library of standard details and call them by name.
A skill is the Claude version of that: a named, reusable workflow you invoke by typing a forward slash. Instead of typing out the same instructions every time, you type one word.
Three things to know.
Type a slash.
Typing / in the chat brings up a list of available skills. You don’t have to memorise them.
Built-in, then your own.
Claude ships with a handful (/init, /model, /clear). You’ll learn to add your own in Part 2.
They’re just files.
Each skill is a tiny file in your project that tells Claude what steps to run. Like a standard detail in a details library.
If you find yourself typing the same instructions twice, that’s a skill waiting to happen. Part 2 will show you how to make them.
Prompting is
just good briefing.
Imagine briefing a smart friend who’s brilliant but has never met you. What would they need to know?
“Make me a TFL widget.”
Too vague. Claude will guess at everything, which lines, what style, what data, and you’ll spend the next hour undoing its guesses.
“Build a web page that shows next arrivals for the Central and Victoria lines at Oxford Circus. Use real TFL colours. Keep it minimal. Refresh every 60 seconds.”
Specific. Scoped. Claude knows what to build and what to leave out.
1. What, the thing you want
2. For whom / where, context Claude couldn’t guess
3. Constraints, colours, tone, size, tech, anything you care about
Sometimes
Claude makes
things up.
It’s called a hallucination. Claude will confidently say a function exists when it doesn’t, or invent a library that was never built.
It’s not lying. It’s pattern-matching, and sometimes the pattern is plausible but wrong.
How to spot it
It sounds perfectly reasonable but something feels off. A library name you’ve never heard of. A command that fails in a weird way. Too-clean-to-be-true answers.
How to prevent it
Ask Claude to show its sources. Tell it to read the real docs first. Say “if you’re not sure, say so.” A good prompt beats a hallucination.
Five rules that
save you hours.
These come from real projects built exactly the way we’re going to build yours. Treat them like gentle laws.
The spec wins.
Write down what you want, clearly, before you build. When Claude and you disagree, the written spec is the tie-breaker. No written spec? You’ll drift.
Small steps, not giant leaps.
Ask for one thing at a time. Build it. See it work. Then the next thing. Trying to build the whole widget in one prompt ends in tears.
Don’t let it wander.
If Claude starts “improving” things you didn’t ask about, stop it. “Only do X. Leave Y alone.” Scope is your friend.
Read what it writes.
Claude shows you diffs and summaries. Skim them. Ask “why did you do it that way?” when something feels odd. You’re the human in the loop.
Save checkpoints.
When something works, tell Claude to save the moment, it’ll use a tool called Git to make a checkpoint (the word is “commit”). If the next change breaks everything, you can rewind to the last good version. You don’t need to set Git up yourself, just ask Claude to handle it.
Git is your
revision stamp.
Every architect knows the fear of a “final_final_v7_Janika_use_this_one.dwg” moment. Git stops that happening. It gives every change a revision, a reason, and a way back.
Git · the revision log
A tool that lives on your Mac. Every time you save a checkpoint, Git stamps it with who, when, and what changed. You can rewind to any stamp, any time.
GitHub · the office server
A website that stores your Git history in the cloud. A safe copy that survives your laptop dying, and lets others see your work.
The four words you’ll hear.
The whole lifecycle, in one picture.
Worktrees: two hands on the pencil.
A worktree is a second copy of your project on your Mac, linked to a different branch. Two Claudes can run in parallel on two different features without stepping on each other. Like giving two junior architects separate drawing sets for separate rooms so neither blocks the other.
You don’t need to learn any Git commands. Just say to Claude: “please commit this”, “push to GitHub”, “open a pull request”, or “make me a worktree for this” and it handles the ceremony. You stay at the level of intent.
Let’s build
your widget.
We’ll go in four small steps. Each one ends in something you can see and play with.
A written plan
Ten minutes with Claude to agree on: which lines, which stations, what it looks like, what it needs to do. This is your spec.
A working web version
A simple web page that shows live arrivals from TFL’s real API. Runs in your browser in one click. We’ll see it tonight.
Polish it
Real colours. Nice typography. Loading states. The little touches that make it feel like a product.
The iPhone widget
Turn the web version into a real widget on your lock screen. This is its own adventure, a project for another evening.
Steps 1 and 2. One hour. Something you can show your friends tonight. That’s a win.
TFL’s live tube data is free, but they want you to register for an app key (a small password so they know who’s asking). Five minutes, with a couple of small traps. Follow these in order.
You can’t break your Mac doing this. The worst that happens is some code doesn’t work, and we start that bit over. Messy is normal. Nothing is final.
Kick it off.
You’re in the tfl-widget folder with Claude running. Time to steer.
Start with a conversation, not code.
Copy this and paste it to Claude. Then chat back and forth until you both agree on the plan. These prompts are starting points, change the words to suit you.
I’m not a coder. Talk to me like a friend who’s about to design this with me.
Before we write a single line of code, ask me five questions that will shape the design. Things like which lines I care about, which stations, how it should look, how often to refresh. Keep it simple.
Save the plan to memory.
Once you’re happy, ask Claude to write it down so it doesn’t forget:
Ask for the smallest working thing.
Here is my TFL app key: <paste your key here>
No styling yet, plain and ugly is fine. Once it works, we’ll make it beautiful. When you’re done, tell me exactly how to open it in my browser.
Open your creation.
Once Claude says it’s done, find the index.html file in your tfl-widget folder (use Finder) and double-click it. Your default browser will open and, hopefully, show live tube times.
Didn’t work? Not a problem. Paste the error or the blank page back to Claude and say: “Here’s what I see. What do you think is going wrong?”
Say: “Show me the error in your own words. What do you think is going wrong?”
The little
dictionary.
Every word you’ll hear, in plain English. Bookmark this page. You’ll come back to it.
End of Part 1.
You know more than enough to ship the first version. The rest you’ll pick up by doing.
Build the widget. Break it. Ask silly questions. Change your mind. That’s the whole job.
When you’re ready, open Part 2: the Ship It Graduate Deck.
Open Part 2 →Made with ♥ for Janika.
Now go and ship something.
Stuck on something?
Type it here. It goes straight to Munim.