Back to course
Your First Build
Lesson 3 of 10
Free

Talking to AI That Builds

Learn how to give clear instructions that get you what you actually need. The difference between vague requests and precise directions.

15 min read
Share

The file renamer worked because Claude understood what you wanted. But what happens when your instructions are ambiguous? Or when you’re not sure exactly what you need?

This lesson teaches you to communicate with AI in a way that gets results.

Why Instructions Matter

Here’s the same request, two ways:

Vague:

Make a tool for contracts

Specific:

Create a Python script that:
1. Reads all .docx files in the current folder
2. Searches each file for the word "termination"
3. Prints the filename and the paragraph containing that word

The vague request might give you anything—a contract template, a CRM system, a PDF generator. The specific request gives you exactly what you need.

You don’t need to know programming to be specific. You need to think about what you want to happen.

The Anatomy of a Good Instruction

Good instructions have three parts:

1. What It Should Do (Action)

Start with the action. What should happen when this thing runs?

  • “Read all PDF files in a folder”
  • “Extract dates from a document”
  • “Compare two contracts and list differences”
  • “Send me an email when a deadline is 7 days away”

2. What It Works With (Input)

What does the tool need to operate on?

  • “Files in the current folder”
  • “A Word document I specify”
  • “Any text I paste in”
  • “A CSV file with client names and dates”

3. What It Produces (Output)

What should you get back?

  • “Print results to the screen”
  • “Create a new file with the results”
  • “Show me a summary and ask if I want details”
  • “Save as a CSV I can open in Excel”

Practice: Building a Clause Finder

Let’s build something using good instructions. Start Claude in a folder:

cd ~/Desktop/my-first-tool
claude

Try this vague instruction first:

Make something that finds clauses in contracts

See what Claude builds. It will probably work, but might not be exactly what you need.

Now try a specific version:

Create a Python script that:
1. Reads a Word document I specify (I'll type the filename)
2. Finds every paragraph that contains the word "shall"
3. Numbers each one and prints them all
4. At the end, tells me how many "shall" paragraphs it found

Compare the results. The specific version gives you predictable, useful output.

Handling Ambiguity

Sometimes you don’t know what you want until you see it. That’s fine—iterate.

Start broad:

I need a way to track which documents I've reviewed in a case.
What approaches could work?

Claude will suggest options. Pick one and get specific:

Let's go with the spreadsheet approach. Create a script that:
1. Looks at all files in a folder
2. Creates a CSV with columns: filename, file type, date modified
3. Adds an empty "Status" column I can fill in manually
4. An empty "Notes" column for my comments

When to Add Detail

Add detail when:

  • There are multiple valid interpretations. “Organize these files” could mean by date, by type, by client—specify which.
  • The default might not work. “Search for deadlines” might only find the word “deadline”—specify that you also want dates that follow words like “due by” or “no later than.”
  • You care about the format. “Show me the results” could mean printed text, a file, or a popup—say which you want.

Skip detail when:

  • The standard approach is fine. “Create a folder called ‘Archive’” doesn’t need more specification.
  • You want to see options. “What’s the best way to…” lets Claude suggest approaches.

The Refinement Pattern

Most building follows this pattern:

  1. Start with what you know

    I need to process client intake forms

  2. Claude asks or assumes—correct as needed

    Actually, the forms are PDFs, not Word documents.
And I need to extract the client name and matter type specifically.

  3. Test and adjust

    This works, but can you also grab the date from the top of the form?

  4. Handle edge cases

    Some forms have the date in a different spot. Can you check the first
three lines for anything that looks like a date?

This conversation is normal. You don’t need to get everything right in the first message.

Common Instruction Mistakes

Too Abstract

❌ “Make document management better” ✅ “Create a script that renames files in this folder to follow the pattern: YYYY-MM-DD_ClientName_DocType”

Missing Context

❌ “Parse the contracts” ✅ “Parse the .docx files in the /contracts folder and extract the party names from the first page”

Assuming Knowledge

❌ “Use the standard format” ✅ “Use the format: 2024-03-15_Smith-v-Jones_Motion.pdf”

Forgetting Output

❌ “Find all the deadlines” ✅ “Find all the deadlines and save them to a file called deadlines.csv with columns for date, description, and source document”

Exercise: Rewrite These Instructions

Take these vague requests and make them specific:

1. “Help with contracts”

Think: What specifically about contracts? Reading them? Organizing them? Finding certain clauses? What format are they in? What output do you want?

2. “Track my cases”

Think: What information about each case? Where does that information come from? How do you want to see it? What actions should be possible?

3. “Make email easier”

Think: Which emails? What’s hard about them now? Do you want drafting help? Organization? Searching? What would “easier” actually look like?

Quick Reference: Instruction Template

When you’re stuck, fill in this template:

Create a [script/tool] that:
1. [ACTION]: [what it does]
2. [INPUT]: Works with [what kind of files/data]
3. [PROCESS]: For each item, [what happens]
4. [OUTPUT]: Produces [what format, where saved]
5. [EDGE CASES]: If [problem], then [what to do]

Example:

Create a script that:
1. ACTION: Finds confidentiality clauses in contracts
2. INPUT: Works with all .docx files in the current folder
3. PROCESS: For each file, searches for paragraphs containing
   "confidential" or "non-disclosure"
4. OUTPUT: Produces a text file listing the filename and matching
   paragraphs
5. EDGE CASES: If a file can't be read, skip it and note which
   files were skipped at the end

What You’ve Learned

  • Specific instructions get predictable results
  • Good instructions have action, input, and output
  • It’s fine to iterate—start broad, then refine
  • Detail matters when there are multiple interpretations

Next Lesson

You can tell Claude what to build. But how do you know if what it built is right? The next lesson covers reading and understanding code—not to write it, but to verify it does what you asked.