Cursor AI Prompting Guide

When an AI can inspect a repository, a better prompt is usually narrower—not broader. Give Cursor the files, boundaries, constraints, and validation that matter, then ask it to analyze the relevant area before it edits.

Repository-aware tools can uncover useful context, but they can also make a change look more certain than it is. The goal is to turn repository access into evidence, not permission to alter every related file.

Cursor’s context reference documentation describes attaching repository material such as files, folders, git changes, and linter errors. Use the context controls available in your version to point the assistant at the smallest useful set of evidence.

For example, instead of this:

Fix the slow dashboard.

write:

Investigate the dashboard loading delay for signed-in users.

Scope: Start with the dashboard route, its data-loading hook, and the one card
that shows a loading skeleton too long. Use the current profile provider and
existing performance instrumentation as context.

Outcome: Identify whether the delay is fetch time, unnecessary rendering, or a
state transition. Propose the smallest measurable improvement.

Constraints: Preserve authorization behavior, localized UI, and existing
loading feedback. Do not add a cache or a new state library without evidence.

Before editing, summarize the execution path and state what you would measure.

The prompt gives the assistant a route into the repository without treating every dashboard file as changeable.

Repository context is most valuable at the start of a task. Ask Cursor to:

1. trace the relevant data or control flow;
2. identify the code that owns the behavior;
3. distinguish confirmed facts from assumptions;
4. list the smallest files likely to change;
5. explain what test or observation will prove the fix.

This is especially important when the request touches a shared provider, a global component, authentication, payments, or navigation. Those areas often have call sites that a local change cannot safely ignore.

“Update the notifications feature” is still broad if the feature spans UI, persistence, workers, and settings. Add a file or boundary constraint:

Change the notification preference form only. The client writer is the source
of truth for preference updates; do not add another writer or alter the
scheduler in this task.

Inspect the form, the typed client writer, and their direct tests. If the
reported bug requires a backend change, stop and explain the evidence instead
of expanding the scope.

This does not prevent the assistant from finding a real cross-boundary issue. It makes the expansion explicit and reviewable.

Repeated project context belongs in the repository’s instructions or rules, not in every chat prompt. Use durable project guidance for invariants such as:

• static-export or deployment boundaries;
• locale requirements;
• test commands and code style;
• ownership rules for shared state;
• paths where special review is required.

Keep the task prompt focused on the specific problem and acceptance criteria. If project instructions and the prompt disagree, resolve the conflict in the request instead of hoping the assistant guesses which one matters.

Large requests are hard to validate because a broad diff hides cause and effect. Break work into checkpoints:

First inspect and explain the current form submission path. Do not edit files.

After the analysis, implement only the validation-state fix and add its focused
test. Do not refactor neighboring form components yet.

Run the relevant test and summarize the diff. If it passes, propose a separate
follow-up for shared cleanup.

This pattern makes the assistant’s work easier to review and makes rollback practical if the hypothesis was wrong.

An AI coding assistant should not choose “looks correct” as the completion rule:

Acceptance criteria:
- the existing behavior still works for a successful submission;
- the reported invalid state becomes reachable and visible;
- keyboard and screen-reader feedback remain intact;
- the targeted test passes and a failure would have caught the old bug.

Validation: run the focused test suite, type check, and describe any manual
browser step that covers behavior the test cannot observe.

Ask it to identify a missing test rather than inventing confidence from a green compilation result.

Use the reusable prompt structure in how to write better AI prompts, then add Cursor-specific scope in the same message:

• name the @ files, folders, diff, or linter output the agent should read first;
• state which paths are out of scope unless evidence forces an expansion;
• ask for analysis before edits when the task touches shared providers, auth, payments, or navigation.

See prompt engineering for developers for patterns by task type. For a change that is mostly structural, use these prompt templates for refactoring code.

If a repository task involves scripts or terminal output, confirm the real command behavior before changing it. Practice command-line workflows in the browser to turn an assumed output into an observable test case.