Short answer
Installing Claude Code is one command, and you can be running it inside a real
project two minutes later. The setup that actually determines whether it is
useful is three things: a file where your project’s decisions live, some way for
the agent to observe results instead of reporting them, and a deliberate point
where a human still looks. This post covers the install, each of those, and the
week of production debugging that taught me the middle one.
What is Claude Code?
Claude Code is an agent that works inside your actual project. It reads your
files, edits them, runs your commands, and reads the output — rather than
answering questions about code you paste into a chat window.
That difference is the whole thing. A chat assistant reasons about a snippet you
chose to show it. An agent reasons about the repository, the failing command, and
the response your server actually returned. Almost everything below is a
consequence of that distinction.
For grounding: this site’s publishing pipeline was built with it, and every post
here was written and shipped through that pipeline. The examples are all from
that work.
How do you install Claude Code?
On macOS, Linux, or WSL:
curl -fsSL https://claude.ai/install.sh | bash
On Windows PowerShell:
irm https://claude.ai/install.ps1 | iex
There are package-manager routes as well — brew install --cask claude-code on
macOS, winget install Anthropic.ClaudeCode on Windows. Then change into a
project directory and run:
claude
It prompts you to log in on first run. Most surfaces expect either a Claude
subscription or an Anthropic Console account.
That is genuinely the entire installation. If you were looking for the part that
is hard, it is not here.
Which surface should you use?
Claude Code runs in the terminal, in VS Code, in JetBrains IDEs, in a desktop
app, in the browser at claude.ai/code, and on mobile. Your CLAUDE.md,
settings, and MCP servers follow you across all of them, so this is a preference
rather than a commitment.
Two things worth knowing before you pick.
The terminal is the honest one. Everything the agent does is a command you
could have typed, and you watch it happen. The IDE integrations are more
comfortable, but comfort in this context means a layer between you and what is
being run. Starting in the terminal for the first week is worth it for the same
reason people learn git on the command line first.
On Windows, know which shell you are in. This project runs on Windows 11, and
Claude Code can drive both PowerShell and a POSIX shell there. Which one you get
is not arbitrary: with Git for Windows installed it can use the Bash tool, and
without it PowerShell becomes the shell tool instead. They are not interchangeable
and the failures are quiet — $VAR versus $env:VAR, /dev/null versus $null,
&& chaining that does not exist in Windows PowerShell 5.1 and raises a parser
error instead of running. A command that would have worked in one shell fails in
the other for reasons that have nothing to do with the task, and you spend the
next ten minutes debugging the wrong layer. Knowing which shell is the default —
and writing that down where the agent will read it — removed an entire category
of noise for me.
That second point is the first hint of the pattern this whole post is about: the
useful configuration is not settings, it is context.
Your first session: give it the failing thing, not a description of it
The most useful hour of my first week went like this.
A WordPress admin page was dying with a generic critical-error notice. No log
output, no error text, nothing to paste. My instinct was to describe the symptom
— “this page returns a 500 after I install that plugin” — and let the model
theorize.
That produced plausible theories. The first one was wrong, and I could not tell
it was wrong, because I still had no error.
The turn came when I stopped describing and started capturing. Twenty lines of
PHP that stored the last fatal error and an endpoint to read it back, and
suddenly there was a real stack trace to work from. The fix was obvious within a
minute of having it. The full write-up of that debugging session is
here —
the interesting part is that the missing thing was never the diagnosis, it was
the path from the failure to somewhere I could see it.
The general form:
An agent reasoning about your description is guessing. An agent reading your
actual output is not.
This applies far past error messages. A failing test’s output beats “the test
fails.” A curl -i beats “the endpoint seems slow.” The work is in producing the
observable, and that work is worth doing before you start the conversation.
So for your first real session: pick something that is actually broken, and spend
the first ten minutes making the breakage visible rather than describing it. A
toy task teaches you nothing about the failure modes, and a described failure
teaches the agent nothing it can check.
What is CLAUDE.md, and what belongs in it?
CLAUDE.md is a markdown file that Claude Code reads at the start of every
session. Put it in your project root for project rules, or at user level for
rules that should apply everywhere you work.
The obvious use is coding standards. The more valuable use took me longer to
find: it is where your project’s already-made decisions live.
The line that earned its place in mine is not a style rule. It says: always
resolve a repository’s owner and name from git remote -v rather than inferring
it from the directory name or from a merge commit message. It exists because
inferring it once produced a plausible, completely wrong URL, and then a
correction cycle to undo it. One command up front, an entire class of error gone.
Notice where that rule lives — at user level, not in a project file. It is not
about this project; it is about a mistake that is available in every project. The
split is worth thinking about for thirty seconds when you add a line: would this
be true in a different repository? If yes, it belongs at user level, and you
write it once instead of five times.
The test I now apply to any candidate line:
- Did getting this wrong once cost real time?
- Is the correct answer not derivable from the code itself?
Both yes, it goes in the file. Anything else is noise, and noise is not free — it
dilutes the lines that matter. A CLAUDE.md full of generic best practices is
worse than an empty one.
What Claude Code remembers on its own
Separately from the file you write, Claude Code accumulates its own memory across
sessions — build commands, debugging findings, project facts it worked out once
and would otherwise re-derive.
Both are worth having, and the division is clean: the file is for what you
decided, the memory is for what it learned.
One of the entries in mine reads, in effect: the blog pipeline stops at draft on
purpose — never auto-publish. That is not a coding standard and not a fact about
the code. It is a boundary, written down after the reasoning behind it was worked
out once, so that no future session has to be talked out of “helpfully” finishing
the job. Which brings us to the last section — but two things need to happen
first.
What is MCP, and when do you need it?
You do not need MCP to start. Claude Code already reads your files and runs your
commands.
MCP — the Model Context Protocol — is how you extend it to things that are
neither. You connect a server that exposes some system as tools the agent can
call directly, and from then on that system is as reachable as the filesystem.
The concrete example is this site. Every post here starts as a note in an
Obsidian vault, and the vault is connected over MCP. So the drafting, the
publishing plan, the backlog of episodes worth writing up, and the post files
themselves are all things the agent reads and edits in place. There is no step
where I copy a draft out of one tool and paste it into another — which matters
more than it sounds like, because the manual step in the middle of an otherwise
automated path is exactly what killed the previous version of this project.
The judgment call is the same one as with CLAUDE.md: connect a server when the
agent genuinely needs to reach something, not because it is available. Every
connected server is more surface, and surface you are not using is surface you
are not watching. This is worth its own post and will get one.
How do you make an agent verify its own work?
This is the one I would keep if I could only keep one, and it is the through-line
of everything else on this site.
A model that just edited a file will tell you it edited the file. That is true
and nearly useless. The question you actually have is whether the effect you
wanted happened — and the only way to answer it is to look from somewhere the
change cannot vouch for itself.
Concretely, in this project, that meant:
| Claim | What “from outside” looked like |
|---|---|
| The post uploaded | Fetch it back from the REST API and read the stored fields |
| The image got resized | Ask the API which derived sizes exist, not whether the upload succeeded |
| The endpoint is closed | Request it logged out, from a separate process |
| The cache is on | Request the same URL twice and look for the cache marker in the response |
Every one of those checks found something at least once. The site was silently
generating no thumbnails at
all
while every upload returned success. Two plugins sat in the plugin list marked
active while doing absolutely
nothing.
There were enough of these that they became their own
post:
in practice, the absence of an error is not evidence of success.
None of that is a criticism of the agent. Each system reported honestly on the
thing it controlled — the upload did succeed, the plugin was active — and I
read those reports as answers to a question nobody had asked. An agent inherits
that problem from you and executes it faster.
The habit in one line: before accepting “done,” ask what would be observably
different if it were true — then go observe that. It costs one extra command,
and it is the entire difference between an agent that ships and an agent that
produces confident-sounding text.
Subagents, hooks, and the parts I have not used yet
Claude Code has more than what is above. Subagents let you spawn several agents
that work on different parts of a task at once, each in its own context, with a
lead agent coordinating and merging the results. Hooks run your own shell
commands before or after the agent’s actions — the mechanism you would use to
make something happen automatically every time, rather than asking for it every
time. There are also skills, for packaging a repeatable workflow into a command,
and an SDK for building agents of your own.
I have not used them in anger yet, so I am not going to write four confident
paragraphs about them. They are the next thing I am turning on here, and when
there is something real to report — including whatever does not work — that will
be its own post.
I mention them for one reason: if you are evaluating the tool, the ceiling is
higher than this post. Everything above is what I needed to ship seven posts and
a pipeline, which turned out to be less machinery than I expected.
Automate the mechanical steps; keep the judgment step
This one is a design principle rather than a workflow tip, and it is the reason
the pipeline exists at all.
The previous version of this project died because publishing required opening an
image editor to make a header image. Not hard — just manual, sitting in the
middle of an otherwise automated path. Eight drafts got written. Zero shipped.
So the pipeline generates the image in code, uploads it, attaches the metadata,
builds the schema, and then stops at draft on purpose. The last step is a
person reading the thing. I wrote up how that pipeline is put
together
in the first post here.
That stop is not a limitation I have not gotten around to removing. It is the
point. Automate what is mechanical precisely so that the only remaining step is
the one that needs judgment — and then actually keep that step.
If you take one architectural idea from this post: decide deliberately where your
human gate is, then remove every other manual step around it. A gate you chose is
a quality control. A manual step you merely tolerated is a bottleneck, and it
will eventually stop you.
Where it cost me time
An honest getting-started post needs this section.
The worst hour of that week was a broken favicon. The site was serving a
512-pixel image into a 32-pixel slot, and fixing it took five attempts —
re-selecting the image did nothing, one admin button silently destroyed the
original, restoring it undid the progress, and the thing that finally worked was
uploading the file again from scratch.
Claude Code did not flail there. I did. It kept correctly reporting what each
attempt had and had not changed; I kept reaching for the next plausible button.
The loop only closed when we stopped clicking and started checking the actual
generated file sizes through the API after every attempt. That is the
verification habit above, learned the slow way, on the day I had not learned it
yet.
Two smaller frictions worth naming:
- It will follow a wrong plan very quickly. Speed is not judgment. On
anything with real consequences I now ask for the plan before the edit, which
costs a minute and has already caught two bad approaches. - Long autonomous runs need a stated goal, not a running conversation. The
sessions that produced the most were the ones where I specified the whole task
up front instead of assembling it turn by turn. Assembling it turn by turn
produces something that satisfies each turn and no overall intent.
What I would tell myself on day one
- Install it, then immediately give it something real. A toy task teaches you
nothing about the failure modes. - Before your first serious debugging session, find the observable. Do not start
by describing. - Start
CLAUDE.mdon day one, but only add lines that already cost you
something. - Decide where the human gate is before you automate anything else.
FAQ
How do I install Claude Code?
One command. On macOS, Linux, or WSL run the install script from claude.ai; on
Windows use the PowerShell equivalent, or install through Homebrew or WinGet.
Then run claude inside a project directory and log in when prompted. Most
surfaces need a Claude subscription or an Anthropic Console account.
What is CLAUDE.md and do I need one?
It is a markdown file Claude Code reads at the start of every session, either in
your project root or at user level for rules that apply everywhere. You do not
need one to begin, but you will want one by the second day. Put the decisions
your project has already made in it — the things you would otherwise re-explain
every session.
Do you need MCP to use Claude Code?
No. Claude Code already reads your files and runs your commands without it. MCP
is how you extend it to things that are neither — a notes vault, a database, an
issue tracker — by connecting a server that exposes those as tools it can call
directly.
Can Claude Code verify its own work?
It can, if you give it a way to observe the result rather than the report. A
command whose output it can read, an API it can query, a file it can check.
Without an observable, it is reasoning about what should have happened rather
than what did.
Wrapping up
The install is the least interesting part, which is why every other
getting-started post ends where this one starts.
What determines whether an agent is useful to you is how much of your work it can
actually see. Give it your real errors instead of your descriptions of them.
Make it look from outside before it accepts its own success. Write down the
decisions it would otherwise have to re-derive. Then be deliberate about the one
step you keep for yourself.
That loop is the method behind everything on this site — the pipeline, the posts,
and the run of production failures that all reported success while failing.
Including the parts where I was the one who got it wrong.
Primary sources:
Claude Code overview
· Quickstart
· CLAUDE.md and memory
· Hooks