Claude · 08 · Part 4

Learning to Communicate with Claude

A coding agent is only as good as the task you hand it. This page teaches how to give an agent what it cannot find for itself — intent, constraints and a way to check its work — using Spring examples from the bookshelf project. The guidance follows Anthropic's Claude Code best-practices page; the failing outputs are real failures captured while building the project.

5
Prompt parts
4
Before/after pairs
3
Real failures
Map · 01 World of AI · 02 AI in Dev · 03 Coding Agents · 04 Ecosystem · 05 Anthropic & Claude · 06 Claude Code · 07 Installation · 08 Prompting · 09 Real Projects · 10 Capabilities · 11 Workflows · 12 Your Environment · 13 Security · 14 Future · 15 Prompt Library · 16 Recipes · 17 Reading Output · 18 First Skill · 19 Skill Pack · 20 First Subagent · 21 Agent Teams · 22 Hooks Lab · 23 MCP Lab · 24 Plugins · 25 Headless CI · 26 Capstone · 27 Cheat Sheet
Information current as of: 2026-10-30
01
Chapter One · A Different Kind of Prompt

You Are Delegating, Not Dictating

Anthropic's advice for Claude Code is to treat it like a capable colleague: give context and direction, then let it work out the details (Source 1). You do not need to say which files to read or which commands to run; Claude searches the repository itself.

What it cannot do is read your mind or your team's meetings. The best-practices page puts the dividing line precisely: Claude can find what is in the repository, so write down only what it cannot see (Source 2).

What the agent can find vs. what only you can tell it
Claude can find it • file and package layout• existing code conventions• which test framework is used• how a similar feature is built• what the build tool is don't re-explain it Only you can supply it • what you actually want• decisions made off-repo• a preferred approach• limits (no new libraries)• what "done" looks like say it in the prompt
02
Chapter Two · Anatomy

Five Parts of a Good Task Prompt

Not every prompt needs all five, but a request that fails usually lacks one. These are this guide's names for patterns that Anthropic's pages describe in other words: naming the file and symptom, saying what fixed looks like, pointing at a pattern to follow, stating constraints, and giving a check to run (Source 2).

The five parts
1 Objectivethe goal 2 Contextwhere · why 3 Constraintslimits 4 Outcomewhat done is 5 Checkrun to prove One task promptspecific enough to verify
PartQuestion it answersbookshelf example
ObjectiveWhat should be true afterwards?"Add GET /api/books/{id} that returns one book."
ContextWhere, and what is happening now?"Listing is in BookController; unknown ids currently give a 500."
ConstraintsWhat must not change, what to follow?"Follow the existing controller style. No new libraries. Don't change the DTO."
OutcomeHow will we know it is right?"Unknown id returns 404 with a ProblemDetail body."
CheckWhat can Claude run to find out?"Run ./mvnw -B test and show me the output."
The check is the most leveraged part. Anthropic's guidance says that with something that returns pass or fail, Claude can make a change, run it, read failures and fix them itself, rather than you becoming the test suite. It also advises asking for evidence — the command and its output — instead of accepting "all tests pass" (Source 2).
03
Chapter Three · Before and After

Vague Prompts vs. Engineering Prompts

The docs' own example pair is "fix the login bug" versus a prompt that names the symptom, the code area, a failing test and the fix (Source 2). Here are four in the bookshelf project.

1 · Add an endpoint
Vague
add an endpoint for books

Which verb, which path, what for a missing id, what shape of response, any tests?

Engineering prompt
add GET /api/books/{id} returning one BookDto. Unknown id -> 404 with a ProblemDetail body. Follow the style of BookController; no new libraries. Add a @WebMvcTest for the 404 case and run ./mvnw -B test.
2 · Fix a failure
Vague
the tests are broken, fix them

Invites edits to the tests rather than the code, and gives no hint of what "broken" means.

Engineering prompt
BookQueryCountTest fails: expected 1 SQL statement for findAll() but was 4. Find why listing runs extra queries, fix it in the repository layer without changing BookDto, and keep the test unchanged. Run ./mvnw -B test.
3 · Validation
Vague
add validation

Where? Which rules? What should the client see?

Engineering prompt
Validate POST /api/books: title and author not blank, year 1450..2100. Use Jakarta Bean Validation on a CreateBookRequest record. Invalid input -> 400. Add tests for a blank title and a year of 3000.
4 · Performance
Vague
make the book listing faster

"Faster" has no measure, so any change can be called done.

Engineering prompt
Listing books should run exactly one SQL statement. Measure the current count with the Hibernate statistics approach in BookQueryCountTest, find the cause, and fix it. Report before and after counts.
When vague is fine. Anthropic's page notes that for exploration — "what would you improve in this file?" — a vague prompt is completely fine; you will simply correct more as you go (Source 2). Precision matters when you want a specific change.
04
Chapter Four · Giving Context

Hand Over What You Have

When you already hold the thing Claude needs, give it rather than describe it (Source 2):

  • A file: type @src/main/java/com/example/bookshelf/BookService.java to include its contents. The Read tool's default limit for this is 25,000 tokens, and a text file over 256KB is not included (Source 3).
  • An image: paste a screenshot of the error or design.
  • Command output: pipe it from your shell, for example cat error.log | claude -p "what's going on here".
Three real inputs from the bookshelf project

These were captured while building version 2. Each is exactly the kind of thing worth pasting into a prompt.

1 · Actual output · Maven test failure (excerpt) · Spring Boot 4.1.2, H2, Java 21
Caused by: org.h2.jdbc.JdbcSQLSyntaxErrorException: Syntax error in SQL statement "create table book ([*]year integer not null, author_id bigint, id bigint not null, title varchar(255), primary key (id))"; expected "identifier"
2 · Actual output · assertion failure from BookQueryCountTest
SQL statements for findAll(): 4 [ERROR] BookQueryCountTest.listingBooksUsesASingleQuery:29 expected: 1L but was: 4L
3 · Actual output · running app, GET /api/books/99 with no exception handler
HTTP/1.1 500 {"timestamp":"2026-10-30T17:34:38.729Z","status":500,"error":"Internal Server Error","path":"/api/books/99"} com.example.bookshelf.BookNotFoundException: Book 99 not found at com.example.bookshelf.BookService.findById(BookService.java:25) at com.example.bookshelf.BookController.get(BookController.java:31)

Notice what each contains: the exact error, the place it came from, and what was expected. A prompt that includes input 1 plus "the app is Spring Boot with H2; find the cause" gives the agent a precise starting point instead of a guess. Chapter 9 resolves all three.

Trim the noise. A full Maven log can run to hundreds of lines. Paste the failing assertion and the stack frames in your own code; large pastes fill the context window you learned about in Chapter 1.
05
Chapter Five · Breaking Work Down

Explore, Plan, Implement, Verify

For anything bigger than a one-line change, split the work. The documentation's tips are consistent: let Claude explore before changing; give step-by-step instructions for complex tasks; and use plan mode when you want to review an approach before anything touches disk (Source 4, Source 5).

A workflow that keeps you in control
Exploreread-only Planyou approve Implementedits Verifyrun tests Reviewread the diff tests fail → fix small tasks can skip Explore and Plan; the check never gets skipped
Plan mode in practice

In plan mode Claude reads and proposes a plan but makes no edits until you approve. Enter it with Shift+Tab (the status bar shows ⏸ plan mode on), by prefixing a message with /plan, or at start-up with claude --permission-mode plan. Press Ctrl+G to edit the plan in your editor before approving (Source 5).

Start in plan mode · not executed for this page
$ claude --permission-mode plan
Prompt
I want to add pagination to GET /api/books. Read BookController, BookService and BookRepository, then propose a plan: which classes change, the API shape (page, size, default values), and which tests to add. Do not edit anything yet.
Illustrative plan shape — written for this guide, not captured from a real session
Plan 1. BookRepository: add Page<Book> findAllBy(Pageable) with the author entity graph kept. 2. BookService.findAll(page, size): map to Page<BookDto>. 3. BookController.list: accept ?page=0&size=20 (defaults), cap size at 100. 4. Tests: controller test for defaults and an oversized page; extend BookQueryCountTest to assert the paged query is still a single statement. Open question: should the response be a bare array or an envelope with totals?

A good plan names the open question rather than hiding it. Answer it, edit anything you disagree with, and only then approve implementation. Anthropic's best-practices page adds an interview variant for when you do not yet know what you want: ask Claude to interview you until it could write the spec, write it to a file such as SPEC.md, and start a fresh session to build from it (Source 2).

Decompose with numbered steps
From the quickstart's pattern, adapted to bookshelf
1. add a Review entity (id, bookId, rating 1-5, comment) 2. add POST /api/books/{id}/reviews with validation 3. return average rating in GET /api/books/{id} run ./mvnw -B test after each step and stop if anything fails
06
Chapter Six · Reviewing

Read What It Proposes

In Manual mode every edit and command prompts you; the prompt shows what Claude is about to do. Read it. In the VS Code extension, proposed edits appear as side-by-side diffs you can accept or reject per change (Source 6). After the work, review the full diff with Git: git diff shows what changed regardless of which tool changed it.

Review questionWhy
Did it change only the files the task needed?Unrelated edits are scope creep and hide risk.
Does a test fail without the change?A test that cannot fail proves nothing.
Did it edit or delete tests to make them pass?The classic failure when "fix the tests" is the prompt.
Any new dependency, config or permission?Supply-chain and security surface.
Does the evidence match the claim?Ask for the command and its output, not a summary.

For a second opinion, Anthropic suggests asking a subagent to review the diff against your spec — and to skip style, because a reviewer asked to find problems will always find something (Source 2):

Review prompt pattern from the best-practices page, adapted
use a subagent to review the pagination diff against SPEC.md, check every requirement is implemented and the listed edge cases have tests, report gaps that affect correctness and skip style
07
Chapter Seven · Iterating

Debugging Through Conversation

You rarely get it right in one prompt, and you do not have to: "when the first attempt isn't right, you don't start over. You iterate" is how the how-it-works page describes it (Source 1). The controls:

  • Esc stops Claude immediately and keeps the conversation.
  • Type while it works. A message sent during a run is queued and read as soon as the current tool calls finish, so you can correct course without stopping.
  • Rewind. Press Esc twice (or use /rewind) to restore file changes and conversation to an earlier checkpoint. Checkpoints cover file edits only.
  • Start clean. /clear between unrelated tasks; stale context costs tokens and attention.
A debugging conversation, shaped by the real failure

Using the real output from Section 4, a good exchange has this shape. The replies are illustrative; the first message and the evidence it cites are real.

Illustrative conversation shape — the failing output in message 1 is real, the replies are written for this guide
YOU: BookQueryCountTest fails: expected 1 SQL statement for findAll() but was 4. Find the cause. Don't change the test or BookDto. Show me what you find first. CLAUDE: (reads BookService, BookRepository, Book, BookDto) findAll() maps each Book to BookDto and calls book.getAuthor().getName(). Book.author is LAZY, so each distinct author triggers its own SELECT: 1 query for books + 3 for authors = 4. YOU: Fix it in the repository, keep ordering by title. Then run ./mvnw -B test. CLAUDE: (adds an entity graph for author on findAllByOrderByTitle, runs the tests) All 5 tests pass; the statement count is now 1.

Two habits make this work. First, the human asked for the diagnosis before the fix, so a wrong theory could be corrected cheaply. Second, the verification is a test that already existed. The actual fix and the real before/after counts (4 then 1) are in Chapter 9.

Effort and phrasing. Anthropic notes that phrases like "think step by step" are ordinary prompt text, not switches; the main control for how hard Claude thinks is the effort level, and one phrase that does still help is be ambitious when you want the fuller version with edge cases and follow-ons (Source 2).
08
Chapter Eight · Common Mistakes

Prompting an Agent

1 · Insufficient context. "Fix the 500" without the endpoint, the reproduction or the stack trace makes the agent search blindly. Name the file and symptom.
2 · No check. If Claude has nothing to run, "looks done" is all it has. Name the test command in the prompt or in CLAUDE.md.
3 · "Fix the tests". The agent may change the tests instead of the code. Say which side is authoritative: "keep the test unchanged".
4 · Accepting generated tests unvalidated. Tests Claude wrote for code Claude wrote can share the same wrong assumption. Break the code on purpose and confirm the test fails.
5 · One giant prompt. A long, multi-feature request hides which part went wrong. Use numbered steps, or plan first.
6 · Re-explaining what the repo shows. Padding the prompt with file layouts and conventions Claude can read wastes context. Add only what it cannot see.
7 · Using the agent for trivia. Renaming one variable does not need exploration and a plan. Match the process to the size of the task.
09
Chapter Nine · Summary

Key Takeaways, Exercises and Sources

∑ Communicating with Claude — what to remember
  • Delegate, but tell it what it cannot see: intent, decisions, constraints and what done means.
  • Five parts: objective, context, constraints, outcome, check. The check matters most.
  • Paste real evidence — the failing assertion, the stack trace — not a paraphrase.
  • Explore, plan, implement, verify for anything non-trivial; plan mode makes the plan reviewable.
  • Review the diff, not the summary, and ask for command output as evidence.
  • Iterate. Interrupt early, rewind when needed, and clear context between tasks.
Exercises

Exercise 1 Beginner

Rewrite these three vague prompts as engineering prompts for the bookshelf project: "add search", "it's slow", "write some tests". For each, label which of the five parts you added.

Learning outcome: recognise missing prompt parts.

Exercise 2 Intermediate

In plan mode, ask Claude to plan pagination for GET /api/books without editing. Read the plan, find one assumption you disagree with, edit the plan (Ctrl+G), and only then approve. Record what changed between the first plan and the one you approved.

Learning outcome: use plan mode as a review checkpoint, not a formality.

Exercise 3 Advanced

Introduce a bug in the project on purpose (for example, sort listing by year instead of title). Give Claude two prompts: one vague ("books are in the wrong order") and one precise with the failing assertion pasted in. Compare the number of corrections each needed and which one touched files it should not have.

Learning outcome: measure, rather than assume, how prompt quality changes the result.

Sources (read on 2026-10-30; paraphrased, at most one short quote per source)
  1. Anthropic, How Claude Code works — delegating, interrupting and steering, checkpoints.
  2. Anthropic, Best practices for Claude Code — tell Claude what it cannot see, specific prompts, checks, spec interviews, review prompts. The page was read in part; later sections were not.
  3. Anthropic, Common workflows — @ references and limits, piping, plan mode, worktrees.
  4. Anthropic, Quickstart — prompt examples and "pro tips".
  5. Anthropic, Permission modes — entering plan mode, editing the plan.
  6. Anthropic, VS Code extension — inline diffs and per-change accept/reject.

The three "real input" blocks are verbatim excerpts from commands run on this machine on 2026-10-30 (Spring Boot 4.1.2, H2, OpenJDK 21.0.2). The plan and the debugging conversation are illustrative text written for this guide; no Claude Code session was run. Anthropic's general prompt-engineering guide for Claude models was fetched but only skimmed, so this page relies on the Claude Code pages above.