Write Better Prompts for AI Coding Tools: Developer Guide

# Expected output for the good prompt
def calculate_factorial(n: int) -> int:
    """
    Computes the factorial of a non-negative integer.

    Args:
        n: The non-negative integer.

    Returns:
        The factorial of n.

    Raises:
        ValueError: If n is a negative integer.
    """
    if not isinstance(n, int):
        raise TypeError("Input must be an integer.")
    if n < 0:
        raise ValueError("Factorial is not defined for negative numbers.")
    if n == 0 or n == 1:
        return 1
    
    result = 1
    for i in range(2, n + 1):
        result *= i
    return result

# Example usage
# print(calculate_factorial(5)) # Output: 120
# print(calculate_factorial(0)) # Output: 1
# calculate_factorial(-1)       # Raises ValueError

# main.py (existing context)
from fastapi import FastAPI, HTTPException
from typing import List, Dict, Optional
from pydantic import BaseModel

app = FastAPI()

# In a real app, this would be a database
fake_db: Dict[int, 'User'] = {} # Forward reference for type hinting

@app.on_event("startup")
async def startup_event():
    # Populate some initial data
    global fake_db
    fake_db = {
        1: User(id=1, name="Alice", email="alice@example.com"),
        2: User(id=2, name="Bob", email="bob@example.com")
    }

@app.get("/")
async def read_root():
    return {"message": "Welcome to the User API!"}

# models.py (existing context, or defined inline for brevity)
class User(BaseModel):
    id: int
    name: str
    email: str

# --- End of existing context ---

# Prompt for: Add a new GET endpoint at /users/{user_id}
# Expected output from AI:
@app.get("/users/{user_id}", response_model=User)
async def get_user_by_id(user_id: int):
    """
    Retrieve a user by their ID.
    """
    user = fake_db.get(user_id)
    if user is None:
        raise HTTPException(status_code=404, detail="User not found")
    return user

# Original synchronous function
import requests
import time

def process_data(urls: list[str]) -> list[dict]:
    results = []
    for url in urls:
        try:
            response = requests.get(url, timeout=5)
            response.raise_for_status()
            results.append({"url": url, "status": response.status_code, "data": response.json()})
        except requests.exceptions.RequestException as e:
            results.append({"url": url, "error": str(e)})
    return results

# Example usage
# urls = ["https://jsonplaceholder.typicode.com/todos/1", "https://jsonplaceholder.typicode.com/todos/2"]
# start_time = time.time()
# output = process_data(urls)
# print(f"Synchronous execution time: {time.time() - start_time:.2f} seconds")
# print(output)

# Prompt for: Refactor to use asyncio and aiohttp
# Expected output from AI:
import asyncio
import aiohttp
import time

async def process_data(urls: list[str]) -> list[dict]:
    async def fetch(session, url):
        try:
            async with session.get(url, timeout=5) as response:
                response.raise_for_status()
                return {"url": url, "status": response.status, "data": await response.json()}
        except aiohttp.ClientError as e:
            return {"url": url, "error": str(e)}
        except asyncio.TimeoutError:
            return {"url": url, "error": "Request timed out"}

    async with aiohttp.ClientSession() as session:
        tasks = [fetch(session, url) for url in urls]
        return await asyncio.gather(*tasks)

# Example usage (needs to be run in an async context)
# async def main():
#     urls = ["https://jsonplaceholder.typicode.com/todos/1", "https://jsonplaceholder.typicode.com/todos/2"]
#     start_time = time.time()
#     output = await process_data(urls)
#     print(f"Asynchronous execution time: {time.time() - start_time:.2f} seconds")
#     print(output)

# if __name__ == "__main__":
#     asyncio.run(main())

   # Existing test example
   import pytest
   from your_module import User

   def test_user_creation_valid():
       user = User(id=1, name="Alice", email="alice@example.com")
       assert user.id == 1
       assert user.name == "Alice"
       assert user.email == "alice@example.com"
   ```

Now, generate a `pytest` test function `test_user_creation_invalid_email` that checks if a `ValidationError` is raised when creating a `User` with an invalid email format (e.g., "invalid-email")."

```python
# Expected output for the good prompt
import pytest
from pydantic import ValidationError
from your_module import User # Assuming User is defined in 'your_module.py'

def test_user_creation_invalid_email():
   """
   Test that creating a User with an invalid email raises a ValidationError.
   """
   with pytest.raises(ValidationError) as excinfo:
       User(id=2, name="Bob", email="invalid-email")
   
   # Optionally, check specific error details
   assert "value is not a valid email address" in str(excinfo.value)

   import csv

   def read_csv_file(filepath):
       with open(filepath, 'r') as file:
           reader = csv.DictReader(file)
           return list(reader)
   ```

* **Refinement Prompt 1:** "That's good. Now, modify the `read_csv_file` function to gracefully handle `FileNotFoundError` and `csv.Error`. For `FileNotFoundError`, it should return an empty list. For `csv.Error` (e.g., malformed CSV), it should log the error and also return an empty list."

* **AI's Refined Output (expected):**
```python
   import csv
   import logging

   logging.basicConfig(level=logging.INFO, format='%(levelname)s: %(message)s')

   def read_csv_file(filepath: str) -> list[dict]:
       """
       Reads a CSV file and returns its contents as a list of dictionaries.
       Handles FileNotFoundError and csv.Error gracefully.
       """
       try:
           with open(filepath, 'r', newline='') as file: # Added newline='' for consistency
               reader = csv.DictReader(file)
               return list(reader)
       except FileNotFoundError:
           logging.warning(f"File not found: {filepath}")
           return []
       except csv.Error as e:
           logging.error(f"Error reading CSV file {filepath}: {e}")
           return []
   ```

### Step 6: Break Down Complex Tasks (Chain of Thought)

For large or multi-step problems, asking the AI to outline a plan first, and then implementing each step, leads to more coherent and accurate results. This mimics how a human engineer would approach a complex problem.

**Actionable Tip:** Start with "Plan how to...", "Outline the steps...", "First, generate a high-level design for X, then implement step 1."

**Example 6: Building a Small Feature**

* **Poor Prompt:** "Build a user authentication system with JWT."
* *Issue:* Too broad, will likely get a massive, potentially insecure, and generic solution.

* **Good Prompt (Chain of Thought):**
1. **Prompt 1 (Planning):** "Outline the high-level steps required to implement a basic user authentication system in Python using FastAPI and JWT. Focus on user registration, login, and a protected endpoint."

2. **AI's Outline (expected):**

       # models.py
       from pydantic import BaseModel
       from typing import Optional

       class User(BaseModel):
           username: str
           email: Optional[str] = None
           full_name: Optional[str] = None
           disabled: Optional[bool] = False

       class UserInDB(User):
           hashed_password: str

       # auth_utils.py
       from passlib.context import CryptContext

       pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

       def verify_password(plain_password: str, hashed_password: str) -> bool:
           return pwd_context.verify(plain_password, hashed_password)

       def get_password_hash(password: str) -> str:
           return pwd_context.hash(password)
       ```
...and so on for subsequent steps.

## Common Issues

Even with good prompting, we might encounter some recurring issues.

* **Hallucinations/Incorrect Code:** The AI invents non-existent APIs, libraries, or provides logically flawed code.
* **Solution:** Be more specific with context. Provide documentation links or code snippets for obscure APIs. Always verify critical generated code. Remember, the AI is predictive, not inherently factual.
* **Generic/Boilerplate Code:** The output is technically correct but lacks the specific nuances of our project or problem.
* **Solution:** Increase specificity in constraints (Step 3) and provide examples (Step 4). Reference existing project conventions.
* **Ignoring Instructions:** The AI omits a key requirement or constraint mentioned in the prompt.
* **Solution:** Rephrase the instruction, emphasize it with bullet points or bold text, or break the prompt into smaller, more focused requests (Step 6). Sometimes, simply stating "Ensure that..." or "Do NOT..." can help.
* **Verbose Output:** The AI provides too much explanatory text and not enough concise code.
* **Solution:** Explicitly ask for "just the code," "no explanations," or "be concise." We can also specify the desired output format (e.g., "only return the Python function").
* **Security Concerns:** AI-generated code might have vulnerabilities (e.g., SQL injection, insecure cryptography, XSS).
* **Solution:** Always review generated code for security best practices. Explicitly ask the AI to "write secure code" or "follow OWASP guidelines," but *never* rely solely on the AI for security. Treat it as a first draft that requires human expertise. This is a significant downside; AI is not a security expert and can easily introduce subtle flaws.

## Next Steps

Mastering prompt engineering is an ongoing process. Here's what to explore next:

* **Experiment with Different Models:** Different AI models excel at different types of tasks. Test your prompts with various assistants (e.g., Copilot, ChatGPT, Claude, open-source models) to find the best fit for specific coding challenges.
* **Advanced Prompt Engineering Techniques:** Dive into concepts like "role-playing" (e.g., "Act as a senior DevOps engineer..."), "persona prompting," or "chain-of-thought prompting" for more complex, multi-step tasks.
* **Integrate AI Output into Your Workflow:** Develop habits to quickly integrate and validate AI-generated code. This might involve setting up automated tests for new features generated by AI or using linting tools to ensure style consistency.
* **Learn About Agentic Workflows:** Explore how to combine multiple AI calls into automated workflows, where the AI can self-correct or break down tasks more autonomously. Tools like Auto-GPT or LangChain are good starting points.
* **Contribute and Share:** Document your most effective prompts. Share them with colleagues or contribute to open-source prompt libraries. Learning from a community can accelerate our understanding.

Ultimately, AI coding assistants are powerful tools that augment our capabilities. By investing time in learning how to communicate effectively with them, we can significantly boost our productivity and focus on higher-level architectural and design challenges, rather than boilerplate or debugging trivial errors. Always remember to review, test, and understand the code the AI provides; it's a co-pilot, not a replacement for engineering rigor.

## Recommended Reading

*Deepen your skills with these highly-rated books. Links go to Amazon — as an affiliate, we may earn a small commission at no extra cost to you.*

- [Co-Intelligence: Living and Working with AI](https://www.amazon.com/s?k=co+intelligence+ethan+mollick&tag=devtoolbox-20) by Ethan Mollick
- [The Pragmatic Programmer](https://www.amazon.com/s?k=pragmatic+programmer+hunt+thomas&tag=devtoolbox-20) by Hunt & Thomas