Skip to main content
Mapagam

Writing Effective Prompts for Coding Agents

1. Structuring Task-Oriented Prompts

Element Description Best Practice
Task Definition Clear statement of what needs to be accomplished Use specific, measurable language. Avoid vague terms like "fix" or "improve".
Context Relevant background information or constraints Include environment details, dependencies, and any known limitations.
Expected Output Desired format or result of the task Specify output type (e.g., code, documentation) and any formatting requirements.
Examples Concrete examples or templates to guide the response Provide working code snippets or structure references when possible.

Example: Task-Oriented Prompt


Create a React component that displays a list of users with their names and email addresses. The component should accept an array of user objects as props and render them in a table format.
Note: A well-structured prompt should clearly define the task, provide necessary context, and specify the expected output format to ensure accurate and efficient responses from AI agents.

2. Providing Relevant Context in Prompts

Context Type Description Best Practices
Problem Statement What is the specific issue or goal? Clearly define what needs to be solved or achieved
Codebase Overview Language, frameworks, structure Include relevant tech stack and project scope
Expected Output Desired result format Specify output type (e.g., function, class, fix)
Constraints Limitations or rules to follow List any restrictions (e.g., no external libraries)

Example: Prompt with Context


A React component that displays a list of users with their names and email addresses. The component should use the Material-UI library for styling and must not use any external libraries beyond React and MUI. The data should be fetched from a mock API endpoint.
Note: Including context helps the AI understand the environment and requirements better, leading to more accurate responses.

3. Using Few-Shot Examples in Prompts

Few-shot examples are concrete code snippets or task demonstrations included within a prompt to guide an AI agent in generating desired outputs. They help the model understand context, structure, and expected behavior more effectively.

Example Type Description Use Case
Code Generation Example showing how to write a function in a specific language Helps the model understand syntax and structure for code generation
Task Completion Example of a completed task with input/output Guides the model to replicate similar workflows
Error Handling Example demonstrating how to handle errors or edge cases Teaches the model to anticipate and manage exceptions

Example: Code Generation with Few-Shot

// Prompt: Write a function to calculate the area of a circle.
// Example 1:
function calculateCircleArea(radius) {
    return Math.PI * radius * radius;
}

// Example 2:
function calculateRectangleArea(length, width) {
    return length * width;
}

// Now generate a function for triangle area.

Example: Task Completion with Few-Shot

// Prompt: Convert a string to title case.
// Example 1:
const input1 = "hello world";
const output1 = "Hello World";

// Example 2:
const input2 = "javascript is awesome";
const output2 = "Javascript Is Awesome";

// Now convert this string:
const input3 = "openai gpt models";
Note: Few-shot examples should be relevant and concise. Avoid including too many examples, as they may confuse the model or increase token usage unnecessarily.

4. Breaking Down Complex Tasks

Workflow: Decomposing Complex Coding Problems

  1. Identify the Core Problem: Clearly define what the end goal is. Example: "Implement a real-time chat application with user authentication."
  2. Break into Subtasks: Divide the problem into manageable, atomic tasks. Example: "1. Set up backend server. 2. Implement user login API. 3. Create WebSocket connection handler."
  3. Define Inputs and Outputs: Specify what data or actions each subtask will consume and produce. Example: "User login API consumes email/password, returns JWT token."
  4. Assign to Coding Agents: Send each subtask as a distinct prompt to an AI agent. Example: "Create a Node.js endpoint that validates user credentials and returns a JWT."
  5. Iterate and Integrate: Combine results, test integration, refine prompts if needed.
Task Type Description Example Prompt Agent Focus
Backend Setup Initial server configuration and dependencies Set up a Node.js server with Express and CORS enabled. Infrastructure
Authentication User login, session management, token handling Implement JWT-based authentication with bcrypt password hashing. Security
Real-time Communication WebSocket handling and message broadcasting Create a WebSocket server that broadcasts messages to connected clients. Networking

Best Practices for Task Decomposition

  • Each task should be atomic and testable.
  • Use clear, unambiguous language in prompts to avoid misinterpretation.
  • Define success criteria for each subtask to guide agent behavior.
  • Ensure data flow clarity between tasks to prevent integration issues.

5. Specifying Output Format Requirements

Format Type Description Examples
JSON Structured data format with key-value pairs, ideal for configuration or API responses 
{
  "name": "user",
  "age": 30
}
Markdown Lightweight markup language, useful for documentation or code comments 
# Title
## Section
- Item 1
- Item 2
HTML Markup language for web content, suitable for generating UI components 
<div class="container">
  <p>Hello World</p>
</div>
YAML Human-readable data serialization format, often used for configuration files 
database:
  host: localhost
  port: 5432

Example: JSON Output Format

// Example prompt requesting JSON output
{
  "prompt": "Generate a JSON object with user details",
  "output_format": "JSON"
}

Example: Markdown Output Format

// Example prompt requesting Markdown output
{
  "prompt": "Write a README in Markdown for a Node.js project",
  "output_format": "Markdown"
}
Note: When specifying output format, ensure the prompt includes a clear instruction like "Return your response in JSON/YAML/Markdown format" to guide the agent.

6. Iterating on Prompt Refinements

Prompt Element Description Best Practice
Clarity Unambiguous instructions Use specific verbs and avoid vague terms like "fix" or "improve"
Context Relevant background information Include code snippets or error messages for better understanding
Constraints Limitations or requirements Specify output format (e.g., JSON, markdown) and length limits
Examples Concrete use cases or templates Provide working examples to guide desired output structure

Example: Initial vs Refined Prompt


Create a React component that displays a list of users.


Create a React component that displays a list of users with the following features:
- Accepts an array of user objects
- Each user has name, email, and avatar URL
- Displays users in a grid layout
- Includes a search filter by name
- Uses Material UI components for styling

Workflow: Prompt Iteration Process

  1. Start with a basic prompt that defines the task
  2. Run the prompt through the AI agent and observe results
  3. Analyze gaps or misinterpretations in output
  4. Refine prompt with more specific details or constraints
  5. Iterate until desired output is consistently achieved

Key Tips for Prompt Refinement

  • Start Simple: Begin with a minimal working prompt before adding complexity
  • Test Incrementally: Add one constraint or example at a time
  • Document Changes: Keep notes on what changes improved results
  • Use Templates: Create reusable prompt structures for similar tasks

7. Avoiding Ambiguous Instructions

Instruction Type Example of Ambiguous Clear Alternative Improvement Notes
Vague task phrasing Fix the code Refactor this function to use a more efficient sorting algorithm Specify the exact problem or desired outcome
Missing context Make it better Optimize this React component to reduce re-renders and improve performance Include relevant details like performance constraints or UI behavior
Unclear scope Improve the app Add dark mode support to the login page and ensure it persists across sessions Define specific features or modules to target

Example: Ambiguous vs. Clear Prompt


Fix the code to make it faster.


Optimize the following function to reduce time complexity from O(n^2) to O(n log n).
Note: Ambiguous instructions often lead to misinterpretation and suboptimal results from AI agents.
Warning: Vague prompts can cause the AI to make assumptions that don't align with your actual intent.

8. Using System Prompts Effectively

Element Description Best Practices
Role Definition Defines the agent's role or persona Be specific and avoid vague roles like "developer". Use precise roles like "Senior JavaScript Developer" or "Full Stack Engineer"
Task Instructions Describes what the agent should accomplish Clearly state the desired outcome, not just the steps. Example: "Implement a React component that fetches and displays user data from an API"
Context Provides background information or constraints Include relevant project context, technology stack, and any specific requirements (e.g., "Use TypeScript with React hooks")
Output Format Specifies how the response should be structured Define the expected output format (e.g., "Return code in a markdown block with JavaScript syntax highlighting")

Example: Effective System Prompt


<system>
You are a Senior JavaScript Developer specializing in React and Node.js. Your task is to implement clean, efficient, and well-documented code solutions.

Context:
- Project uses React 18 with TypeScript
- Backend is Node.js with Express
- All code must follow Airbnb style guide

Output Format:
Return all code in markdown blocks with appropriate language syntax highlighting.
</system>
Note: System prompts should be concise yet comprehensive. Avoid overloading with unnecessary details that may confuse the agent.

System Prompt vs User Prompt

  • System Prompt: Sets the agent's role, context, and expectations
  • User Prompt: Provides specific instructions or queries for the agent to execute

Best Practices for Crafting System Prompts

  1. Define Clear Roles: Specify the agent's expertise and responsibilities
  2. Provide Relevant Context: Include project constraints, technologies, and coding standards
  3. Specify Output Format: Indicate how responses should be formatted (e.g., markdown, JSON)
  4. Use Examples: Include sample outputs or code snippets to guide the agent
  5. Iterate and Refine: Continuously improve prompts based on agent performance

9. Handling Multi-Turn Prompt Context

Aspect Description Best Practices
Context Retention Agents must retain context from previous turns to maintain state Use explicit references to prior steps or variables
State Management Managing session state across multiple prompt exchanges Implement clear state reset mechanisms when needed
Prompt Memory Storing and retrieving relevant past prompts or responses Limit memory size to prevent overflow; prioritize recent interactions

Example: Multi-Turn Prompt Flow

// First turn
const firstPrompt = "Write a function to calculate Fibonacci numbers";

// Second turn (with context)
const secondPrompt = `Based on our previous discussion, implement the function with memoization.
Return the result for fib(10).";

// Third turn (building on previous)
const thirdPrompt = `Now modify the function to handle negative inputs.
Use the same memoization approach.";
Note: Ensure that each new prompt includes sufficient context to allow the agent to understand and respond appropriately without requiring external state lookup.

Key Considerations for Multi-Turn Prompts

  • Each prompt should reference prior context clearly
  • Limit the number of previous turns to maintain clarity
  • Reset session state when necessary to avoid confusion
  • Validate that the agent correctly interprets multi-turn instructions

Was this article helpful?

Related Cheat Sheets