Prompting Tips

The agent is good. Your prompts are the bottleneck. After a few thousand sessions, the same patterns separate prompts that produce one-shot solutions from prompts that loop and waste credits. Here they are.

Clear is better than clever

The agent is not your co-worker performing politeness theater. It doesn't get "hints". It does what you literally said — so say what you want.

Bad:  Could we maybe think about improving the homepage a bit?
Good: Replace the hero section with a centered headline,
      subtitle, and a primary CTA button linking to /signup.

Hedging language ("maybe", "think about", "a bit") gets interpreted as ambiguity, which sends the agent into discovery mode reading files it shouldn't need to. That's wasted credits before any code gets written.

Show, don't just tell

When something is broken, the agent's first job is to reproduce your understanding of broken. Save it the guesswork — paste the actual evidence.

Paste error messages verbatim. The full stack trace, console output, or build error. The agent will grep for the file and line.

Good: I'm seeing this in the console:
      "Cannot read property 'map' of undefined at TaskList.tsx:42"
      Fix it.

Paste sample data. If you're rendering an API response, show what the response actually looks like.

The /api/orders endpoint returns:
[{ "id": "...", "lineItems": [...] }, ...]

Build a table that shows id and lineItems[0].name.

Reference the file you're looking at. The agent already knows your viewingPath (the route open in the preview iframe), but for components and helpers, a path is faster than a description.

Good: In src/components/Settings/ProfileForm.tsx, add an avatar upload field
Bad:  Add an avatar upload to the settings page somewhere

One concern per prompt

This is the single most common mistake. People bundle a bug fix, a new feature, and a refactor into one message and then wonder why the result is messy.

Bad:  Fix the navbar overflow on mobile, AND add a search bar,
      AND make the logo a link to home.

The agent will do all three, but it'll also touch more files than necessary because it's optimizing across the whole prompt at once. The diff is harder to review and easier to break. Split it:

Fix the navbar overflow on mobile (it scrolls horizontally below 640px).

Add a search input to the navbar, right of the nav links.

Make the logo in the navbar link to /.

Three small diffs > one tangled diff. Each step gets its own snapshot, so you can revert any one without losing the others.

Reference files explicitly

The agent has a project map and can grep, but explicit paths short-circuit a discovery pass and save you 1-2 credits per prompt. If you know the file, name it.

Bad:   Update the settings page
Good:  Edit src/pages/Settings.tsx — split the General tab into two
       sub-tabs: Profile and Notifications.

When you're not sure of the exact path, name a function or component:

The useAuth hook should also return the user's role.

The agent will grep for useAuth, find the file, and edit there.

Use plan mode for big changes

Anything that touches more than 3-4 files, or anything you'd describe as "refactor", should go through plan mode. The 30 seconds you spend reviewing the plan saves five minutes of untangling a bad diff.

A good signal: if you find yourself prepping a long prompt with bullet points and edge cases, it's a plan-mode prompt. Toggle it on.

When the agent gets stuck

Even good prompts sometimes loop. Three patterns and what to do:

"It can't find the file"

The agent grepped, didn't find what it was looking for, and is now poking around. Tell it the path:

The component is at src/features/onboarding/Steps/EmailStep.tsx
— I saw it earlier in the file tree.

"It keeps looping on the same fix"

You'll see the same files getting edited turn after turn. The agent has the wrong mental model. Stop the run, then re-prompt with a constraint:

The bug is in the reducer, not the component. Look at
src/store/auth.ts and trace what happens on LOGIN_SUCCESS.

"It picked the wrong file"

It's editing src/components/Modal.tsx when you wanted src/components/dialogs/UserModal.tsx. Be specific the next time:

Edit src/components/dialogs/UserModal.tsx (NOT the generic Modal.tsx).

Capitalizing or quoting the wrong path explicitly works because the agent will read your message verbatim.

"It says it's done but nothing changed"

Check the timeline for tool_result events. If you see a lot of read_file and grep_search but no write_file, the agent decided no edit was needed. Either it's right (and you misread the current state) or your prompt was too vague to commit to a change. Re-prompt with a concrete what to change:

Wrong: Make this faster
Right: The TaskList re-renders on every keystroke in the search field.
       Memoize the filtered list with useMemo keyed on search and tasks.

Three good prompts vs. their bad equivalents

Side-by-side reference:

1. Bug fix

Bad:  The form is broken
Good: The signup form at /signup throws "email is required"
      even when I type an email. Console shows
      "TypeError: cannot read 'email' of undefined" in SignupForm.tsx.
      Fix it.

2. New component

Bad:  Add a notifications thing to the header
Good: In src/components/Header.tsx, add a bell icon button
      between the search bar and the user avatar. On click,
      open a Popover (use the existing shadcn Popover) listing
      the user's unread notifications from the
      /api/notifications endpoint. Mark as read on click.

3. Refactor

Bad:  Clean up the api code
Good: src/lib/api.ts has 12 fetch wrappers that all repeat the
      same try/catch and JSON parsing. Extract a single
      fetchJson<T>(url, options) helper and update all 12 callers
      to use it. Don't change the public function signatures.

Notice the pattern: path + concrete action + explicit constraint.

Pre-flight checklist

Before you hit Send on anything non-trivial, ask yourself:

Does the prompt name a specific file or component?
Is there exactly one concern?
Did I paste the error message / sample data if relevant?
Should this be a plan-mode prompt?
Did I hedge with words like "maybe", "a bit", "somehow"?

Five seconds. Saves you minutes.

Overview — what the agent does with your prompt
Plan Mode — when one prompt becomes too much
File Operations — the tools the agent invokes

Prompting Tips

On this page