title: "Prompting for Agents — Claude Code" tested_with: claude-code: "1.0.x" last_updated: 2026-03-21 status: proven difficulty: beginner prerequisites: [02-project-memory]

Prompting for Agents — Claude Code

This guide covers prompting techniques specific to Claude Code. For general prompting principles, see concepts.md in this module.

Plan Mode

Plan mode tells Claude Code to think through a task before executing it. Instead of immediately editing files and running commands, the agent produces a structured plan that you can review, modify, or approve.

When to Use Plan Mode

Use plan mode when:

  • The task is complex and touches multiple files or systems
  • You want to understand the agent's approach before it starts making changes
  • You are unfamiliar with the area of code being modified
  • The task has multiple valid approaches and you want to choose one
  • You are working on something risky (database migrations, auth changes, deployment configs)

Skip plan mode when:

  • The task is straightforward and well-scoped ("fix the typo in the error message")
  • You have high confidence in what needs to happen
  • You are iterating on a previous result and the direction is already established

How to Use Plan Mode

Activate plan mode by including the word "plan" in your prompt or by pressing Shift+Tab to toggle into plan mode before sending:

Plan how to add rate limiting to the API endpoints in src/api/

Claude Code will respond with a numbered plan: which files it will examine, what changes it will make, and in what order. You can then:

  • Approve the plan: "Looks good, go ahead."
  • Modify the plan: "Skip step 3. For step 4, use the existing Redis connection instead of creating a new one."
  • Reject and redirect: "Actually, I want to use middleware instead of per-endpoint logic. Replan."

Plan mode is especially valuable early in a project when you are still establishing patterns. Once patterns are established and documented in your CLAUDE.md, you can rely on direct execution more often.

Slash Commands

Claude Code provides built-in slash commands that control the tool's behavior. These are not prompts to the agent — they are commands to the interface.

Essential Commands

  • /help — Show available commands and usage information. Use this when you forget a command or want to explore capabilities.

  • /clear — Reset the conversation. All context from the current session is discarded. Use this when switching tasks or when the conversation has become too long and unfocused.

  • /compact — Compress the conversation history to reclaim context window space. The agent summarizes prior turns into a condensed form. Use this when you are deep into a long session and want to keep going without starting fresh. Unlike /clear, the agent retains a summary of what happened.

  • /model — Switch the underlying model. Useful when you want to try a different model for a particular task or balance cost vs. capability.

When to Use /compact vs. /clear

Use /compact when the earlier conversation context is still relevant — you are mid-task and need to continue, but the context window is getting full. The agent preserves the essence of what you discussed.

Use /clear when you are starting something genuinely new. Carrying old context into a new task adds noise and can bias the agent's approach.

Multi-Turn Conversations

Claude Code retains full context within a session. This means your second prompt builds on the first, your third builds on the second, and so on. This is powerful but requires a different approach than single-shot prompting.

Building on Previous Work

After the agent completes a task, you can refine it without restating the full context:

Turn 1: "Add input validation to the createUser function in src/api/users.ts"

Turn 2: "Good. Now add the same validation pattern to updateUser in the same file."

Turn 3: "The email validation is too strict — it's rejecting addresses with plus signs. Fix that in the validation helper you created."

Each turn is short and specific because the agent already knows what you are working on, which files are involved, and what patterns have been established.

The Compound Context Advantage

By turn three, the agent understands:

  • Your codebase structure
  • The validation pattern it created
  • Your preferences (you noticed the plus-sign issue, so you care about edge cases)
  • The specific files and functions involved

This compound context is more valuable than any single prompt could be. It is one reason why multi-turn iteration outperforms one-shot prompting for complex work.

Referencing Files Explicitly

One of the most effective prompting techniques in Claude Code is pointing directly to files and code locations. The agent can read files, but telling it where to look saves time and reduces ambiguity.

Direct File References

Look at src/auth/middleware.ts and fix the bug where expired tokens aren't rejected.

The test in tests/api/users.test.ts is failing on line 42. The assertion expects a 200 but the endpoint now returns 201.

Compare the error handling in src/api/orders.ts with src/api/users.ts. Make users.ts match the orders pattern.

Why This Works

Explicit file references eliminate the agent's search phase. Instead of scanning the project to figure out where the relevant code lives, it goes directly to the right file. This is faster and reduces the chance of the agent finding and modifying the wrong file.

The "Do X, Then Y" Pattern

For multi-step tasks, structure your prompt as a sequence:

First, add a "lastLogin" timestamp field to the User model in src/models/user.ts.
Then update the login endpoint in src/api/auth.ts to set this field on successful login.
Finally, add a test that verifies lastLogin is updated after login.

This pattern works because:

  • Each step has a clear deliverable
  • The steps build on each other logically
  • The agent can complete and verify each step before moving to the next
  • You can review the intermediate results

Keep the sequence to two to four steps. Beyond that, break the work into separate prompts so you can review and course-correct between chunks.

Correcting Course Mid-Task

When the agent produces something that is not quite right, give targeted feedback rather than starting over:

Instead of: "That's wrong, try again."

Say: "The function works but it's modifying the input array in place. Return a new array instead."

Instead of: "I don't like this approach."

Say: "This approach adds a new dependency. Rewrite it using only the standard library."

Instead of: "Start over."

Say: "Keep the test file you created but rewrite the implementation to use a queue instead of polling."

Specific corrections preserve the work that was done right and fix only what needs changing. The agent does not need to re-derive the parts that already met your expectations.

Using Images and Screenshots

Claude Code accepts images in prompts. This is useful for:

  • UI bugs: Paste a screenshot showing the visual problem. "Here is what the dashboard looks like. The chart legend is overlapping the title. Fix the CSS."
  • Design references: Share a mockup. "Implement this design in the ProfileCard component."
  • Error messages: Screenshot a complex error from a browser console or terminal output that is hard to copy as text.

To include an image, drag it into the prompt or paste it from your clipboard. Combine images with text for best results — the image shows the what, your text explains the task.

Effective Prompt Templates

These templates encode the principles from the concepts module into concrete patterns for common tasks.

Bug Fixing

There's a bug where [describe the symptom — what happens vs. what should happen].

The relevant code is in [file path]. [Optionally: I think the issue is in the [function/section] area.]

Fix the bug and add a test that would have caught it.

Example:

There's a bug where users can submit the registration form with an empty email field. The form should show a validation error instead.

The relevant code is in src/components/RegistrationForm.tsx. The validation logic is in the handleSubmit function.

Fix the bug and add a test that verifies empty emails are rejected.

Feature Addition

Add [feature description] to [component/module].

Follow the pattern used in [existing similar feature] for consistency.

[Any constraints: "Don't add new dependencies," "Keep the existing API," etc.]

Example:

Add a "forgot password" flow to the auth module.

Follow the pattern used in the email verification flow in src/api/auth/verify-email.ts for consistency.

Use the existing email service in src/services/email.ts to send the reset link. Don't add new dependencies.

Refactoring

Refactor [file or function] to [goal — what the refactored version should achieve].

Don't change the public API — existing callers should not need to be updated.

[Any specific constraints or preferences.]

Example:

Refactor the processOrder function in src/services/orders.ts to separate validation, pricing, and persistence into distinct helper functions.

Don't change the public API — processOrder should still accept the same arguments and return the same type.

Add JSDoc comments to each new helper function.

Code Review

Review [file or directory] for [specific concerns].

Suggest improvements but don't make changes yet.

Example:

Review src/api/payments.ts for security issues. Specifically check for:
- SQL injection vulnerabilities
- Improper input validation
- Sensitive data in logs
- Missing authentication checks

Suggest improvements but don't make changes yet.

This last template uses plan mode implicitly — by saying "suggest but don't change," you get the agent's analysis without it modifying code. You can then selectively ask it to implement specific suggestions.

Summary

The key Claude Code-specific techniques are:

  1. Plan mode for complex or risky tasks — review the strategy before execution
  2. Slash commands to manage your session — /compact to reclaim space, /clear to reset
  3. Explicit file references to eliminate search time and ambiguity
  4. Sequential steps with the "do X, then Y" pattern for multi-step work
  5. Targeted corrections that preserve good work and fix only what needs changing
  6. Images for UI bugs, design references, and complex errors
  7. Prompt templates that encode good patterns for recurring task types

Combine these with the general principles from the concepts module — intent over instruction, right-sized tasks, iterative feedback — and you will consistently get strong results from Claude Code.