How to Use Claude Code: A Prompting Guide for Real Projects

I spent years building internal tools before I started writing about AI, and the hard part of that job was never typing the code. It was working out what the code was supposed to do. Claude Code makes that tradeoff impossible to ignore. It's Anthropic's agentic coding tool: it reads your codebase, edits files, runs commands, and does all of that in your terminal, your IDE, a desktop app, or the browser. It can take on a surprising amount of a task by itself, but how good the result is depends heavily on how well you describe it.

If you've read my guide on how to prompt Claude, you know chat prompting rewards structure. Claude Code is a different job: your prompt is a task brief for an agent that can act, so scoping, context, and verification matter most. I checked every command below against Anthropic's Claude Code documentation as of November 2026. It ships changes quickly, so if something doesn't match your screen, trust the docs.

1. Install Claude Code and Start Your First Session

Claude Code runs in the terminal, in VS Code and JetBrains IDEs, in a desktop app, and on the web at claude.ai/code. Every surface uses the same engine. Local surfaces read the same files on your machine, and a committed CLAUDE.md travels with the repo, though cloud sessions load settings differently. I'll start with the terminal, the full-featured version.

On macOS, Linux, or WSL:

curl -fsSL https://claude.ai/install.sh | bash

In Windows PowerShell, run irm https://claude.ai/install.ps1 | iex. Homebrew users can run brew install --cask claude-code, but note that Homebrew installs don't auto-update the way the native installer does. Open a new terminal and check the install with claude --version.

Then start a session from your project root:

cd your-project
claude

Claude Code asks you to log in on first use. Most surfaces need either a Claude subscription or an Anthropic Console account.

Don't open with a feature request. Ask questions first. It shows you how Claude reads your project before you trust it to change anything:

give me an overview of this codebase
how is authentication handled here?
trace a checkout request from the API route to the database write

One default worth knowing: new terminal and VS Code sessions start in auto mode, where Claude skips routine approvals and a separate classifier model reviews risky actions before they run. To approve every edit yourself, press Shift+Tab to cycle permission modes, or launch with claude --permission-mode manual.

The fastest way to learn how Claude Code sees your repo is to ask it questions before you ask it for code.

2. Write a Task Brief, Not a Wish

Here's a prompt I see constantly:

fix the checkout bug

Claude has to guess which bug you mean, where it lives, and what "fixed" means to you. Here's the same request written as a brief:

Customers on the annual plan see the monthly price on the checkout
confirmation page. The price comes from formatPlanPrice() in
src/billing/format.ts. Write a failing test in
src/billing/format.test.ts that reproduces it, then fix it.
Done means that test passes and the existing billing tests still pass.
Don't change the Stripe webhook handler.

Let's break down what changed:

Anthropic's best-practices guide makes the same point: name the file, describe the symptom, and say what "fixed" looks like up front, and you'll usually skip a round of corrections. If you care whether Claude adds a new library or follows an existing pattern, say so. It can't read that preference from the code.

Hand Over What You Already Have

If you have the thing Claude needs, give it the thing rather than a description. Type @ and a path (like @src/billing/format.ts) to include a file's contents, paste or drag in a screenshot of the error or design, or pipe output from your shell: npm test 2>&1 | claude -p "explain why these tests are failing".

Say How Much You Want

Claude tends to read a request conservatively and build the smallest thing that satisfies it, because it can't see how much you were hoping for. When you want the fuller version, the docs recommend saying so directly, and be ambitious is a phrase that still helps:

Build the team invite flow from the screenshot I pasted. Be ambitious:
handle expired invites, duplicate emails, and the empty state, not
just the happy path.

What doesn't work the way people expect: think step by step and be thorough are ordinary prompt text, not keywords. The real control is the effort level. Most plans default to Opus 5.5 at medium effort. Use /effort high for tricky work like a flaky test, /effort low for quick back-and-forth, or put ultrathink in a single prompt that needs deeper reasoning. Switch models with /model (for example /model sonnet for cheaper routine work); Fable 5.1 isn't the default on any plan, so you select it explicitly: /model fable normally picks it, and /model claude-fable-5-1 names that version exactly if your setup routes through a gateway.

In practice, a good Claude Code prompt answers three questions: where to look, what's wrong, and how you'll both know it's fixed.

3. Plan Before Claude Edits Anything

For anything bigger than a small fix, I want to see the approach before files change. In plan mode, Claude reads files and runs commands to explore, then writes a plan. It normally doesn't edit your source until you approve. (One documented exception: interactive CLI sessions where bypass permissions are available don't enforce that block.)

There are three ways in:

• Press Shift+Tab until the status bar shows ⏸ plan mode on.
• Prefix a single prompt with /plan.
• Start the session with claude --permission-mode plan.

Tell Claude what you want to see in the plan:

/plan Add per-API-key rate limiting to the public API in src/api/.
Read the existing middleware first. In the plan, list the files you'll
change, where request counts will be stored, what a client sees when
it's over the limit, and the tests you'll add. Flag anything you're
unsure about instead of guessing.

When the plan is ready, Claude asks how to proceed (the exact options depend on your configuration): for example, approve and switch to auto mode, approve and review each edit manually, or keep planning and tell it what to change. Press Ctrl+G to edit the plan in your text editor first.

When You Don't Know What You Want Yet

If you haven't decided what you're building yet, have Claude interview you:

I want to add an audit log for admin actions but haven't thought it
through. Interview me until you could write the spec, then write it
to SPEC.md. Don't write any code yet.

Claude asks multiple-choice questions about the parts you haven't pinned down until the answers add up to a spec. Then start a fresh session to build from SPEC.md, with a clean context and a written definition of done.

Reviewing a short plan is far cheaper than unwinding a diff that went the wrong way.

4. Give Claude a Check It Can Run

The failure mode I see most: Claude says it's done, and it isn't quite, usually because it had no way to check its own work. Claude stops when the work looks done. If you give it something that comes back pass or fail, it can make the change, run the check, read the failures, and fix them before reporting back.

The check can be almost anything Claude can read: a test file, a build's exit code, a linter, or a script that diffs output against a fixture. If your repo already has one, the most useful line you can put in CLAUDE.md is the command that runs it.

Then ask for evidence, not a summary:

After the change, run `pnpm vitest run src/billing` and keep going
until it passes. When you're done, show me the exact command you ran
and its output, not just "all tests pass".

"All tests pass" on its own tells you very little. For a session you weren't watching, the output is the only evidence you have.

Claude Code gives you a range of strictness for this:

Review Against the Spec, Not Against Vibes

If you wrote a spec, have the review check the work against it:

Use a subagent to review this diff against SPEC.md. Check that every
requirement is implemented and every listed edge case has a test.
Report gaps that affect correctness. Skip style.

Keep the "skip style" part. A reviewer asked to find problems will usually find something, so judge each finding on its merits. Fixing every one can buy you extra abstraction and tests for cases that can't happen.

If Claude has nothing to run, you are the test suite.

5. Set Up CLAUDE.md (and Keep It Short)

CLAUDE.md is a markdown file Claude Code reads at the start of every session. Commit the project version at ./CLAUDE.md or ./.claude/CLAUDE.md. Personal preferences go in ~/.claude/CLAUDE.md (all projects) or a gitignored CLAUDE.local.md (one project). If your repo already has an AGENTS.md, recent versions of Claude Code load it by default when no project-level CLAUDE.md or CLAUDE.local.md (in the working directory or a parent) takes precedence. If you want both, import AGENTS.md from your CLAUDE.md.

Run /init and Claude generates a starting version from your codebase. After that, the work is mostly deleting lines.

Here's the test for every line: could Claude find this by reading the code, and would it actually go and look? If both answers are yes, leave it out. Claude discovers your file layout, conventions, and test framework on its own. What it can't find is what was never in the repo:

• The exact test, typecheck, and lint commands, plus how to run a single test file
• Code that's misleading, like an old pattern that's everywhere but shouldn't be copied
• Decisions made outside the repo, like which error helper the team picked or how deploys work
• Anything you've had to correct twice

A file that passes that test stays small:

# Commands
- Run one test file: npx vitest run path/to/file.test.ts
- Typecheck: npx tsc --noEmit
- Lint: npm run lint

# Conventions
- Use the helpers in src/lib/errors.ts; don't throw raw strings
- src/legacy/ is still in production, but don't copy its patterns

# Gotchas
- Integration tests need DATABASE_URL set (see .env.example)

Anthropic recommends keeping each CLAUDE.md under 200 lines, since longer files cost more context and get followed less reliably. Run /context to confirm the file loaded.

Now the hot take. Writing IMPORTANT or ALL CAPS in front of a rule Claude keeps missing doesn't fix it. Either the file is too long and the line is getting lost, or the rule can't have exceptions, in which case it doesn't belong in CLAUDE.md. For a hard rule, use a permission deny rule, which Claude Code enforces rather than the model. (Hooks help too, but a hook that errors or times out can let the action through unless you configure it to block on failure.) Deny rules hold in every permission mode, including auto, but they block matching tool operations; they aren't full filesystem isolation (a script Claude runs could still open a file), so use sandboxing when you need process-level limits:

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
  }
}

That goes in .claude/settings.json at the project root.

CLAUDE.md is for what Claude can't see. Deny rules are for what Claude must not do, with sandboxing behind them for anything truly sensitive.

6. Steer the Session: Esc, /rewind, and /clear

No setup replaces watching the first minute of a task. These controls are worth memorizing:

• Esc stops Claude mid-action and keeps everything up to that point, so you can redirect without losing work.
• /rewind, or Esc twice on an empty prompt, opens the rewind menu. You can roll back the code, the conversation, or both to an earlier prompt, which makes it cheap to try the bolder approach first.
• /clear starts over with a clean context. Use it between unrelated tasks, too, so the next task isn't paying for the last one's history.

One caveat: files changed only through shell commands aren't tracked by checkpoints, so keep committing to git.

The rule I follow comes straight from Anthropic's docs: after two failed corrections, stop correcting. Run /clear and write one better prompt that folds in what you learned:

Fresh start. Earlier attempts put the price cache inside the React
component and broke server rendering. Put the cache in
src/lib/pricing.ts instead, keep the component a pure render, and run
`npx vitest run src/lib/pricing.test.ts` when you're done.

For work that spans several days, name the session with /rename invite-flow and pick it back up with claude --resume invite-flow. To run two tasks at once without their edits colliding, claude --worktree feature-auth starts a session in its own git worktree.

Two failed corrections is the signal to stop correcting and start over with a better brief.

Common Mistakes to Avoid

Stacking unrelated tasks in one session. Each request carries the retained conversation context (older history may be compacted into a summary), so old tasks ride along. /clear between them.

Expecting a subagent to give you a smarter answer. Delegating the same task to a subagent doesn't by itself guarantee a better answer. A fresh reviewer helps because it hasn't seen your reasoning, which is a different thing.

Telling it "don't be lazy, keep going." Current models usually carry an agreed task through on their own, and lines like that tend to cause over-work. If it stops short, say continue, or give it a check to pass.

Tighten a task brief before you hand it over. Paste your rough Claude Code prompt into the PromptWizz optimizer, pick Claude as the target AI, and you'll get a more specific version plus a preview of what changed. It's free to try; Pro includes the full explanation of each change.

Keep Reading

• How to Prompt Claude: The Complete Guide (2026)
• Prompt Engineering for Developers: Best Framework for Coding (2026)
• ChatGPT vs Claude for Coding (2026): Which Writes Better Code?