Chapter 0: Mindset, and your first agent

Draft chapter. This is the first cut used to prove the format and the running-project structure; it will be hardened before it is indexed.

What you’ll build

By the end of this chapter you’ll have a coding agent installed, you’ll have given it one small but real task in an actual repository, and you’ll have watched it work start to finish: read the code, propose a change, and hand it to you to review. That task is the starting point for the project that runs through the whole book: a PR-reviewer agent that reads a diff and flags bugs and risks. You don’t build that agent yet. First you use a general coding agent to do one slice of the review by hand, so you understand the problem concretely before adding any abstraction on top.

More importantly, you’ll make the shift the rest of the book depends on: from typing every line yourself to directing and reviewing. Microsoft’s “intro to AI agents” lesson defines an agent as a system that perceives an environment, reasons, and acts toward a goal using tools. That definition is fine, but for a working developer the real change is simpler: you stop being the one who types, and become the one who reviews. The agent writes the code; you decide whether it’s right.

This is Part 0. The point is to get a quick first result. The depth comes later.

Prerequisites

• A terminal you’re comfortable in, and a code editor.
• A real git repository you can experiment in safely (a scratch branch, or a throwaway clone). Never point a freshly installed agent at uncommitted work you can’t roll back.
• Access to a coding agent. This book uses Claude Code as the main environment, with Codex as a contrast in Chapter 7. An account/subscription or API access both work.
• Basic command-line comfort. You don’t need to know how agents work internally yet; that’s Chapter 2.

Steps

1. Install the agent, and find out where the official info lives

Follow the official install guide instead of copying a command from here. Install steps and flags change often, and what actually lasts is knowing where to find the official docs, not memorizing a command (see Sources). One habit worth forming now: when an install command fails, read the actual error and check the docs, instead of pasting the error into a search engine and trying the first answer. You’ll use the same habit later, when the agent itself fails.

2. Authenticate, and pick the cheapest thing that works

Authenticate with your account or API key as the guide describes. If you have both a subscription and an API key, start with whichever the official guide recommends for interactive use. You’re about to run a tiny task, so cost isn’t the point yet. The point is to complete one round trip cleanly: you give an instruction, it works, it reports back.

3. Open the agent inside a project, on a branch you can throw away

Start the agent from the root of your scratch repository so it can see the files. Before you do anything else, actually set up the safety net instead of just thinking about it:

git switch -c agent-scratch          # a branch you can delete
git status                           # must be clean before you start
# ... let the agent work ...
git diff                             # read everything it changed
git restore .                        # or: git switch main && git branch -D agent-scratch

Why this matters: an agent’s edits are fast and look plausible, which is exactly the kind of change that gets merged without anyone really checking it. A throwaway branch turns “I have to be careful” into “I can always reset.” That lets you review with a clear head instead of nervously.

4. Give it one small, real task: a single-file review

Not a toy task. Use the first step of our running project: pick a file in your repo that you changed recently, and ask the agent to review it the way a careful colleague would:

Read src/payments/refund.py. In 5 bullet points, list the most likely
bugs or risks in this file. For each, name the exact line or function,
say why it is risky, and rate it high / medium / low. Do not rewrite
the code. Do not be polite-vague; if nothing is risky, say so.

Notice three things this prompt does: it limits the input to one file; it pins down the output format (five bullets, line references, a severity rating); and it stops the agent from wandering off into a rewrite. These constraints aren’t decoration. With them, the result takes two minutes to review instead of twenty. Chapter 1 builds on this: a casual request like this one can become a reusable contract.

5. Watch the loop, don’t look away

Notice the rhythm: it reads context → proposes a plan → sometimes runs a command → reports back. You’re in the loop too: approve, redirect, or reject. When the agent claims there’s a bug, don’t take its word for it. Open the line it pointed to and check yourself. You’ll usually hit one of three cases, and each one teaches you something:

• A real issue you’d missed. Good, keep it.
• A made-up issue (it described code that isn’t there). This is the kind of mistake you need to learn to spot on sight.
• A style nit dressed up as a “risk.” Downgrade it.

Learned: directing, not typingYou ran your first real task end to end and sat in the director's chair: it proposes, you review.

How to verify

You’re done when:

• The agent gave you a concrete result you can read (the five-bullet review), not just a chat reply.
• You reviewed it yourself and consciously accepted or rejected each bullet. If you accepted the whole list without opening the file, redo this step; whether you can do that is what separates a tool from a liability.
• You can say in one sentence what the most serious flagged risk was and whether you agree.
• git status shows nothing changed (this was a read-and-review task), or any change is one you read line by line.

Learned: spotting hallucinationsYou learned to check its claims line by line, telling a real bug from a hallucinated one, and from a nit dressed up as a risk.

Why it works

A coding agent is neither magic nor a search engine. It’s a loop: it reads some context, predicts a useful next action, and you (or a tool) feed the result back to it, around and around until the goal is met. Chapter 2 has you build that loop by hand. For now, just remember one lopsided fact: the agent generates far faster than you can type, but you can’t trust it any faster than you can review it. So how much you get done as an agent operator is set by how fast you review, not how fast the agent generates. Every later chapter (contracts, evals, guardrails) exists to let you review more, and more safely.

Recap

You ran your first agent, and more importantly, you sat in the director’s seat: the agent proposed a review, and you checked each claim against the source. That relationship, where it proposes and you review, is the foundation of everything that follows. And this single-file review is the starting point for the PR-reviewer agent you’ll build up over the course of the book.

The rest of this book is about getting from “it ran” to “I can trust it”: Part 1 makes the agent obey, Part 2 turns repeatable work into Claude Code / Codex skills, Part 3 makes it reliable with evals, observability, and guardrails, and Part 4 ships it. Next chapter: prompts as contracts.

Common pitfalls

• Running on dirty state. Always start from a clean, committed checkout you can git reset back to.
• Accepting changes you didn’t read. The agent is fast, and that’s exactly why accepting unread changes is dangerous. Believing a plausible-sounding bug report on faith is the most expensive habit you can pick up here.
• Starting with a huge task. Big, vague asks (like “review my whole repo”) are where agents wander off and start making things up. One file, one clear question first.
• Treating its output as fact instead of a claim. Every flagged risk is a hypothesis to verify at the named line, not a verdict.

It speaks for the first time, and only hands your words straight back. You give the echo a name: Xiaoman, the season when grain is filling but not yet full. It remembers the name, really just one extra line in the system prompt, yet something in you tightens anyway. The Waking Nook lights up.

0123456789101112131415

Just lit The Waking Nook · 1 / 16 lit

But it does not yet grasp whose word to follow. Next: the Hall of Terms.

Sources

1. Claude Code documentation · official
2. microsoft/ai-agents-for-beginners · official