Claude Code Prompting Guide (2026)

Prompting Claude Code well looks less like chatting and more like writing a work order. Claude Code is Anthropic's terminal-native coding agent — it operates inside your working directory, runs shell commands, edits files, and iterates through tasks — so the prompt needs scope, context, stop conditions, and verification up front. The payoff: fewer loops, fewer wrong-file edits, and fewer "I think I fixed it" claims that turn out to be wishful thinking. This guide covers how Claude Code differs from chat, how to use CLAUDE.md files, slash commands, hooks, MCP servers, and sub-agents.

What Claude Code Is

Claude Code is Anthropic's CLI-based coding agent. You invoke it from a terminal inside a repo, and it operates directly on files in that working directory. Unlike a chat window, it has a set of tools it uses without asking each time: Bash to run shell commands, Read to open files, Edit and Write to modify or create them, and Grep and Glob to search. It also has a permissions model — you can allowlist commands, require confirmation for risky ones, and block destructive operations entirely.

Because the agent can run your tests, typecheck your code, and inspect the repo, the best prompts offload verification to the agent itself. You are not asking it to guess whether something works — you are telling it which commands prove that it works.

For broader context, see the pillar: The Complete Guide to Prompting AI Coding Agents. For the category definition, see agentic AI.

How Prompting Claude Code Differs From ChatGPT or Claude.ai Chat

A chat model returns a good next message. Claude Code returns a sequence of file edits, shell runs, and observations that converges on a goal.

A chat-style prompt like "Refactor this to be cleaner" leaves Claude Code without a target — it will touch things you did not want touched and declare victory without running the tests. The same request as a work order — goal, scope, files, acceptance criteria, stop condition — converges quickly and produces a reviewable diff. See spec-driven AI coding for the discipline.

CLAUDE.md Files — The Persistent Project Brief

CLAUDE.md is the file Claude Code looks for to learn a project's ground rules. Instead of repeating the same context every prompt, you write it once and the agent reads it when you start a session.

Three layers worth keeping straight:

• Global (~/.claude/CLAUDE.md) — personal preferences across every project. Coding style, git workflow, commit format.
• Project root (/your-repo/CLAUDE.md) — facts about this repo. Tech stack, scripts, conventions, directories that are off limits.
• Subdirectory (/your-repo/some-module/CLAUDE.md) — local context for a module with different conventions (a legacy folder, a generated client).

Claude Code reads the most specific CLAUDE.md relevant to the files in play, so subdirectory files extend the project root for work inside that subdirectory.

A plausible project CLAUDE.md:

# Project: Acme Billing Service

## Stack
- TypeScript (strict), Node 20, Next.js 15 (App Router)
- PostgreSQL via Prisma
- Tests: Vitest (`pnpm test`). Typecheck: `pnpm typecheck`. Lint: `pnpm lint`.

## Conventions
- Functional components only. Immutable data — no in-place mutation.
- Files under ~400 lines; functions under ~50 lines.
- Validate external input with Zod at system boundaries.

## Directory rules
- `src/app/` — routes. Prefer server components.
- `src/lib/` — pure utilities. No network calls.
- `src/server/` — server-only. Never import here from client components.
- `prisma/migrations/` — do not hand-edit; use `pnpm prisma migrate dev`.

## Verification
Before declaring a task done, run `pnpm typecheck && pnpm test && pnpm lint`
and paste each output in your summary.

## Out of scope by default
- Do not edit `prisma/schema.prisma` without being asked.
- Do not install new dependencies without confirming.
- Do not commit to `main` directly.

This is a template, not an "official" one — shape depends on your repo. Every line removes a decision the agent would otherwise guess at. For more on context files vs. the prompt itself, see the tool use glossary entry.

Slash Commands — Reusable Scoped Workflows

Claude Code supports slash commands as a way to save and re-run scoped workflows. Instead of typing "find untested functions in src/lib, add tests, stop when coverage is above 80%" each time, you define it once and invoke it by name.

Slash commands are useful for anything you repeat: the pre-commit checklist, scaffolding a new route, your team's code review prompt, generating a changelog entry. They keep the agent's surface area small and predictable, which is what you want in a tool that can edit your code. They pair well with CLAUDE.md: the CLAUDE.md tells the agent how the project works, slash commands package specific workflows on top.

Hooks — Scripts at Tool-Execution Events

Hooks are an advanced feature that let you run scripts at specific tool-execution events. The generally-understood event categories include PreToolUse (before a tool runs), PostToolUse (after a tool runs), and Stop (when the session ends). The idea is the same as a git hook: intercept a known event and run your own logic.

Typical uses: auto-formatting a file after Claude edits it, running a linter or typecheck after any write, blocking commits that include .env files. Hooks are configured at the settings level, so they apply to every session consistently. The exact event names and configuration shape evolve, so check Anthropic's current Claude Code docs before configuring hooks in production — the principle is stable, the specifics move.

MCP Servers — Extending Tool Access

Claude Code integrates with MCP (Model Context Protocol) servers, an open standard for exposing tools and context sources to AI agents. An MCP server can give Claude Code access to a database, an internal API, a docs system, a ticket tracker, or anything else you wire up. MCP is a plug, not a feature: you run a server, point Claude Code at it, and its tools become available alongside the built-in ones. Which servers exist is a fast-moving ecosystem — treat any list as a snapshot and check the MCP registry or the server's own docs.

Sub-Agent Delegation

Claude Code can dispatch sub-agents — isolated runs that work on a scoped task and return their result. Sub-agents are useful when:

• The work is parallelizable. Reviewing three independent files for the same concern? Dispatch three sub-agents.
• You want context isolation. A narrow brief does not pollute the main session with intermediate reads.
• Roles help. One plans, another implements, a third reviews — the pattern covered in the multi-agent prompting guide.

Sub-agents add coordination overhead, so skip them on simple tasks. If the main session would otherwise hold a lot of unrelated context, or the work splits into independent streams, a sub-agent pays for itself.

A Work-Order Prompt You Can Copy

GOAL
  Add a retry loop to `request()` in `lib/api/client.ts` so that
  transient failures do not bubble to callers.

SCOPE
  - Edit only `lib/api/client.ts` and `lib/api/client.test.ts`.
  - Do not change the exported signature of `request()`.
  - Do not touch any other files.

CONTEXT
  Read these first:
  - lib/api/client.ts       (the function to change)
  - lib/api/client.test.ts  (existing test style)
  - lib/api/errors.ts       (the error classes used)

BEHAVIOR
  - Retry on network errors and 5xx responses only.
  - Max 3 attempts with exponential backoff: 100ms, 200ms, 400ms.
  - Do not retry on 4xx — surface them immediately.

ACCEPTANCE
  1. `pnpm test lib/api/client.test.ts` — all tests pass.
  2. New tests cover: retry-on-5xx, no-retry-on-4xx, max attempts.
  3. `pnpm typecheck` — no errors.
  4. `git diff --name-only` — only the two files above appear.
  5. Stop when all of the above hold.

CLOSING STEP
  Print the diff, paste the test output, list assumptions, stop.
  Do not commit.

Every section removes an ambiguity Claude Code would otherwise guess at. For sibling tools, see the Cursor AI prompting guide and Aider prompting guide. For team workflows beyond the CLI — shared workspaces, persistent reference docs — see the SurePrompts + Claude Projects guide.

Common Anti-Patterns

• No CLAUDE.md, so every prompt re-explains the project. The agent drifts because context is missing. Fix: write a project CLAUDE.md on day one; keep it short and specific.
• Vague scopes. "Clean up the auth module" has no edge. Fix: name exact files to edit and files that are off limits.
• No stop condition. The agent keeps "improving" after the task is done. Fix: "Stop when all tests pass and no files outside lib/api/ are modified."
• Trusting output without re-running tests. "All tests pass" can be wrong because tests did not run, or ran against stale output. Fix: re-run tests yourself; diff-review every change.
• Unbounded tool access. Fine on a throwaway repo, risky on a production one. Fix: use the permissions model — allowlist safe commands, confirm risky ones, block destructive ones.
• Re-prompting when stuck instead of diagnosing. Each nudge burns tokens. Fix: stop the run, inspect the last three actions, fix the missing piece, restart with a tighter scope.

FAQ

How is prompting Claude Code different from prompting Claude.ai chat?

Claude.ai chat is single-turn. Claude Code is multi-step and autonomous — it plans, runs shell commands, edits files, and iterates against a goal. The input needs to look like a spec rather than a question: goal, scope, context files, acceptance criteria, stop condition. A conversational nudge that works in chat leaves Claude Code without a target to stop at.

What goes in CLAUDE.md vs. in each prompt?

Stable, reusable information goes in CLAUDE.md — tech stack, conventions, commands, directories that are off limits. Task-specific information goes in the prompt — what to build today, which files to touch, what done looks like. If you find yourself repeating a line in every prompt, it belongs in CLAUDE.md.

When should I use a sub-agent?

When the work is genuinely parallelizable, when you want context isolation, or when roles help (plan / implement / review as separate runs). For small tasks, the overhead is not worth it — stay in the main session.

Should I let Claude Code run any command?

No. A reasonable default: allow reads, tests, typecheck, lint, and git on feature branches. Confirm for installing packages, editing files outside scope, and any push. Block destructive operations — force pushes to main, branch deletes, production deploys, anything that leaves the sandbox.

How do I keep Claude Code from editing the wrong files?

Three layers. In CLAUDE.md, list off-limits directories by default. In the prompt, name the specific files Claude Code may edit. In the closing step, ask it to run git diff --name-only and stop if any file outside scope was modified. Layered constraints beat any single one.