Your First Project

Beginner-Friendly Teaching Edition · Learning by Doing

What you will learn
This chapter walks through building a real command-line tool from zero using only conversation. You will practise a five-step loop — describe, review, execute, verify, iterate — and finish with an intuitive sense of what "conversational programming" actually feels like.

Describe requirementsReview the planConfirm executionVerify outputIterate

The Big Idea

The chapter opens with a short story. On the day the author's app Kitty Light launched, someone asked how long it took to go from idea to finished product. The answer was about one hour: five minutes to check that people actually wanted it, then a few rounds of conversation with an AI coding tool.

The key point the book draws from this: you did not need three months of learning to code first. You did not need to understand SwiftUI or React Native. You only needed to know what you wanted to make.

Easy way to remember:
Old requirement → "Learn to code, then build."
New requirement → "Know clearly what you want, then describe it."

Why This Topic Matters

Chapter 1 and Chapter 2 were about understanding and installing. This is the first chapter where you actually build something end to end. It matters because:

The five-step loop you learn here is the same loop every later project uses — from a tiny script to a full product.
It forces an important mental shift: you are the product manager, Claude is the engineer.
It teaches you to judge results instead of reading every line of code.
It shows you the normal bumps beginners hit, and that almost all of them have a standard fix.

Core Concepts

Conversational programming
You describe a need in plain language; Claude produces the plan and the code; you review and ask for changes.

The five-step loop
Describe requirements → Review plan → Confirm execution → Verify output → Iterate. Repeated as many times as needed.

"Plan first, code later"
Asking Claude for an implementation plan before it writes code. This makes it think the task through.

Trust, but verify
Let Claude run with the work, but check the result at every step — carefully during planning, lightly during coding, thoroughly at the output.

You own the what and the whether
Claude owns the how. Your attention lives at requirements, approach, and whether the result matches expectations.

Rewind (safety net)
Press Esc twice to open a menu that can roll back the conversation, the file changes, or both.

Step-by-Step: The Warm-Up (a 5-Minute Personal Homepage)

Before the main project, the book suggests a tiny warm-up so you feel one full "say → build → see" cycle.

1. Create a folder and start Claude Code

mkdir my-homepage && cd my-homepage
claude

Line 1 makes a new empty folder and moves into it. Line 2 launches Claude Code, which uses your current folder as its workspace.

2. Describe the page in plain language

Build me a personal homepage. Single-page HTML, make it look good.
Content: my name is [your name], and I'm a [your role/identity].
Add a tagline, an about section, and placeholder social media links at the bottom.
Use a modern minimalist style with responsive layout.

What this demonstrates: the request names the deliverable (single-page HTML), the content (name, role, tagline, about, links), and the style (modern minimalist, responsive). Concrete instructions produce a usable first result.

3. Open the file and look

open index.html      # macOS
xdg-open index.html  # Linux
start index.html     # Windows

These three commands each open a file in the default browser — one per operating system.

4. Iterate by talking

Change the color scheme - use a dark background with light text. Switch to a serif font.
Add an animated gradient background effect.

Claude updates the file; you refresh the browser and see the change. Repeat until you are happy. The book notes the whole warm-up takes under five minutes, but you have now done one complete loop: describe → Claude implements → review → suggest changes → Claude adjusts.

Optional next step from the book: say "Help me deploy this page to GitHub Pages." Claude will create a Git repository, push the code, and configure GitHub Pages — roughly another five minutes — and you have a live personal homepage.

Remember: Every project that follows, no matter how complex, is just this same loop running repeatedly.

Step-by-Step: The Main Project (an AI News Aggregator CLI)

What you are building: a command-line tool that:

Fetches the latest articles from a few RSS feeds (TechCrunch AI, The Verge AI, Hacker News, etc.).
Uses AI to summarise the key points of each article.
Outputs a neatly formatted Markdown digest.

Why this project? The book picks it because it is small enough to finish in an afternoon, yet complete enough to touch networking, data processing, AI API calls, and file output — the full range of what Claude Code can do.

The mental shift to make first: from now on, you are the product manager and Claude is your engineer. Your job is to state clearly what you want — not to write code. The book says to try it this way even if you are an experienced developer.

Step 1 — Tell Claude what you want

mkdir ai-news-digest && cd ai-news-digest
claude

Then, in plain language, describe the requirement:

# What you type into Claude Code:
Build me an AI news aggregator CLI tool. Here's what I need:
1. Fetch articles from the last 24 hours from these RSS feeds:
   - TechCrunch AI (https://techcrunch.com/category/artificial-intelligence/feed/)
   - The Verge AI (https://www.theverge.com/rss/ai-artificial-intelligence/index.xml)
   - Hacker News top 30 (https://hnrss.org/newest?q=AI&count=30)
2. Extract title, link, publish time, and source for each article
3. Sort by time descending, and output a Markdown digest to the output/ directory
4. Write it in TypeScript, run directly with tsx
Don't start coding yet - give me an implementation plan first.

Explaining that request, line by line

Part of the request	Why it is written this way
"last 24 hours" + exact feed URLs	Gives concrete data sources instead of a vague "a few RSS feeds", so Claude does not have to guess.
"Extract title, link, publish time, and source"	Defines exactly which fields the output must contain.
"Sort by time descending … Markdown digest to the output/ directory"	Describes the final deliverable and where it goes.
"Write it in TypeScript, run directly with tsx"	Fixes the tech stack so the plan is predictable.
"Don't start coding yet - give me an implementation plan first"	The important technique: force Claude to think it through before acting.

Remember: The quality of your requirements description directly determines the quality of the output. Be clear about the deliverable, specify the tech stack, and give concrete URLs and values.

Step 2 — Review the plan

Claude does not code immediately. It replies with a plan that looks roughly like this:

Here's my plan for the AI news aggregator:

Project structure:
ai-news-digest/
├── src/
│   ├── index.ts        # Entry point
│   ├── fetcher.ts      # RSS fetching logic
│   ├── formatter.ts    # Markdown formatting
│   └── types.ts        # Type definitions
├── output/             # Digest output directory
├── package.json
└── tsconfig.json

Technical approach:
- RSS parsing via rss-parser
- HTTP requests via Node's built-in fetch
- Date handling via date-fns
- Run TypeScript directly with tsx - no compile step needed

Implementation flow:
1. Fetch all three RSS feeds in parallel
2. Normalize format, filter to articles within 24 hours
3. Sort by time
4. Generate Markdown digest
5. Write to output/YYYY-MM-DD.md

Ready to start implementing?

What to do now: read it like an engineering proposal. If it looks right, say OK. If you want changes, say so plainly. The book's example feedback:

# Your feedback:
The plan looks good. Two additions:
1. For each article in the digest, include a one-sentence summary (first 100 chars from the article)
2. Add a stats header at the top of the digest: "X articles collected from Y sources"

This back-and-forth — Claude proposes, you add details, Claude refines — is described as the core of conversational programming. No flowcharts, no technical specs, just plain language.

Step 3 — Watch Claude work

Initialize the project. Claude runs npm init -y and installs dependencies. You see a permission prompt like Claude wants to run: npm init -y Allow? (y/n). Press y. It will ask again for rss-parser, date-fns, tsx, and others.

Create the source files. Claude writes the TypeScript files one by one, showing a diff for each. You do not need to read every line — just scan that the structure looks reasonable.

Run a test. Claude usually runs the code to check for errors. If there are errors, it reads the message, finds the problem, fixes the code, and runs again — an automatic self-repair loop.

The book says this takes about 2–5 minutes, and your job is simply to watch — like observing a new colleague the first few times before you trust their style.

Important: Claude may ask for permission many times. Early on, glance at each command. Once comfortable, you can pre-authorise common commands with /permissions (covered in Chapter 4) or switch to Auto mode.

Step 4 — Verify the output

npx tsx src/index.ts

If it worked, a Markdown file appears in output/ that looks something like this:

# AI News Digest - 2026-03-28
> 23 articles collected from 3 sources

## TechCrunch AI

### OpenAI Releases GPT-5.4 with 2M Context Window
🔗 https://techcrunch.com/2026/03/28/openai-gpt-54/
📅 2026-03-28 14:30
> OpenAI today released GPT-5.4, with the biggest change being an expanded context window...

### Anthropic Launches Claude Code Desktop App
🔗 https://techcrunch.com/2026/03/28/anthropic-desktop/
📅 2026-03-28 11:00
> Anthropic announced that Claude Code is now available as a desktop application...

## The Verge AI
...

Expected result: the book says in most cases it works on the first try. If there is an error, paste the full error message to Claude:

# When the run fails, paste the error to Claude:
Got an error when running:
TypeError: Cannot read properties of undefined (reading 'map')
  at formatArticles (src/formatter.ts:15:23)

Claude reads the error, finds the issue, fixes it, and runs again. This fix loop usually takes only 1–2 rounds.

Step 5 — Iterate and improve

It works, but you want more. You keep talking. The book gives three improvements:

# Improvement 1: add AI summaries
Right now each article's summary is just truncated from the description - pretty rough.
Change it to use AI: for each article's title + description, call the Claude API to generate a summary.
Read the API key from the environment variable ANTHROPIC_API_KEY.

# Improvement 2: add scheduled runs
Add a cron mode that automatically runs at 8am every day, using node-cron.
Add a CLI argument:
- `npx tsx src/index.ts`        runs once immediately
- `npx tsx src/index.ts --cron` enables scheduled mode

# Improvement 3: add deduplication
Some articles appear across multiple sources. Add URL-based deduplication.

What each round demonstrates: Claude updates the code, runs the tests, and confirms the result. You only ever do two things — say what you want, and verify that it is right.

Remember the whole shape:
Describe Requirements → Review Plan → Confirm Execution → Verify Output → Iterate.
Tiny utility or full product — the underlying pattern is always these five steps.

Simple Example: The Loop in One Picture

You: "Build X. Give me a plan first."
        ↓
Claude: proposes a plan
        ↓
You: "OK" (or "change these 2 things")
        ↓
Claude: writes files, runs tests, self-fixes
        ↓
You: run it, check the output
        ↓
You: "Now also add Y"   ──────► (loop back)

The Mental Shift (explained)

After finishing the project, the book wants you to feel one thing: your value is not in writing code — it is in defining what to build and judging whether it was built right.

Many engineers instinctively want to read every line and understand every detail. That is natural, but it slows you down. A better approach is to manage Claude like a team member:

Traditional programming	Programming with Claude Code
Design the solution yourself, write the code yourself	Describe the need; Claude produces the plan and code
Debug line by line	Give Claude the error message; it debugs itself
Read docs, search Stack Overflow	Ask Claude directly: "how do I implement X?"
Code review done manually	Ask Claude to explain what it wrote
Refactoring requires understanding all the code first	Tell Claude: "refactor this into the X pattern"

This does not mean ignoring the code entirely. It means your attention operates at a higher level: Are the requirements accurate? Is the approach sound? Does the result match expectations?

Common Beginner Questions (from the book)

"What if I can't understand the code?"

Just ask. "Explain the implementation logic in fetcher.ts" — Claude explains it in plain language. You can follow up: "Why use Promise.allSettled instead of Promise.all?" The book's analogy: you do not need to know how to rebuild an engine — you just need to know when the car is running normally.

"What if it gets something wrong?"

Recommended
"After running, only TechCrunch articles show up — articles from the other two sources are missing. Check the fetching logic."

Not recommended
"Your code has a bug on line 23." (unless you actually know where the problem is)

Describing the symptom is more effective than pointing at a line number. The real cause may be somewhere you would not expect.

"How much oversight should I have?"

Four words: trust, but verify. Read carefully during planning. A quick scan of the file structure is enough during coding. Check the output against expectations during execution. Test edge cases thoroughly during iteration — empty data, network timeouts, malformed input.

"What if it goes off the rails?"

If it is slightly off, correct it: "Stop — don't use the XXX library, switch to YYY." If it is badly off, press Esc to stop and re-describe the requirement from scratch. Pressing Esc twice opens the Rewind menu: roll back the conversation, roll back file changes, or both.

Rule of thumb from the book: if two corrections have not fixed it, stop and start over. Patching on top of a wrong foundation just makes things messier.

Real-World Use Cases

Kitty Light — a solid-colour "fill light" card app, built in about an hour with an AI coding tool after a five-minute demand check. (Built with Cursor because Claude Code had not launched yet, but the book says the experience is identical.)
A personal homepage shipped to GitHub Pages in about ten minutes total.
The AI news aggregator from this chapter — a real CLI tool touching networking, data processing, AI API calls, and file output.
Any afternoon-sized utility where you can clearly state the inputs, the processing, and the output format.

Visual Mental Model: Who Owns What

You (Product Manager)
• What are we building?
• Are the requirements accurate?
• Is the plan's direction right?
• Does the output match expectations?
• What should change next?

Claude (Engineer)
• Produce an implementation plan
• Scaffold the project, install packages
• Write and modify the code
• Run tests, read errors, self-fix
• Explain any part on request

Important Comparisons

Vague request vs. specific request

Vague (weak result)	Specific (strong result)
"Make it look nice"	"Dark background, large headline, card layout, rounded corners"
"Add that feature"	A self-contained sentence naming exactly which feature and where
Ten requirements in one message	2–3 short messages, a few requirements each

The five steps and how much attention each needs

Step	Your attention level	Why
Describe requirements	High	Everything downstream depends on this being clear.
Review plan	High	Cheapest place to fix a wrong direction.
Confirm execution	Low–medium	Glance at commands early; scan file structure.
Verify output	High	Does the real result match what you asked for?
Iterate	Medium–high	Test edge cases: empty data, timeouts, bad input.

Common Beginner Mistakes

Skipping the plan. Letting Claude code immediately instead of asking for a plan first.
Vague requirements. "Make it nice" instead of concrete style and structure.
Assuming context. "Add that feature" — Claude does not know what "that" refers to. Every request should stand on its own.
Too many things at once. Ten requirements in one message; Claude may quietly drop a few.
Reading every line and trying to understand every detail instead of judging the result.
Retyping error messages by hand instead of copy-pasting the full text from the terminal.
Patching a broken foundation. More than two failed corrections — start over instead.

Best Practices (from the chapter)

Always ask for a plan first: "Don't start coding yet — give me an implementation plan first."
Be specific about the deliverable, the tech stack, and the data — give real URLs and values, not vague references.
Break big requests into 2–3 messages.
Give the full error message, copied directly from the terminal.
Describe symptoms, not line numbers, when something is wrong.
Trust, but verify — match your attention to the step you are in.
Know that Rewind exists (double Esc) so you can work without anxiety.
Test edge cases during iteration: empty data, network timeouts, malformed input.

Troubleshooting Guide (beginner snags and their standard fixes)

Symptom	Usual cause	Standard fix
Files were created but running throws an error	Missing dependency or unset environment variable	Paste the full error to Claude: "Got an error when running: [paste]. Please fix it." One round fixes it about 90% of the time.
Still broken after two fix attempts	Environment issue (Node.js version, permissions)	Tell Claude your setup: OS version, Node.js version, npm version, and ask if it could be an environment issue.
Claude seems to "think" and nothing happens for over a minute	Interrupted flow, network issue, or the request is too large	Press `Esc` to interrupt and resend. Check your connection. Break large files into pieces: "Just look at the first 100 lines — any issues?"
The result looks nothing like what you wanted	Requirements description problem	Re-read what you said. Fix vagueness, assumed context, or too-many-things-at-once.
Claude modified files it should not have touched	—	Press `Esc` twice → Rewind menu → roll back conversation, files, or both.
Dependency install fails / is very slow	Network (the book notes this on mainland-China networks)	Use a mirror, e.g. `npm config set registry https://registry.npmmirror.com`, or ask Claude for an alternative package. Python: `pip install -i https://pypi.tuna.tsinghua.edu.cn/simple package-name`.
Hit the token / usage limit (Pro plan)	Daily quota reached	Wait a few hours for the reset, upgrade to Max 5x, or stop for the day. Use `/compact` to compress conversation history and reduce token use.

The single most important troubleshooting tip in the chapter: give Claude the full error message, copy-pasted (not retyped). With the complete error in front of it, Claude can self-resolve about 90% of problems.

Interview / Revision Questions

What are the five steps of the conversational programming loop?
Why does the book tell you to add "give me an implementation plan first" to your request?
In this workflow, what do you own and what does Claude own?
What is the warm-up project, and what single skill is it meant to teach?
What does the AI news aggregator project touch that makes it a good first project?
How much attention should you give during planning versus during coding versus at the output?
What is the recommended way to report a bug — symptom or line number? Why?
What does "trust, but verify" mean in practice at each step?
What is Rewind, and how do you open it?
What is the rule of thumb if two corrections have not fixed a problem?
What is the single most important troubleshooting tip in the chapter?
Name three common reasons a result "looks nothing like what you wanted."

Practice Exercises

Exercise 1: Do the 5-minute warm-up. Build a personal homepage, then iterate twice on colour and font by conversation only.

Exercise 2: Write a requirements message for a small CLI tool of your own. Include: the deliverable, the tech stack, concrete inputs, and the line "give me an implementation plan first."

Exercise 3: Take a plan Claude gives you and send back exactly two specific additions, the way the book's example does.

Exercise 4: Deliberately cause an error, then practise the fix loop: copy the full error, paste it, ask Claude to fix it, verify.

Exercise 5: Practise Rewind. Make a change you dislike, press Esc twice, and roll back files only.

Exercise 6: Add three improvements to a working project in three separate messages (not one), and verify after each.

Quick Memory Map

Your First Project
│
├── Mindset
│   ├── You = product manager (what / whether)
│   └── Claude = engineer (how)
│
├── The 5-step loop
│   ├── 1. Describe requirements  (be specific)
│   ├── 2. Review the plan        ("plan first, code later")
│   ├── 3. Confirm execution      (watch; approve commands)
│   ├── 4. Verify the output      (does it match?)
│   └── 5. Iterate                (talk; test edge cases)
│
├── Safety
│   ├── Trust, but verify
│   └── Rewind = Esc Esc (conversation / files / both)
│
└── Troubleshooting
    ├── Paste the FULL error (copy, don't retype)
    ├── Describe symptoms, not line numbers
    ├── Break big requests into 2-3 messages
    └── Two failed fixes -> start over

Complete Chapter Revision

You do not need to learn to code first — you need to know clearly what you want to build.
The warm-up (a personal homepage) exists to make you feel one full say → build → see cycle.
The main project is an AI news aggregator CLI, chosen because it touches networking, data processing, AI API calls, and file output.
Every project uses the same five-step loop: describe → review plan → confirm execution → verify output → iterate.
Always ask for a plan before code; review it like an engineering proposal.
During execution you mostly watch and approve commands; later you can pre-authorise with /permissions or use Auto mode.
Trust, but verify — match attention to the step; test edge cases when iterating.
When something breaks, paste the full error and describe symptoms, not line numbers.
Rewind (double Esc) can undo conversation, files, or both — your safety net.
If two corrections fail, start over rather than patch a broken foundation.
Your lasting value: defining what to build and judging whether it was built right.

Final Takeaway

The chapter's central lesson:

Building a real project with Claude Code is one repeatable conversation loop — describe requirements, review the plan, confirm execution, verify the output, iterate.

You own the what and the whether; Claude owns the how. Once that division of labour becomes second nature, your productivity moves to a different level.

This teaching edition is based on the supplied April 2026, 2nd edition of Claude Code: The Complete Guide (§03, "Your First Project"). The source describes itself as a continuously updated guide, so specific commands, package names, plan limits and statistics can change over time.