Prompting Patterns

The #1 skill for AI coding agent productivity is writing clear, specific prompts. This reference covers the core principles, proven patterns, and advanced techniques for getting good results from your agentic CLI.

The Core Principle

Your AI coding agent is not Google. Don’t search — instruct.

The agent has your full project context. It can read files, run commands, and make changes. Tell it what you want done, not what information you need.

Core Prompting Principles

1. Be Specific About the Outcome

Vague: “Review this code” Specific: “Check this code for SQL injection vulnerabilities. Show each vulnerable line and a fixed version.”

Vague: “Write tests” Specific: “Write a test that verifies register() returns failure when the email has no @ symbol.”

Vague: “Fix this bug” Specific: “The discount is calculated wrong for orders over $100. Walk me through the math on line 67.”

2. Provide Context That Changes the Answer

The agent gives different (better) answers when you explain the situation:

Without context:

> Review this function

With context:

> Review this function. It handles credit card refunds and we've
  had duplicate refund bugs in production. Check for idempotency
  and race conditions.

Context that helps the agent:

• What the code does (“this handles user registration”)
• What you’re worried about (“we’ve had auth bypass issues”)
• What constraints exist (“this runs in a lambda with 15s timeout”)
• What patterns to follow (“match the style of the other services”)

3. Constrain the Scope

The agent will do more than you ask if you don’t set boundaries:

> Refactor the report generator

The agent might rewrite the entire file, rename variables, add type annotations, create new classes…

> Extract the daily_summary data processing into a separate method.
  Don't change anything else.

The agent does exactly one thing.

Useful constraints:

• “Only modify this file”
• “Don’t change the public API”
• “Keep all existing tests passing”
• “Don’t add any new dependencies”
• “Just show me the approach, don’t write code yet”

4. Tell the Agent What NOT To Do

Sometimes the most important instruction is what to avoid:

> Write the minimum implementation to pass this test. Don't add
  validation for anything we haven't written a test for yet.

> Refactor this method but don't change any behavior. Even if you
  see a bug, leave it — we'll fix bugs separately.

> Review for security only. Skip style nits, naming suggestions,
  and performance concerns.

5. Start with Clear Intent

Know what you want before asking the agent. Provide context, not just instructions — show existing patterns. Verify output, especially for security, business logic, and data handling.

6. Iterate Rather Than Restart

Tell the agent what to fix, not “try again.” You don’t need to re-explain everything. The agent maintains context within a conversation.

> Good, but use parameterized queries instead of escaping.
  Also, move the validation into a separate method.

Pattern Categories

The “Read Then Act” Pattern

When to use: When the agent needs specific file context before answering.

Example prompt:

> Read src/InventoryService.java and src/InventoryServiceTest.java.
  What code paths are not covered by tests?

Why it works: Telling the agent to read specific files first ensures it has the right context before answering. Without this, it may answer based on assumptions rather than your actual code.

The “Do X Like Y” Pattern

When to use: When you have an existing example of the pattern you want to follow.

Example prompt:

> Add a store_comparison report type. Follow the same structure as
  the daily_summary report.

Why it works: The agent copies patterns extremely well. Point it at a good example and say “do it like this.” This produces more consistent code than describing the pattern from scratch.

The “Plan Then Build” Pattern

When to use: For any non-trivial change where you want to review the approach before committing.

Example prompt:

> Don't write code yet. Describe your approach for adding inventory
  transfer functionality. What files would you modify? What methods
  would you add?

Why it works: Review the plan, adjust it, THEN let the agent build. This prevents large rework cycles when it picks the wrong approach.

The “Fix and Explain” Pattern

When to use: When debugging, especially in unfamiliar code.

Example prompt:

> This test is failing with the error below. Fix it and explain
  what was wrong so I understand the root cause.

  [paste error]

Why it works: Getting the explanation alongside the fix builds your understanding of the codebase. You learn why the bug happened, not just how to fix it.

The “Incremental” Pattern

When to use: For any feature that can be broken into independent steps.

Example prompt:

> Just implement the email validation. Don't touch password
  validation or username checks yet.

Why it works: Small steps = easier to review, easier to understand, fewer mistakes. Each step is small enough to review, test, and commit independently.

Multi-Step Instructions

When to use: When a task has a natural sequence of dependent steps.

Example prompt:

> I need to add a cache layer:
  1. First, read how our other services handle caching
  2. Then describe your approach (don't write code yet)
  3. I'll review your plan before you implement

Why it works: You stay in control at each step. If the agent makes a bad choice in step 1, you catch it before it cascades.

Role-Based Prompting

When to use: When you want the agent to adopt a specific perspective for review or analysis.

Example prompt:

> Review this code as if you're a security auditor performing a
  penetration test. What would you exploit?

> Explain this code as if you're onboarding a new engineer who
  has never seen this codebase before.

Why it works: Assigning a role changes what the agent prioritizes and the depth of analysis it provides.

How Much Context Does the Agent Need?

How Agentic CLI Differs from Chat AI

This means your role shifts from “write code” to “describe intent and review output.” The better you describe what you want, the better the output.

Common Anti-Patterns

Anti-Pattern: The Dump

> I have this code and it's not working, can you help?
  [pastes 200 lines]

Better: Point the agent at the file and describe the specific problem:

> Read src/OrderProcessor.ts. The completeOrder method on line 45
  returns null when it should return the updated order. Why?

Anti-Pattern: The Megaprompt

> Write a complete inventory management system with stock tracking,
  reservations, backorders, transfers, reporting, and admin dashboard.
  Use React for the frontend, Express for the API, and PostgreSQL
  for the database. Include full test coverage.

Better: Break it into steps:

> Let's start with the data model for inventory. I need to track
  stock quantities across multiple warehouses. What tables do I need?

Anti-Pattern: Accepting Without Reading

The agent generates plausible code. Plausible does not equal correct.

Always:

• Read the test before letting the agent implement
• Use /diff after the agent edits files
• Run the tests after changes
• Check that changes match what you asked for

Anti-Pattern: Fighting the Agent

If the agent keeps doing the wrong thing, don’t repeat the same prompt louder:

> No, I said DON'T add error handling!
> I SAID just the validation!
> ONLY THE EMAIL CHECK!!!

Better: Use /clear and start with a more specific prompt:

/clear
> Read line 32-45 of UserRegistrationService.java. Add a single check:
  if the email doesn't contain @, add "Invalid email format" to the
  errors list. Change nothing else in the file.

Using /clear Strategically

/clear resets the agent’s context. Use it:

• Between unrelated tasks
• When the agent seems confused or stuck
• When switching between different parts of the codebase
• After finishing a long multi-step workflow

Don’t use it:

• In the middle of a related sequence of changes
• When the agent needs context from earlier in the conversation

See also: Cookbook for copy-paste recipes