Giving Good Instructions

The single most useful skill

Everything else in this course builds on one thing: how well you describe what you want.

Claude Code is smart, but it's not a mind reader. When you type a vague request, you get a vague result. When you describe exactly what "done" looks like, you get something you can actually use.

What follows are techniques for writing instructions that work on the first try. Or at least get close enough that one small adjustment finishes the job.

Describe the outcome, not the steps

The most common mistake new users make is trying to tell Claude Code how to do something instead of what they want.

You don't need to know the steps. That's Claude Code's job. Your job is to describe what "finished" looks like.

Here's the difference:

Notice the pattern. The second column focuses on the result. Claude Code figures out the steps on its own.

This might feel backwards if you're used to giving detailed instructions to people. But Claude Code works best when you describe the destination and let it pick the route.

Vague vs. specific

Being outcome-focused doesn't mean being vague. The more specific you are about what you want, the better the result.

Compare these:

The vague versions leave Claude Code guessing. What does "clean up" mean? Which names need fixing, and how? What counts as a good summary?

The specific versions answer those questions upfront. Claude Code spends its effort on the actual work instead of guessing what you meant.

Tip: If your instruction would make sense as a subject line but not as an email body, it's too vague. Add the details you'd include in the actual email.

The colleague test

Here's a reliable gut-check for whether your instructions are clear enough.

Anthropic, the company behind Claude Code, calls it the colleague test:

Read your instructions as if you were sending them to a colleague who has never seen your files and knows nothing about your project. Would they know what to do?

If a smart but uninformed colleague would ask follow-up questions, Claude Code will have the same questions — it just won't always ask them. Instead, it might guess. And the guess might be wrong.

Here's what the colleague test catches:

• Missing context. "Update the report" — which report? Update it how?
• Assumed knowledge. "Use the usual format" — Claude Code doesn't know your usual format.
• Ambiguous terms. "Make it better" — better how? More concise? More detailed? Different tone?

Before you hit Enter, read your instruction once more and ask: would someone with no context understand exactly what I want?

Tell Claude Code about purpose and audience

The biggest upgrade you can give any instruction is adding who it's for and why you need it.

Compare:

Summarize this sales data

Summarize this sales data for a board presentation. The audience is non-technical executives. Focus on trends and recommendations, not raw numbers. Keep it to one page.

The first version might give you a data dump with averages and row counts. The second version gives you something you can actually put on a slide.

Purpose changes everything. When Claude Code knows the result is headed to your manager, a client, or a slide deck, it adjusts tone, length, and level of detail to match.

Think about including:

• Who will read it — "This is for my team's weekly standup" vs. "This is for the VP of Sales."
• What you'll do with the result — "I need to paste this into a slide deck" vs. "I need this as a CSV I can open in Excel."
• How much detail you need — "Give me the highlights" vs. "I need every line item broken out."

Provide an example

When words aren't enough, show Claude Code what you want.

If you need files renamed in a specific pattern, show the pattern:

Rename the files in this folder to match this format: YYYY-MM-DD_client-name_document-type.pdf

For example: 2026-01-15_acme-corp_invoice.pdf

If you want data formatted a certain way, describe one row:

Reformat this contact list so each entry looks like:
Name: Jane Smith
Company: Acme Corp
Phone: (555) 123-4567
Email: jane@acme.com

If you want a summary in a particular style, share an example of a summary you liked from a previous project.

One concrete example often communicates more than three paragraphs of description.

Let Claude Code interview you

For bigger requests, there's a technique that flips the whole thing around.

Instead of trying to think of everything upfront, let Claude Code ask you the questions:

I want to create a report that tracks our team's project status. Before you start, interview me about what I need — ask me about format, audience, what data to include, and anything else you need to know.

Claude Code comes back with questions you hadn't considered: What time period should the report cover? How should projects be grouped? What does "on track" vs. "at risk" mean for your team? Should it include budget numbers?

You answer each one, and by the end Claude Code has a clear picture of what you need. Often a clearer picture than you had yourself before the conversation started.

This technique works especially well when:

• You know what you want but aren't sure how to describe it completely
• The task has a lot of details and you don't want to miss something important
• You've never done this kind of task before and aren't sure what the right questions are

You can also keep it brief:

Before you start, ask me any clarifying questions.

That single sentence prevents a lot of back-and-forth later.

Tip: When Claude Code asks you questions, it often presents multiple-choice options. You can pick one, or choose "Other" and type your own answer. There are no wrong answers — you're just telling it what you need.

When vague is okay

After all that advice about being specific, here's the counterpoint: not every instruction needs to be a detailed brief.

Sometimes you're exploring. You don't know what you want yet, and that's fine. Vague instructions are great for exploration:

• "What would you improve about this report?"
• "What patterns do you see in this data?"
• "How could these files be better organized?"

These work when you're willing to look at what comes back and then steer from there. The distinction that matters: are you exploring or executing? Exploring, keep it loose. Executing, be specific.

A quick reference

Before you type your next instruction, run through this checklist:

• What does "done" look like? Describe the result, not the steps.
• Would a colleague understand? Read it as if someone with no context had to act on it.
• Who is it for? Mention the audience if it's relevant.
• Can you show an example? One example beats three paragraphs of description.
• Is it big enough to interview? For complex tasks, let Claude Code ask the questions.

These habits carry over, by the way. Clear instructions to Claude Code make you clearer in emails, briefs, and meetings too.

Next up: how to check what Claude Code gives you back, and what to look for before you trust the result.