# Effective Agent Prompting

> How to communicate with AI coding agents for maximum productivity. Patterns that work across Claude, Cursor, Windsurf, Copilot, and any agentic tool.

## When to Use

- Every interaction with an AI coding agent
- When agents aren't doing what you expect
- When you want to minimize back-and-forth
- When working on complex multi-step tasks

## The Pattern

Effective agent prompting follows a **context → intent → constraints** structure. The more precise you are upfront, the less correction you need afterward.

## Prompting Principles

### 1. State the goal, not just the action

**Bad:** "Add a function to auth.ts"
**Good:** "Add a `refreshToken()` function to auth.ts that takes an expired JWT, validates the refresh token from the cookie, and issues a new access token. Follow the existing pattern in `loginUser()`."

### 2. Reference existing patterns

Agents work best when they can mimic existing code:

**Bad:** "Create a new API endpoint for notifications"
**Good:** "Create a notifications module following the same pattern as `src/modules/auth/` (types.ts → repository.ts → routes.ts). Use Zod for validation."

### 3. Specify scope explicitly

**Bad:** "Fix the auth bug"
**Good:** "The login endpoint returns 500 when email has uppercase letters. Root cause is in `src/modules/auth/repository.ts` — the email comparison is case-sensitive. Fix just the comparison, don't refactor anything else."

### 4. Use "don't" constraints

Agents are eager to help and may over-engineer. Constrain them:

- "Fix only this function, don't refactor the file"
- "Add the test, don't modify the implementation"
- "Just answer the question, don't write code"
- "Minimal change — single-line fix if possible"

### 5. Give verification commands

Tell the agent how to verify its work:

"After making changes, run `npm test` and `npm run typecheck` to verify nothing broke."

### 6. Batch related requests

Instead of 5 separate messages:

**Bad:**

1. "Add field X to types.ts"
2. "Update repository.ts to handle X"
3. "Add route for X"
4. "Write tests for X"
5. "Update the docs"

**Good:** "Add a `deleteUser` endpoint to the users module. This needs: types (DeleteUserSchema), repository method (soft delete with `deletedAt` timestamp), route (DELETE /users/:id, admin-only), and tests (happy path + unauthorized + not found). Follow the pattern in `createUser`."

## Task Complexity Tiers

### Tier 1: Quick fixes (1 message)

"The import on line 42 of auth.ts is wrong — it should be `./repository.js` not `./repository`"

### Tier 2: Feature implementation (1-2 messages)

"Add a health endpoint to the service that returns `{ status: 'ok', service: 'notifications', requestId: request.id }`. Register it in server.ts."

### Tier 3: Multi-file features (plan first)

"I need to add a notifications module to platform-service. Before writing code, outline the plan: which files to create, what endpoints, what Cosmos container. Then implement."

### Tier 4: Cross-repo work (workflow-driven)

"Run `/production-readiness` across all repos and fix any issues found."

## Patterns for Specific Scenarios

### Debugging

```
The /api/users endpoint returns 500.
Error in logs: "Cannot read property 'id' of undefined"
I think the issue is in repository.ts around line 80.
Find the root cause and fix it. Don't add workarounds.
```

### Code review

```
Review src/modules/auth/routes.ts for:
1. Security issues (input validation, auth checks)
2. Error handling gaps
3. Missing edge cases
Don't make changes, just list findings.
```

### Refactoring

```
Extract the duplicated Cosmos client setup from:
- admin-dashboard/src/lib/cosmos.ts
- user-dashboard/src/lib/cosmos.ts
- tracker-dashboard/src/lib/cosmos.ts

Into a shared package at packages/cosmos/.
Keep the existing API surface. All 3 consumers should work after migration.
Verify with typecheck in each dashboard.
```

### New project setup

```
Create a new Fastify service called "notification-service" in services/.
Follow the exact same structure as platform-service:
- src/server.ts (app factory)
- src/lib/config.ts (Zod schema)
- src/lib/cosmos.ts (container init)
- src/modules/notifications/ (types, repo, routes)
Port 4007, health endpoint, JWT auth.
```

## Anti-Patterns

- **"Make it better"** — Vague. Better how? Faster? More readable? More secure?
- **"Rewrite this file"** — Agents should make minimal edits, not rewrite
- **Assuming context** — Don't assume the agent remembers last conversation (it might, via memory, but be explicit)
- **Not verifying** — Always ask for test/typecheck after changes
- **Micro-managing tool calls** — Let the agent choose its tools; focus on the outcome
- **Asking for multiple unrelated things** — One task per conversation, or explicitly separate them

## Environment-Specific Tips

### Terminal commands

Some environments have quirks. Establish these early:

- "Keep all commands on a single line — multi-line doesn't work in my terminal"
- "Append `| pbcopy` to commands so I can paste output back"
- "Don't run destructive commands without asking first"

### Large codebases

- "Search the codebase first before making assumptions"
- "Read the existing implementation before proposing changes"
- "Check AGENTS.md for project conventions"

## Editor-Specific Notes

| Editor          | Prompting Style                                                                  |
| --------------- | -------------------------------------------------------------------------------- |
| **Windsurf**    | Chat panel. Can run commands, edit files, search. Use todo_list for plans        |
| **Claude Code** | Terminal-based. Very autonomous. Good at multi-file changes                      |
| **Cursor**      | Inline (Cmd+K) for quick edits, chat for complex tasks. Use @-mentions for files |
| **Copilot**     | Best for completions and inline suggestions. Chat for explanations               |
| **Aider**       | Git-aware. Specify which files to edit upfront with `/add`                       |

## Related Skills

- [06 — Multi-Session Continuity](./06-multi-session-continuity.md)
- [07 — Systematic Debugging](./07-systematic-debugging.md)
- [08 — Test-Driven Bug Fixing](./08-test-driven-fixing.md)
