Agent mode prompts are not Copilot Chat prompts. Chat prompts get answers. Agent mode prompts trigger actions across multiple files and terminal commands. Specificity matters more.

The 30-second version: A good agent mode prompt has a clear goal, explicit scope, and success criteria. A bad agent mode prompt is vague (“fix the tests”), overly prescriptive about method (“edit line 42 then line 87”), or has no way to tell when it’s done. The difference between a 5-minute task and a 45-minute waste of time is often just the prompt.

GitHub’s official documentation covers 8 prompt engineering strategies. This page builds on those strategies with real-world examples, failure analysis, and practical patterns for agent mode specifically.

Why agent mode prompts are different

When you use Copilot Chat, you’re asking for advice or code suggestions. When you use agent mode, you’re delegating a multi-step task. The agent will:

  • Edit multiple files
  • Run terminal commands
  • Read error output and self-correct
  • Iterate until it thinks the task is done

This means your prompt needs to answer three questions the agent will ask itself:

  1. What is the goal? (Not “how should I do it?” — the agent plans the how.)
  2. What is in scope? (Which files? Which tests? Which parts of the codebase?)
  3. How do I know when I’m done? (What does success look like?)

If your prompt doesn’t answer these, the agent will guess. Sometimes it guesses right. Often it doesn’t.

Anatomy of a good agent mode prompt

A good agent mode prompt has four parts:

  1. Goal — what you want done (one sentence)
  2. Scope — what files or areas of the codebase are involved
  3. Constraints — what NOT to do (optional but useful)
  4. Success criteria — how to verify it worked

Example of a well-structured prompt:

Add input validation to the user registration form in src/components/RegisterForm.tsx.
Validate email format and password strength (minimum 8 characters, at least one number).
Write unit tests for the validation logic in src/components/RegisterForm.test.tsx.
Do not modify the existing authentication flow in src/auth/.
Success: the form rejects invalid emails and weak passwords, and all tests pass.

Why this works:

  • Goal is clear: add input validation to one specific file
  • Scope is explicit: RegisterForm.tsx and its test file
  • Constraint is stated: don’t touch src/auth/
  • Success criteria is testable: form behavior + passing tests

Bad prompt patterns (and why they fail)

1. Too vague

Bad:

Fix the tests

Why it fails: Which tests? What’s broken? How should it be fixed? The agent will scan all test files, guess what’s broken, and likely fix the wrong thing.

Good version:

Fix the failing tests in src/utils/date-parser.test.ts.
The date parser is now returning ISO format strings instead of Date objects.
Update the test expectations to match the new return type.
Success: npm test passes with no errors in date-parser tests.

2. Too prescriptive about method

Bad:

Edit line 42 of src/api/users.ts to use async/await, then edit line 87 to remove the callback

Why it fails: You’re micromanaging the how instead of stating the what. Agent mode is better at planning than executing specific instructions. If you already know exactly what to edit, just edit it yourself — it’s faster.

Good version:

Refactor src/api/users.ts to use async/await instead of callbacks.
Keep the same API surface — the function signatures should not change.
Success: all existing tests pass and ESLint shows no promise-related warnings.

3. No success criteria

Bad:

Make the app faster

Why it fails: “Faster” is not measurable. The agent doesn’t know what to optimize or when to stop. It might minify CSS, add caching, refactor algorithms, or do nothing useful.

Good version:

Reduce the initial page load time for the dashboard by lazy-loading the chart library.
Currently Chart.js is loaded on every page. Only load it on /dashboard.
Success: npm run build shows the main bundle is at least 100KB smaller.

The task decomposition question

Should you give agent mode one big task or break it into smaller steps?

General rule: Give it one goal that spans 2–5 related changes. If the task is bigger than that, break it up.

One task (good for agent mode):

Add a new API endpoint /api/users/:id/preferences that returns user preferences.
Create the route handler, add validation middleware, write integration tests.

This is 3–4 file changes, all tightly related. Agent mode handles this well.

Too big (break it up):

Build a complete user preferences system with API endpoints, database schema, 
frontend UI, and email notifications when preferences change.

This is 10+ files across backend, database, and frontend. Break it into separate agent mode sessions:

  1. Database schema + migrations
  2. API endpoints + tests
  3. Frontend UI
  4. Email notifications

Managing context: what to include, what to leave out

Agent mode has a context window. If you give it too much context, it spends tokens on irrelevant details. If you give it too little, it makes wrong assumptions.

Include:

  • Specific file paths (e.g., src/components/Header.tsx)
  • Relevant code snippets (if the agent needs to match an existing pattern)
  • External constraints (e.g., “this API must match the OpenAPI spec in docs/api.yaml”)

Leave out:

  • Generic advice (e.g., “make sure it’s clean and readable”)
  • Background on what the project does (if it’s in your copilot-instructions.md, the agent already has it)
  • Step-by-step instructions (let the agent plan the steps)

Example of a well-contextualized prompt:

Refactor the authentication middleware in src/middleware/auth.ts to use JWT instead of sessions.
Use the jsonwebtoken library (already in package.json).
Match the token validation pattern used in src/middleware/api-auth.ts (check expiry and signature).
Do not modify the existing session-based admin routes — those still use sessions.
Success: all API routes in src/routes/api/ use JWT auth and tests pass.

This gives the agent:

  • The file to change (src/middleware/auth.ts)
  • A reference pattern to follow (src/middleware/api-auth.ts)
  • A constraint (don’t touch admin routes)
  • A success check (tests pass)

This builds on GitHub’s “provide sample code” strategy by showing exactly which file to use as the reference.

Too much context (overkill):

Refactor the authentication middleware in src/middleware/auth.ts to use JWT instead of sessions.
Background: this app is a web-based task manager. We have 5000 users. We're switching to JWT 
because sessions don't scale horizontally. Use the jsonwebtoken library version 9.0.0 which 
supports ES256 signing. Make sure you follow best practices for security. The token should 
have a 1-hour expiry. Store tokens in httpOnly cookies. Don't expose them to JavaScript...

The agent doesn’t need the background. It needs the goal and constraints. Everything else is noise.

Iterating on a prompt: when to re-prompt vs start fresh

If agent mode fails or does the wrong thing, you have two options:

  1. Re-prompt in the same session — useful if the agent got close but missed one thing
  2. Start a new session — useful if the agent went down the wrong path

Re-prompt when:

  • The agent completed the task but missed one edge case
  • The tests failed and you want the agent to fix them
  • You want to add one more small change to the work it just did

Start fresh when:

  • The agent edited the wrong files
  • The agent misunderstood the goal entirely
  • You realize your prompt was unclear and the agent is stuck in a bad direction

Example of a good re-prompt:

The tests are still failing because the date parser doesn't handle null inputs.
Add a null check at the start of the parseDate function.

This builds on the previous work without asking the agent to redo everything.

When to give up and do it yourself:

If you’ve re-prompted twice and the agent is still not getting it right, stop. You’ll finish faster by editing the code yourself. Agent mode is a productivity tool, not a test of patience.

Dive deeper

Related Concepts

📍 Layer 2 — The Agent (prompting patterns) · Back to the AICA Onion

What’s next?

Updated: