Prompting

The agent is capable, but clear requests still produce better results. These patterns help you get accurate diffs, fewer wrong turns, and less back-and-forth.

Be specific about the outcome

State the end state you want, not just the action. The agent plans better when success criteria are explicit.

Give context and constraints

• Point to the relevant files or symbols (src/lib/cart.ts, CheckoutService#create).
• Name constraints up front: "don't change the database schema", "keep it backwards compatible".
• State your conventions explicitly ("use our logger", "no default exports") so the agent follows them.
• Mention the surface: desktop-only fix vs. change that must work in cloud agents too.

Constraint checklist

Work in increments

For large efforts, ask the agent to outline a plan first, then implement step by step. Review each diff before moving on.

1. Ask for a plan

   "Outline how you would split the auth refactor into PR-sized steps. Don't change code yet."

2. Approve one step

   "Implement step 1 only. Stop after the diff is ready for review."

3. Verify

   Run tests or spot-check behavior yourself, then proceed to the next step.

4. Adjust

   If a step went sideways, narrow scope: "Revert the API change; keep only the extraction."

Prompt patterns that work

Feature work

Add a "duplicate task" action to the task detail page.
 
Requirements:
- Button in TaskActions.tsx, visible to project members
- POST /api/tasks/:id/duplicate, copy title/description/assignee
- Navigate to the new task on success
- Add a test in task-actions.test.tsx
 
Don't change the task list API or database schema.

Refactors

Extract shared date formatting from apps/web and apps/docs into packages/ui/date.ts.
 
- Move formatRelative and formatAbsolute unchanged
- Update imports; no behavior changes
- Run typecheck in both apps when done

Code review follow-up

Address review comments on PR #412:
 
1. Use the existing retry helper in lib/http.ts instead of inline loops
2. Add error boundary around ChartPanel (see Comment on line 88)
3. Rename getData -> fetchChartData for consistency
 
Files are already in the branch; don't scope outside this PR.

Investigating bugs

When something is broken, give the agent the symptom, how to reproduce it, and any logs or stack traces you already have:

The /checkout endpoint returns 500 intermittently.
Repro: POST /checkout with an empty cart.
Stack trace: TypeError: cannot read 'total' of undefined at cart.ts:42
Expected: 400 with { error: "empty_cart" }

The more concrete the reproduction steps and evidence, the faster the agent can narrow down the cause before proposing a fix.

1. Symptom

   What breaks, for whom, and since when (if known).

2. Repro

   Exact steps, inputs, and environment (local vs. staging).

3. Evidence

   Stack traces, logs, network responses, screenshots of errors.

4. Hypothesis (optional)

   "Might be related to the cart merge change in #398" — helps but is not required.

Using plugins and MCP in prompts

When you have plugins installed, you can reference their capabilities directly:

Using the Linear plugin: create an issue for the checkout bug with repro steps from above.
Link it to project ENG and assign to me.

Query Datadog for 5xx rate on checkout-api in the last hour.
Summarize spikes and correlate with deploy times before suggesting a fix.

The agent chooses tools; you approve sensitive calls. Naming the integration avoids vague "check the logs" requests when you want a specific system queried.

Subagent delegation prompts

When you ask the agent to delegate with the task tool, write a self-contained brief — subagents cannot ask follow-up questions and must finish in one pass. Include file paths, success criteria, and what to return in the summary. The runtime allows subagents up to 100 steps versus 50 for the main thread, but they still work best on bounded scopes like "research how auth middleware is wired" or "list all callers of CheckoutService." Avoid chaining multiple subagents for one small fix; reserve delegation for research or refactors that would clutter your main conversation.

What to avoid

Quick reference