Describing Behavior Clearly
The quality of code AI generates depends heavily on how clearly you describe what you want. Vague descriptions produce vague code. Clear behavioral specifications produce code that works the first time.
Behavior, Not Implementation
When describing what you want to build, focus on behavior — what the user experiences — not implementation details. Describe what goes in, what comes out, and what happens in between.
This shift in thinking helps both you and the AI. You clarify your requirements, and the AI has the information it needs to generate appropriate code.
The Four Elements of Clear Descriptions
Good behavioral descriptions include:
Inputs: What data does this code receive? What format? What constraints?
Outputs: What does this code produce? What format? What does success look like?
Edge cases: What unusual situations might occur? Invalid input? Missing data? Network failures?
Acceptance criteria: How do we verify this works correctly?
When you cover these four elements, you've given the AI everything it needs.
Bad vs Good Descriptions
Here's a vague description:
"Make a function for stocks"
This tells the AI almost nothing. What about stocks? Fetching prices? Calculating returns? Storing portfolios? The AI will guess, and it will probably guess wrong.
Here's a clear description:
"Create a function called get_stock_price that:
- Takes a stock ticker symbol (string) as input
- Calls the Alpha Vantage API to get current price
- Returns the price as a float
- Raises an exception if the ticker is invalid
- Handles network errors gracefully"
This description specifies the function name, input type, data source, return type, and error handling. The AI can generate exactly what you need.
Writing Acceptance Criteria
Acceptance criteria answer: "How do I know this works?" They're simple statements that can be verified:
Acceptance criteria for get_stock_price:
- get_stock_price("AAPL") returns a positive float
- get_stock_price("INVALID123") raises a ValueError
- get_stock_price("AAPL") with no network returns a NetworkError
These criteria become your tests. If the code passes all criteria, it works.
Practice the Skill
Clear description is a skill that improves with practice. Before prompting AI, take thirty seconds to write down:
- What this code receives
- What this code produces
- What could go wrong
- How you'll verify it works
This small investment dramatically improves AI output and reduces frustrating back-and-forth iterations.