Claude Code, plainly explained.

01

Introduction

Claude Code is Anthropic's command-line coding agent. You talk to it in plain English; it reads your repository, proposes a plan, edits files, runs commands, and iterates until the task is done.

Unlike an autocomplete that lives inside your editor, Claude Code operates at the project level. It can touch many files at once, execute shell commands, run tests, and coordinate multi-step work — the kind of thing that used to take an afternoon of tab-juggling.

The mental model worth holding: a fast, tireless colleague who has just been handed the keys to your repo. Specific instructions and a willingness to review diffs will take you a long way.

02

Installation

Claude Code ships as an npm package. You'll need Node.js 18+ and either a Claude subscription or an Anthropic API key.

Install the CLI

npm install -g @anthropic-ai/claude-code

Run it in a project

cd ~/projects/my-app
claude

On first launch Claude Code opens a browser tab so you can sign in. After that, every time you run claude from a repo root, a new session starts with that project in context.

03

Your first run

The first session in a new project should be exploratory — let Claude read the code before it touches it.

Three things to notice above:

• Claude summarized first instead of editing.
• It named concrete files, not vague areas.
• It left the repo untouched — nothing to revert.

04

How to prompt

Claude Code rewards specificity. The sharpest prompts name a goal, a constraint, and a stopping condition.

A prompting checklist

1. What is the desired outcome?
2. Which files or modules are in scope?
3. Which files must not be touched?
4. How will we know it's done — a test, a behavior, a benchmark?
5. Should Claude plan first, or just go?

Patterns that work

> Don't change anything yet. Read the payment flow and
  propose a plan to add partial refunds.

> Write a failing test that captures the bug, then make it
  pass. Run the whole suite before you finish.

> Rename getUser() to fetchUser() repo-wide. Update imports
  and docstrings only. Don't change behavior.

05

Slash commands

Inside a session, commands that start with / control the agent rather than ask it to do work. These are the ones worth learning.

/help

List every available command with a short description.

/init

Generate a CLAUDE.md that teaches future sessions about your project.

/clear

Reset the conversation — useful between unrelated tasks.

/compact

Summarize the conversation so far to free up context window space.

/review

Ask Claude to code-review its own changes before you commit.

/model

Switch models — a faster one for tight loops, a stronger one for planning.

/cost

Show tokens (and dollars) spent in the current session.

/exit

Leave the session. History is saved so you can resume later.

Keyboard shortcuts

06

Workflows

Five tasks where Claude Code consistently earns its keep. Paste the prompts verbatim; edit them to taste.

> Give me a high-level tour of this repo. What are the
  main entry points, data flows, and where would I start
  to fix a login bug? Do not edit anything.

> Add a rate limiter to /api/login — 5 attempts per 10
  minutes per IP. Write failing tests first, then make
  them pass. Don't touch unrelated files.

> tests/checkout.spec.ts fails with:
  "Cannot read properties of undefined (reading 'total')".
  Find the root cause. Explain the bug, then fix it.

> Rename getUser() to fetchUser() across the repo. Update
  all imports and docstrings. Run tests and fix anything
  that breaks.

> Stage the changes, write a Conventional Commits message,
  and draft a PR description with Summary, Risks, and
  Test Plan sections.

07

Project memory

A CLAUDE.md file in your repo root is loaded automatically on every session. Put conventions and gotchas there so you don't have to repeat yourself.

Think of it as an onboarding doc for the agent. Keep it short, keep it truthful, and update it when patterns change. Run /init once and edit the result.

# My App — agent notes

## Stack
- TypeScript, Next.js 15, Postgres via Prisma.
- Tests live in *.spec.ts next to the file.

## Conventions
- Never import from src/internal/* in src/public/*.
- Prefer pure functions; avoid class-based services.
- Dates: always UTC at the boundary, local for display.

## Before finishing a task
- Run `pnpm test` and `pnpm lint`.
- Update CHANGELOG.md under ## Unreleased.

08

Habits & pitfalls

Ten habits separating people who use Claude Code once from people who reach for it every day.

1. Plan, then code.

   Ask for a plan before you allow edits on anything non-trivial.

2. Small diffs win.

   Break large tasks into commits the size of a code review.

3. Feed it failures.

   Paste stack traces, flaky output, and logs verbatim. Don't paraphrase errors.

4. Clear between tasks.

   Use /clear so old context doesn't color new work.

5. Keep a CLAUDE.md.

   One page of rules beats repeating yourself ten times a day.

6. Pin the files that matter.

   Mention them by name in the prompt to anchor attention.

7. Verify with tests.

   “Make the tests pass” is a better finish line than “make it work”.

8. Guard the blast radius.

   Use a feature branch; let Claude run loose inside it.

9. Ask for reasoning.

   “Explain why” catches subtle mistakes before you merge them.

10. Reward specificity.

    Vague prompts produce vague code. Precise prompts produce precise code.