Cursor AI Tutorial for Beginners: A Complete Guide
![]() |
| Cursor AI Tutorial for Beginners: A Complete Guide |
THE COMPLETE BEGINNER’S GUIDE
Cursor AI
Tutorial for
Beginners
Install Cursor, write better prompts,
build a working app, debug with confidence, and keep control of your code and
privacy.
12
chapters Hands-on project Best practices Cursor vs VS Code vs Copilot
Contents
Click any title to jump to that section.
1.3.
Who Should Use Cursor AI?
2.
How to Download and Install Cursor AI
2.2. Installing Cursor on Windows,
macOS, and Linux
2.3. Creating an Account and Signing
In
2.4. Importing VS Code Settings
3. Understanding the Cursor AI
Interface
3.1. File Explorer and Code Editor
3.2. AI Chat Panel and Agent Mode
3.4. Essential Keyboard Shortcuts
4. Cursor’s Core Features Explained
4.2.
Inline Editing with Ctrl/Cmd + K
4.3. Chat vs. Agent Mode: When to Use
Each
4.4. Using @ to Add Files and Context
4.5. Cursor Rules: Teaching Cursor
Your Preferences
5.
How to Use Cursor AI for the First Time
5.1. Creating Your First Project
5.2. Opening an Existing Project
5.3. Writing Your First AI Prompt
5.4. Reviewing and Running Generated
Code
6. How to Write Code with Cursor AI
6.1. Generating Code from Natural
Language
6.2. Writing Python, JavaScript, and
HTML
6.3. Editing and Modifying Existing
Code
6.4. Writing Effective Coding Prompts
7. Hands-On Project: From Idea to
Working App
7.1. Planning the Project with Cursor
7.3. Testing and Fixing Issues
7.4. Final Result and Next
Improvements
8.
How to Debug and Improve Code with Cursor AI
8.2. Making Sense of Error Messages
8.3. Refactoring Without Breaking
Things
8.4. Testing AI-Generated Code
9. Advanced Ways to Use Cursor AI
9.1. Working with Large Projects
9.2. Understanding Project
Architecture
9.3. Finding Duplicate Code and
Performance Issues
9.4. Generating Documentation and
README Files
10. Cursor AI Best Practices and
Common Mistakes
10.1. Writing Clear and Effective
Prompts
10.2. Common Beginner Mistakes (with
Examples)
10.3.
Reviewing AI-Generated Code and Avoiding Overdependence
10.4. Using Git to Protect Your Work
10.5. Code Security and Privacy
(Including Privacy Mode)
10.6. Tips to Improve Productivity
11. Cursor AI vs. VS Code vs. GitHub
Copilot
11.2. Features and Capabilities
Comparison
11.3. Which Tool Should You Choose?
12. Frequently Asked Questions About
Cursor AI
12.2.
Can Beginners Use Cursor AI?
12.3. Which Programming Languages
Does Cursor AI Support?
12.4. Does Cursor AI Replace
Programmers?
12.5. Is Cursor AI Suitable for
Professional Development?
12.6.
Is Cursor AI Safe to Use?
Getting Started and Installation
Cursor Interface and Core Features
Coding, Debugging, and Working with
Projects
Version Control, Extensions, and
Development Tools
Pricing, Privacy, and Security
GitHub Copilot and Tool Comparison
AI can help you
write code, but knowing how to use it well is what makes the difference. For
beginners, the real challenge is not generating code. It is understanding the
results, fixing errors, and building projects that actually work.
Cursor AI is an
AI-powered code editor built on the foundation of Visual Studio Code. It helps
you write, edit, debug, and understand code directly within your project, using
natural-language instructions and AI-assisted features.
In this Cursor AI tutorial for beginners, you will
learn how to:
● Install and set up Cursor on Windows, macOS, or Linux.
● Use Tab, Inline Edit, Chat, and Agent Mode.
● Write effective prompts and review AI-generated code.
● Build a working application step by step.
● Debug errors and improve code quality.
● Avoid common mistakes and protect your code and privacy.
● Compare Cursor with VS Code and GitHub Copilot.
This guide is
written for beginners, students, and anyone who wants to build software with
AI. No previous programming experience is required. All you need is curiosity
and a willingness to experiment.
Follow the
practical examples as you read, and test every piece of code instead of
accepting AI suggestions without review. By the end, you will have built a
working project and know how to use Cursor AI while keeping control of your
code.
"Short on time? Watch this 4-minute overview of Cursor AI first, then continue with the full guide below."
Let’s
start by exploring what Cursor AI is and how it works.
Cursor AI is a
code editor with artificial intelligence built in. You write code as you would
in any other editor, but you can also ask the AI to generate, explain, or
modify code directly within your project.
Unlike a
separate chatbot, Cursor works with your project files and relevant code
context. This reduces the need to copy code into another application and paste
the results back into your editor.
Cursor is
developed by Anysphere and built on Visual Studio Code (VS Code). If you have
used VS Code, its interface will feel familiar, with a code editor, file
explorer, built-in terminal, and support for extensions. If you are new to
coding, Section 3 will introduce the main parts of the interface.
Cursor adds
AI-powered tools that let you describe coding tasks in plain English. For
example, you can ask it to:
● Create a simple contact form for a website.
● Explain what a Python function does, line by line.
● Investigate why your code produces an error.
Depending on
the task and the feature you use, Cursor can suggest a small edit, modify a
selected block of code, or help make changes across multiple files.
Imagine you
have a button on a webpage that does nothing. You can ask Cursor to make the
button display an alert saying “Hello.” It can propose the necessary code
changes, which you can then accept, modify, or reject.
|
KEY IDEA Cursor suggests changes; you
decide what to keep and test. |
Cursor combines
three elements to assist with coding tasks: an AI model, information from your
project, and your instructions.
The AI
model. Cursor provides access to AI models from different providers, as
well as models developed by Cursor. Available models and their capabilities can
change, so check the model selector in the application for the current options.
Project
context. Cursor can use selected code, referenced files, and information
from the rest of your project to help interpret your request. You can provide
additional context using the @ symbol, which is explained in Section 4.
Your review.
AI-generated code needs to be checked before you rely on it. A typical workflow
involves five steps:
1.
Describe the task.
Explain what you want to create, change, or fix.
2.
Provide context.
Select the code or reference the files involved.
3.
Review the changes.
Check the proposed edits before accepting them.
4.
Run and test.
Verify that the code behaves as expected.
5.
Refine the result.
Explain any remaining problems and request further changes.

Cursor offers
different features for different tasks:
● Tab: Suggests code completions as you type.
● Inline Edit: Helps modify selected code using
instructions.
● Chat: Lets you ask questions and discuss code.
● Agent Mode: Helps handle more complex tasks involving
multiple steps or files, depending on the task and available permissions.
Section 4
explains these features in detail.
|
WATCH OUT Keep in mind that AI-generated
code can contain errors, use unsuitable approaches, or fail in situations you
have not tested. Clear instructions, good context, and careful testing help
you get better results. |
Cursor can be
useful for different types of users:
● Beginners: Ask questions, explore programming concepts,
and understand unfamiliar code.
● Students: Practice programming and study how proposed
solutions work instead of copying them without understanding.
● Web developers: Create and modify websites using HTML,
CSS, and JavaScript.
● Python users: Write scripts, automate repetitive tasks,
and investigate errors.
● Experienced developers: Explore unfamiliar codebases,
refactor existing code, and speed up routine tasks.
You do not need
to be an experienced programmer to start using Cursor. However, learning basic
programming concepts will help you evaluate its suggestions and identify
potential problems.
Cursor may not
suit every situation. Consider these limitations before getting started:
● Cursor is its own VS Code-based editor. If you or your team rely
on another environment, such as JetBrains IDEs or Visual Studio, check whether
switching editors fits your workflow.
● If you need to work entirely offline, remember that Cursor’s AI
features rely on online services.
● If you work with confidential or company-owned code, check your
organization’s policies and review Cursor’s privacy settings before using it.
Section 10.5 covers this in more detail.
Cursor offers
several practical benefits throughout the coding process:
● Faster coding: Generate code and handle repetitive tasks
with AI assistance (Sections 4 and 6).
● Simpler editing: Modify existing code using
natural-language instructions (Section 4).
● Code explanations: Ask questions about functions, files,
and programming concepts (Sections 4 and 8).
● Debugging assistance: Investigate errors and explore
possible solutions (Section 8).
● Project-wide assistance: Work with context from multiple
files (Section 9).
● Learning support: Experiment with code and ask for
explanations of proposed solutions.
|
NOTE How much you benefit depends on
the task, the quality of your instructions, and the features available on
your plan. Cursor is a coding assistant, not a guarantee of correct or secure
software. Reviewing and testing your code remain essential. |
Now
that you know what Cursor AI is and how it works, let’s move on to downloading
and installing it.
Installing
Cursor takes only a few steps. It is available for Windows, macOS, and Linux.
This section explains how to download and install it, sign in, and import your
VS Code settings if you already use that editor.
Always download
Cursor from the official download page. Since a code editor can access your
project files, downloading it from the official source is important.
1.
Visit the official
Cursor download page.
2.
Find the options for
your operating system.
3.
Select the version that
matches your computer and processor.
4.
Wait for the download
to finish.
If you are
unsure which version to choose, check your computer’s system information:
● Windows: Open Settings → System → About and check the
System type entry.
● macOS: Open the Apple menu, select About This Mac, and
check whether your computer uses an Apple chip or an Intel processor.
● Linux: Open a terminal and run uname -m.
A result of x86_64 means a standard 64-bit processor, and aarch64
means an ARM processor. Then choose a package that matches your distribution.
After
downloading the installer, follow the instructions for your operating system.
Windows
1.
Open the downloaded
installer.
2.
Follow the on-screen
instructions. The default options are suitable for most users.
3.
If offered, choose
whether to add Cursor to the right-click menu or make it accessible from the
terminal.
4.
Launch Cursor from the
Start menu or desktop shortcut.
macOS
1.
Open the downloaded
.dmg file.
2.
Drag the Cursor icon
into your Applications folder.
3.
Open Cursor from
Applications.
4.
If macOS asks you to
confirm opening an app downloaded from the internet, confirm to continue.
Linux
Cursor offers
Linux packages in formats such as .deb, .rpm, and AppImage. Choose a format
compatible with your distribution and processor architecture.
● Debian- and Ubuntu-based distributions: Use the .deb
package when available.
● Fedora- and RHEL-based distributions: Use the .rpm
package when available.
● AppImage: Use this portable format if it is available for
your system.
To launch an
AppImage, first navigate to the folder containing the downloaded file. Then
make it executable and run it, replacing the example filename with the actual
one:
|
TERMINAL chmod +x Cursor-*.AppImage ./Cursor-*.AppImage |
If the AppImage
reports a missing FUSE library (libfuse.so.2), install it first. On Ubuntu and
similar systems, this usually works:
|
TERMINAL sudo apt install libfuse2 |
Package names
and commands vary between distributions and versions, so consult the official
Cursor installation guide for current instructions.
After
installation, open Cursor and follow the initial setup screens.
1.
Launch Cursor.
2. Sign in with your
Cursor account or create one if necessary.
3.
Choose your preferred
setup options, such as keyboard shortcuts.
4.
Review the available
privacy settings before opening sensitive projects. Section 10.5 explains these
options in detail.
If you already
use VS Code, choosing familiar keyboard shortcuts can make the transition
easier.
Cursor’s AI
features, available models, and usage limits depend on your account and plan.
Check the official Cursor website for current pricing and plan details. Section
12.1 discusses the cost in more detail.
|
TRY IT NOW Before continuing, open a project
folder using File → Open Folder, or the equivalent option shown in your
version of Cursor. Check that the folder’s files appear in the file explorer. |
If you already
use Visual Studio Code, Cursor provides ways to import compatible settings and
extensions. This can help you continue working with a familiar setup.
Depending on
the import options available in your version, you may be able to transfer:
● Extensions
● Themes
● Keyboard shortcuts
● Editor settings
Look for the
import option during the initial setup or in Cursor’s settings. Follow the
on-screen instructions to complete the process.
Because Cursor
is based on VS Code, many extensions are compatible, although some may behave
differently or may not be available. If an extension does not work, check for
an alternative in Cursor’s extension marketplace.
If you have
never used VS Code, you can skip this step and continue with Cursor’s default
settings. You can also keep VS Code installed alongside Cursor.
With
Cursor installed and ready, you can now explore its interface and learn where
to find the tools used throughout this guide.
The first time
you open Cursor, the screen can feel crowded. There is a sidebar, editor tabs,
an AI panel, a terminal, and icons you cannot name yet. You do not need to
learn all of it today. What matters is how a few main tools fit together, and
how to use them without losing control of your project.
For now, focus
on four areas: the File Explorer, the Code Editor, the AI panel, and the
integrated terminal. Once these make sense, the rest of the interface becomes
easy to pick up.

The File
Explorer lists the files and folders in your project. The Code Editor shows
whichever file you open and lets you read and change it.
Here is a small
website with three files:
|
my-website/ ├── index.html ├── style.css └── script.js |
Each file has
one job:
● index.html defines the structure and content of the
page.
● style.css controls how it looks: colors, spacing,
layout.
● script.js adds interactive behavior with JavaScript.
Click
index.html and it opens in the editor. From there you can read it, edit it
yourself, or ask Cursor to explain it.
Knowing where
your files are is the easy part. The real skill is knowing which files matter
for the change you want.
Say a button looks wrong. Its appearance
probably lives in CSS, and its behavior in JavaScript. If you ask Cursor to
“fix the button,” it has to guess what is wrong and may change more than you
wanted. Compare that with this:
|
PROMPT In index.html and style.css, find the button
labeled “Contact Us.” Make its background blue and keep its size, position,
and behavior unchanged. Do not modify unrelated files. |
That request
names the files, the change, and the limits. The AI has almost nothing left to
guess.
Open the
folder, not just a file. Choose File → Open Folder and select your whole
project. This lets you and the AI work across related files. It does not mean
every file is sent with every request, so mention important files when they
matter.
Select
before you ask. Highlighting the code you mean gives Cursor an exact
starting point. “Explain this” is a sharp question when something is selected,
and a vague one when nothing is.
Know what the AI can see. The AI only works with the context
it is given: your selection, the files you reference, and what it can find in
your project. When an answer seems off, the first thing to check is not “is the
AI wrong?” but “did it have the right file?” Look at what is attached to your
message in the chat box, and add what is missing.
The AI panel is where you talk to Cursor. Its
modes serve different purposes, and picking the right one saves time and
prevents edits you never wanted.
Ask: understand the
code before changing it
Use Ask when
you need an explanation, want to investigate unfamiliar code, or want to
explore a solution before building it. For example:
|
PROMPT Explain how the form submission works in this
JavaScript file. Identify where the form data is handled, and do not modify
any files. |
Ask is especially good for learning. Instead
of pasting in code you do not understand, you find out what it does and which
parts deserve attention.
Agent: carry out a task
with several steps
Agent handles
bigger jobs. Depending on the task, the tools available, and your permissions,
it can explore your files, edit code across several of them, and run commands.
Imagine you
want to add a contact form to an existing site. Do not ask Agent to build it
straight away. Ask for a plan first:
|
PROMPT I want to add a contact form to this website.
Before making changes, identify the files that need to be updated, explain
the changes you propose, and describe how you would test the form. |
Read the plan.
If Agent wants to rewrite a component you did not mention, or replace something
that already works, correct it now, while nothing has changed. When the plan
looks right, tell it to go ahead. That thirty-second check is the cheapest
insurance you will find in this guide.
|
WATCH OUT Before you let Agent loose:
save your work. If you use
Git, commit first so you can return to a known good state in one step. Section
10.4 shows how. |
|
Your goal |
Best starting point |
|
Understand an unfamiliar function |
Ask |
|
Investigate how an existing feature works |
Ask |
|
Modify a selected block of code |
Inline Edit |
|
Implement a feature involving several files |
Agent |
|
Plan a larger change before implementation |
Agent in Plan mode, if available |
|
KEY IDEA The short version: Ask helps you
understand; Agent helps you build. These are starting points, not strict
rules, and mode names can change between versions. |
Whatever mode
you use, check what changed and run the result. A task that looks finished in the AI panel can still be wrong.
The integrated
terminal lets you run commands without leaving Cursor. You will use it to
install dependencies, start a development server, run scripts, and run tests.
Open it with
Terminal → New Terminal. It usually starts in your project folder.
A Node.js
project, for example, may use these two commands:
|
TERMINAL npm install npm run dev |
The first
installs what the project depends on. The second runs the development script
defined in package.json.
They do not fit
every project. Python, Java, and other environments use their own tools. Before
running a command, check the project’s instructions, or ask Cursor to explain
it.
This matters
most when Agent suggests a command. Before you approve it, ask three questions:
1.
What will it change?
Does it install software, edit files, start a process, or alter system
settings?
2.
Where will it act?
Only inside your project, or across your whole computer?
3.
Can I undo it?
Save your work first, especially before anything that deletes or overwrites
files.
Commands that
need administrator rights, destroy data, or run a script you do not recognize
deserve a closer look. Never run something just because an AI suggested it.
Extensions add
features to Cursor: language support, formatting, debugging tools, and
connections to other services. Cursor supports many VS Code extensions, though
not every one is guaranteed to work.
To install one,
open the Extensions view, search for what you need, and check the publisher and
description first.
As a beginner,
keep your setup small. Install an extension when a real need appears, not on
day one. When something breaks, fewer extensions mean fewer suspects.
Shortcuts keep
you in the flow of your work, but you do not need a long list on day one. Start
with two and add others as you go.
The table shows
Cursor’s documented defaults. Keybindings can vary by version, operating
system, and personal settings, so if one does not work, check it in your
installation.
|
Action |
Windows/Linux |
macOS |
|
Accept a Tab suggestion |
Tab |
Tab |
|
Open Inline Edit |
Ctrl + K |
Cmd + K |
|
Toggle the AI
side panel |
Ctrl + I or Ctrl + L |
Cmd + I or Cmd + L |
|
Add selected code to Chat |
Ctrl + Shift + L |
Cmd + Shift + L |
|
Open the mode menu |
Ctrl + . |
Cmd + . |
|
Open the Command Palette |
Ctrl + Shift + P |
Cmd + Shift + P |
Keybindings can
differ by version, operating system, and personal configuration.
Learn them in
this order:
1.
Day one: Tab and Inline Edit. Accept a suggestion with Tab.
Select some code, press Ctrl/Cmd + K, and describe the change you want. These
two alone change how coding feels.
2.
Next: the AI panel
and “Add selected code to Chat.” Open the panel, then highlight code and
send it straight into the conversation.
3.
When needed: the
mode menu and the Command Palette. The Command Palette finds any command by
name, so you never have to remember where something lives.
If the AI panel
disappears, press its shortcut again to bring it back.
To see or
change your shortcuts, open the Command Palette and search for Keyboard
Shortcuts. The official Cursor shortcuts page lists the current defaults.
|
TRY IT NOW A
Five-Minute Tour. The fastest way to get comfortable is to use the tools
yourself. Use any project, or make a folder with one small code file. 1. Open a project. Choose File →
Open Folder and select your folder. 2. Read a file. Open one from the
File Explorer and read a few lines. 3. Select some code. Highlight a
small section you want to understand. 4. Ask about it. Open the AI
panel, choose Ask if available, and type: “Explain this code in plain
English. Do not modify any files.” 5. Open the terminal. Choose
Terminal → New Terminal and notice which folder it starts in. That is the whole interface in
use: your files, the AI, and the terminal. You do not need to master anything
else yet. |
Next,
we look at Cursor’s core AI features, and when to reach for Tab, Inline Edit,
Chat, Agent Mode, and project context.
Cursor becomes
easier to use when you know which feature fits which job. Some help you write
code as you type, some make focused edits, and some explore a whole project and
change several files at once.
A useful way to
think about them is by how much direction each one needs from you. Tab predicts
what you might write next and needs none. Inline Edit follows a one-sentence
instruction. Ask helps you investigate and understand code. Agent works through
a bigger task. Context and Rules give the AI the information and standing
instructions it needs.

You do not need
to master everything at once. Start with Tab and Inline Edit, then add Ask,
Agent, and project instructions as your projects grow.
Cursor Tab is AI-powered autocomplete. Basic
autocomplete suggests a word or a function name. Tab can suggest several lines
at once and predict your next edit, not just your next character.
It draws on
three things: your recent changes, the code around your cursor, and errors your
editor has already flagged in the file. That last one is easy to overlook. Tab
can propose a fix for a problem it sees, not only continue what you are typing.
Example:
completing a function. Suppose you start writing:
|
JAVASCRIPT function calculateTotal(price,
quantity) { |
Cursor may
suggest the body, based on the parameter names and surrounding code. The
suggestion appears as faded preview text. If it matches your intention, press
Tab to accept it. If not, keep typing or press Esc, and it disappears.
The feature
that surprises beginners: press Tab twice. After you accept a suggestion,
press Tab again. Cursor predicts where you will edit next and jumps you there,
sometimes into another file. Rename a function, for example, and Tab may offer
to update the places that use it, one jump at a time. Review each follow-up
change before accepting it, because a suggested edit is not right for every
project.
Getting better results from Tab:
● Read before you accept. A multi-line suggestion is code
you are responsible for, not a guaranteed solution.
● Accept part of it. If only the start is right, press Ctrl
+ → (Cmd + → on macOS) to accept one word at a time.
● Keep typing to override. You never need to explain to Tab
why it is wrong.
● Give it a starting point. A short comment describing the
behavior you want can steer the suggestion, though results vary.
|
JAVASCRIPT // Return the price after
applying a percentage discount. |
● Do not expect a suggestion every time. Sometimes Tab has
nothing useful to offer.
When Tab gets
in the way, click the Tab indicator in the bottom-right corner of Cursor. You
can pause it for a while or turn it off for certain file types. Limits on Tab
can depend on your plan, which Section 12.1 covers.
Tab shines on
repetitive code, predictable patterns, and small follow-up edits. It is the
wrong tool for a feature that needs planning or changes across several files.
|
KEY IDEA Tab helps you continue writing.
The other tools help you investigate, direct, or build. |
For current
details, see the official Cursor Tab documentation.
Inline Edit makes a focused change right where the
code sits, without opening a separate conversation. It works best when you know
which part of the code needs attention and can describe the change clearly.
1.
Select the code you
want to change.
2.
Press Ctrl + K
(Windows/Linux) or Cmd + K (macOS).
3.
Describe the change.
4.
Press Enter.
5.
Review the result. To
refine it, add a follow-up instruction and press Enter again.
If you select
nothing, Inline Edit generates new code at the cursor position. The box that
opens also accepts @ references, just like the AI panel, so you can point it at
a file when the change depends on one.
Example:
improve a function without changing what it does. Suppose your project
contains:
|
JAVASCRIPT function
calculateDiscount(price, discount) {
return price - price * discount / 100; } |
Select it, open
Inline Edit, and write:
|
PROMPT Refactor this function for readability.
Preserve its current behavior, parameters, and return value. Do not modify
any other code. |
Cursor proposes a revised version in the editor. Check
that the calculation still works and that nothing outside the function changed.
The instruction
to preserve behavior is the important part. “Improve this function” leaves the
AI free to rename parameters, alter the formula, or add features you never
asked for. A precise instruction gives you a clear standard to judge the result
against.
Good jobs for
Inline Edit: renaming a variable or function, simplifying a condition, adding
validation to one function, tidying a block of code, or changing the text of an
interface element without touching its behavior.
You can also
ask a question instead of making a change. With the Inline Edit box open,
press Alt + Enter (Option + Enter on macOS) to switch to question mode, then
ask:
|
PROMPT Explain why this condition is necessary. Do
not change the code. |
If the answer
includes a change you like, type “do it” and press Enter, and Cursor applies
it. This is a quick way to understand a line before touching it.
When a change
grows beyond one spot, select the code and press Ctrl + L (Cmd + L on macOS).
This opens Agent with your selection as context, which suits changes across
several files.
|
TIP Which tool? Use Inline
Edit for a focused change in a known location. Use Agent when the task spans
several files. Begin with Ask when you want to understand code before
changing it. |
For the current
shortcuts and workflow, see the official Cursor Inline Edit documentation.
Section 3.2
introduced Ask and Agent. This section helps you choose between them, and
between them and Inline Edit, when a task could go either way.
Three questions
to ask before you start:
1.
Do I need an
explanation or a change? For an explanation, start with Ask. For a change,
use Inline Edit or Agent.
2.
How broad is the
change? One known spot suits Inline Edit. Several files suit Agent.
3.
Do I understand the problem well enough to specify
the fix? If not,
investigate first, or ask Agent for a plan before it changes anything.
One task, three ways. Say you want to change a button label
from “Sign Up” to “Create Account.”
● Inline Edit: Select the button’s code and ask for the
new text, keeping the styling and click behavior. This is a focused
change and takes seconds.
● Agent: It can do the same, but a project-wide tool is
more than a one-line edit needs, and it may touch files you did not intend.
● Ask: Use it first if you do not yet know where the button
is defined. It finds and explains, but does not edit your files.
Now take a
bigger task:
|
PROMPT Add a password visibility toggle to the login
form. Inspect the existing component structure, follow the project’s
conventions, and run the relevant tests if available. Summarize the files you
changed and identify any checks you could not complete. |
This involves
markup, styling, and logic across several files, so Agent fits. Look at the
last sentence: asking Cursor to report what it could not verify helps you
separate what was actually checked from what was assumed.
Common
mismatches:
|
What happens |
Why |
Fix |
|
You asked a question and no file changed |
You were in Ask |
Switch to Agent, or apply the suggestion yourself |
|
A tiny fix changed several files |
A big tool for a small job |
Undo it, then use Inline Edit and say what must stay the
same |
|
A multi-file feature came out half-finished |
The task needed coordinated changes |
Use Agent, and ask it to list the files and checks involved |
|
The result ignores your project’s style |
Agent lacked context |
Reference the right files (Section 4.4) or add a rule
(Section 4.5) |
Agent may ask
permission before running commands or taking certain actions, depending on your
settings. Read these requests instead of approving them automatically. Section
3.3 gives you three questions for judging a command.
Modes, labels,
and capabilities change between versions, so check the mode selector in your
copy of Cursor.
A clear prompt
can still give a poor result if Cursor does not have the information it needs.
Giving the right context is one of the most useful habits you can build.
Typing @ in an
AI conversation opens a picker of context you can add. Depending on your
version, the options include files, folders, code symbols, documentation, and
other supported resources.
Consider this
project:
|
my-website/ ├── index.html ├── style.css ├── script.js └── contact.html |
You want the
contact form to work better on phones. Compare two prompts:
Vague:
|
PROMPT Fix the form. |
With
context:
|
PROMPT Review @contact.html and @style.css. Make the
contact form easier to read on mobile screens. Preserve the existing fields,
validation behavior, and overall design. Explain your proposed changes before
making them. |
The second
names the files, the goal, and the limits. It also helps Cursor connect the
form’s structure to its styling instead of treating the request as an isolated
snippet.
What to
reference:
● A file: when the request concerns one file’s content or
behavior.
● A folder: when the task spans a group of related files.
● A code symbol: when you want to focus on one function,
class, or definition.
● Documentation: when the task depends on how a library or
framework works.
You do not need to memorize these. Type @
and pick what fits.
How much
context is enough? Not more than you need. Piling in many unrelated files
can make a focused task harder for the AI to interpret. Start with the files
most directly connected to the problem and add more only when needed. If a
button has the wrong color, its stylesheet may be enough. If clicking it also
misbehaves, add the script that handles the click.
Referencing a
file does not guarantee that every line of a large project reaches the model.
If something important is missing, mention it or reference it directly.
|
KEY IDEA Give Cursor the smallest useful
set of context that makes the task clear. |
If you keep
giving Cursor the same instructions, such as following your project’s structure
or avoiding extra dependencies, turn them into rules. Rules give Agent
persistent guidance, so you write your conventions once instead of repeating
them in every request.
A practical
signal for adding a rule: when Cursor makes the same mistake twice. The first
time is a prompt problem. The second is a project problem, and a rule is the
lasting fix.
The main types:
● Project Rules: stored in .cursor/rules
in your project, shareable through version control, and configurable to apply
to particular files or situations.
● User Rules: personal preferences set in Cursor’s
settings, used across all your projects.
● Team Rules: managed centrally and available on supported
team and enterprise plans.
● AGENTS.md: a plain Markdown file of project instructions,
the simplest option when you do not need extra configuration.
You may also
meet .cursorrules files in older projects. That is a
legacy format. For new work, use Project Rules or AGENTS.md.
How Project
Rules apply. Project Rules are .mdc files in .cursor/rules.
A rule can be set to always apply, attach automatically when matching files are
involved, be chosen when Cursor judges it relevant, or be included only when
you mention it.
|
WATCH OUT One detail that trips up
beginners: a plain .md file inside .cursor/rules
is ignored, with no warning. Project Rules must use the .mdc
extension. If your rule seems to do nothing, check this first. If you prefer
simple Markdown, use AGENTS.md in the project root. |
A simple
starting point. Create an AGENTS.md file in your project root:
|
MARKDOWN # Project Instructions - Follow the existing project
structure and coding conventions. - Keep changes focused on the
requested task. - Do not introduce new
dependencies without explaining why they are needed. - Preserve existing behavior
unless the request explicitly requires a change. - Report which files were
changed and which tests were run. |
Cursor uses
this file as project guidance. For finer control over when instructions apply,
create a Project Rule through Cursor’s Rules settings or the command for
creating a new rule. The exact steps vary by version.
Two limits to
understand:
● Rules are guidance, not enforcement. Always review the
output, especially for security, data handling, or important behavior.
● Rules guide Agent, not Tab or Inline Edit. If a
preference does not affect your Tab suggestions or inline edits, that is
expected.
Writing
useful rules. Be specific. “Write good code” gives the AI nothing to act
on. “Reuse existing components where possible and avoid adding dependencies
without a clear need” does. Start with a few recurring conventions, add more
only when they solve a real problem, and split long instructions into smaller
rules.
For the latest
rule types and options, see the official Cursor Rules documentation.
You
now have a working picture of Tab, Inline Edit, Ask, Agent, context references,
and Rules. In the next section, you will put them to use by creating your first
project.
The best way to learn Cursor is to use it on a
small task. You do not need a complex application or advanced programming
knowledge. A simple webpage is enough to practice the full cycle: set up
a project, give the AI clear instructions, review the code it produces, and
check that the result works.
In this
section, you will create a project from scratch or open an existing one, write
your first prompt, and verify the generated code. The aim is to learn a
workflow you can reuse in future projects.
|
NOTE Cursor is updated frequently, so
keyboard shortcuts and interface labels may change. The instructions below
focus on the actions you need to perform. To check a shortcut in your
installed version, open the Command Palette with Ctrl + Shift + P on Windows
or Linux, or Cmd + Shift + P on macOS, then search for Preferences: Open
Keyboard Shortcuts. |
If you are new
to programming, start with a small project that has a clear result. In this
example, you will build a simple personal webpage using HTML and CSS. The setup
is intentionally minimal, allowing you to focus on learning Cursor rather than
configuring a development environment.
Step 1: Create a
project folder
Create a folder
on your computer named my-first-cursor-project. You
can place it anywhere convenient, such as your Documents folder.
Step 2: Open the folder in Cursor
Launch Cursor
and choose File → Open Folder. Select my-first-cursor-project.
This creates a
workspace where you can organize your files and work on them together. It also
gives Cursor access to the project structure, helping it locate relevant code
when you ask for assistance.
Step 3: Create the
initial files
In the File
Explorer, create two files:
|
my-first-cursor-project/ ├── index.html └── style.css |
The index.html
file will contain the webpage’s structure, while style.css will control its
appearance.
You do not need
a JavaScript runtime, package manager, or development server for this example.
A modern browser can display the HTML and apply the CSS directly.
Step 4: Define your
goal
Before asking
Cursor to generate code, decide what you want the page to contain. For example,
you could create a personal introduction page with your name, a short
biography, and a contact link.
A clear goal
gives Cursor something specific to work toward and makes it easier to judge
whether the result meets your expectations.
You do not
always need to start from an empty folder. If you already have a website, a
Python script, or another application, you can open it in Cursor and use the AI
to understand or improve its code.
Follow these
steps:
1.
Open Cursor.
2.
Choose File → Open
Folder.
3.
Select the root folder
of your project.
4.
Wait for the project
files to appear in the File Explorer.
5.
Open the files relevant
to your task.
Why open the
project root?
Opening the
project folder gives Cursor a workspace in which related files can be explored
together. This matters when a feature depends on several files. For example, a
button’s appearance might be defined in CSS, while its behavior is handled by
JavaScript.
However, opening a folder does not mean that every
file is automatically included in every AI request. Cursor can search
the codebase, but you can improve the focus of a request by referencing
important files directly. Type @ in the chat input and select the relevant
file, such as @style.css.
Inspect the
project before changing it
If you are
unfamiliar with the codebase, begin by asking Cursor to explain it rather than
immediately requesting edits.
In Ask mode,
try this prompt:
|
PROMPT Summarize the structure of this project.
Identify its main files, explain how they relate to one another, and point
out the most relevant file for changing the homepage layout. Do not modify
any files. |
Ask is designed
for read-only investigation, while Agent can explore the codebase, edit files,
and run commands. Compare Cursor’s explanation with the actual project
structure before deciding what to change.
|
WATCH OUT If the project contains important
work, create a backup or use version control before allowing substantial
edits. This gives you a way to recover if a change produces an unexpected
result. |
A prompt is the
instruction you give Cursor. You do not need elaborate wording, but clarity
makes a significant difference. For a beginner task, a useful prompt usually
covers three things:
● The goal: What should Cursor create or change?
● The requirements: What should the result contain or do?
● The constraints: What should remain unchanged, and what
should Cursor avoid?
Compare these
two prompts.
Too vague:
|
PROMPT Create a website. |
More useful:
|
PROMPT Create a simple personal introduction webpage
using HTML and CSS. Include a heading with my name, a short biography, and a
contact link using the placeholder email address hello@example.com. Use a
clean, responsive layout with readable text and comfortable spacing. Put the
HTML in index.html and the styles in style.css. Do not add JavaScript or
external dependencies. Explain which files you create and how I can preview
the page. |
The second
prompt defines the scope, specifies the required files, and limits unnecessary
complexity. It also uses a placeholder email address rather than asking Cursor
to invent a real contact detail. You can replace the placeholder with your own
address later.
Step 1: Choose a mode
and send the prompt
Creating a
webpage that involves multiple files is a suitable task for Agent. Open the
chat panel, select Agent, enter your prompt, and submit it. Depending on the
task, Cursor may inspect the project, ask a clarifying question, or begin
implementing the requested changes.
If you would
rather understand the plan before any implementation begins, ask Cursor to
outline its approach first:
|
PROMPT Before writing code, outline the structure of
the page and explain what each file will contain. Wait for my confirmation
before implementing it. |
This is useful
while learning because you can evaluate the proposed approach before allowing
changes.
Step 2: Refine the result with a focused follow-up
If something is
missing, ask for that specific change instead of repeating the entire request.
For example:
|
PROMPT Add a short subtitle below the main heading.
Keep the existing layout, colors, and other content unchanged. |
A focused
follow-up makes the change easier to review and reduces the chance of
introducing unrelated modifications.
Once Cursor has
produced the requested result, review what changed before moving on to testing.
Generated code
is a proposal, not proof that a task is complete. A page may look convincing in
the editor while still containing broken links, missing styles, or changes you
never requested. Your job is to verify the result rather than assume it is
correct.
Step 1: Review the
changes
Cursor shows
what changed in a diff view, with added and removed lines highlighted. The
exact review controls depend on your version: you may see Keep and Undo
buttons, or Agent may apply its edits directly and let you review them
afterward in a review view. Either way, read the changes before moving on, and
use the available undo or discard controls to reverse anything you do not want.
Review the
affected files and check the following:
● File locations: Were the files created in the correct
folder?
● Requirements: Does the result include everything you
requested?
● Unnecessary changes: Did Cursor modify unrelated files or
add dependencies you did not ask for?
● Code structure: Are the HTML elements organized
correctly, and does the CSS target the intended elements?
● External resources: Does the page depend on libraries,
fonts, or images you have not configured?
● Placeholders: Is there any content, such as the example
email address, that you still need to replace?
If part of the
code is unclear, ask Cursor to explain it before deciding whether to keep it.
For this small
practice project, you can simply undo a change or ask Cursor to correct it. In
larger projects, version control such as Git gives you a reliable way to
recover from unwanted edits, which is why Section 5.2 recommends it before
substantial changes.
Step 2: Preview the
webpage
For the project
created in Section 5.1, you do not need a development server. Open the project
folder in your file manager and double-click index.html. Your default browser
should display the page.
If the page
appears without styling, check that index.html links to the stylesheet inside
its <head> element:
|
HTML <link
rel="stylesheet" href="style.css"> |
This relative
path works when style.css is in the same folder as index.html. If you move the
stylesheet into another folder, update the path accordingly.
Step 3: Test the result
against your original request
Compare the
page with the requirements in your prompt. Read the text, click the contact
link, and resize the browser window to see how the layout behaves on a narrow
screen.
If the layout
does not adapt properly to mobile screens, check that the <head>
includes the viewport declaration:
|
HTML <meta
name="viewport" content="width=device-width,
initial-scale=1"> |
This
declaration helps mobile browsers use the device’s viewport width when laying
out the page. You will still need responsive CSS to ensure that the content
fits and remains readable.
Step 4: Ask Cursor to investigate problems
If something does not work, describe what you
actually observe instead of simply saying that the page is broken.
For example:
|
PROMPT The page opens, but the CSS styles are not
being applied. Inspect the link between index.html and style.css, identify
the likely cause, and explain the fix before changing any files. |
This gives
Cursor a specific symptom and points it toward the relevant files. Review the
explanation, make the correction, and reload the page.
Step 5: Confirm the fix
Repeat the test
that failed. If you corrected a stylesheet path, reload the page and check that
the styles appear. If you changed a link, click it and confirm that it leads to
the intended destination.
Do not treat
Cursor’s statement that a problem is fixed as proof. Verify the behavior in the
browser, and run relevant tests when the project requires them.
|
KEY IDEA You have now completed the basic
workflow: create or open a project, describe a task, review the generated
code, and verify the result. The goal is not to generate as much code as
possible, but to produce something you can explain, inspect, and maintain. |
In
the next section, you will build on these foundations by writing code with
Cursor in different programming languages and learning how to give it more
effective coding instructions.
Cursor can help
you generate new code, turn an idea into a working function, and adapt existing
code to new requirements. Getting good results depends on you as well: you need
to describe the intended behavior, provide relevant context, and define the boundaries
of the task.
For a small
change, you can send a selected section of code to Agent as context. For a
feature that involves several files, Agent can explore the project, coordinate
edits, and run commands. Choosing the right approach helps keep the work
focused and makes the results easier to review. The official Cursor Agent
documentation explains how Agent works.
You do not need to know every programming detail
before asking Cursor to generate code. You can describe a task inordinary language, explain what the result should do, and let Cursor turn that
description into an initial implementation.
The most useful
instructions describe behavior rather than simply naming a feature. For
example, “Write a function that calculates a discount” leaves several questions
unanswered: Which language should it use? What counts as valid input? What
should the function return?
Compare that
request with the following prompt:
|
PROMPT Write a Python function named
calculate_discount that accepts a price and a discount percentage. Return the
discounted price as a number. Reject negative prices and discount percentages
outside the range of 0 to 100. Include a short example showing how to call
the function. |
This prompt
defines the function’s purpose, inputs, expected result, and basic validation
rules. It gives Cursor a clearer target and provides specific requirements
against which you can evaluate the result.
Cursor might
produce code like this:
|
PYTHON def calculate_discount(price,
discount_percent): if price
< 0: raise ValueError("Price cannot
be negative.") if not 0 <= discount_percent
<= 100: raise ValueError("Discount must
be between 0 and 100.") return price * (1 - discount_percent /
100) final_price =
calculate_discount(200, 15) print(final_price) # 170.0 |
To try the
example, save the code in a file named discount.py, open Cursor’s integrated
terminal, and run:
|
TERMINAL python3 discount.py |
On some Windows
installations, use python discount.py instead. The
command depends on how Python is installed and configured on your computer.
The function
handles the validation rules specified in the prompt, but it assumes that the
inputs are numeric. It also does not define a currency or rounding policy. A
real pricing system may require additional checks and explicit rules for
handling monetary values.
When generating
code, distinguish between a useful starting point and a complete solution. Ask
Cursor to explain unfamiliar implementation choices, and make sure the result
satisfies the requirements of your actual task.
For a small
function, you can request the implementation directly. For a feature involving
several files, first ask Cursor to identify the relevant parts of the project
and outline its approach. Section 6.4 explains how to structure more complex
requests.
Cursor supports
coding workflows across many programming languages. The general approach
remains similar, but your instructions should reflect each language’s purpose
and how the generated code will be used.
Writing Python code
Python is
commonly used for automation, data processing, scripting, and backend
development. When generating Python code, specify the input format, expected
output, and how the function should handle invalid or missing data.
Suppose you
have a list of product prices and want to calculate their average.
Prompt:
|
PROMPT Write a Python function called average_price
that accepts a list of numeric prices and returns their arithmetic mean.
Raise a ValueError if the list is empty. Do not use external libraries.
Include one example with three prices. |
A possible
implementation is:
|
PYTHON def average_price(prices): if not prices: raise ValueError("The price list
cannot be empty.") return sum(prices) / len(prices) print(average_price([10, 20,
30])) # 20.0 |
This example is
deliberately simple. If your actual data comes from a file or database, provide
an example of its structure and explain how the function should handle missing
values, malformed records, or unexpected data types. Otherwise, Cursor may generate
code that works for your example but fails when it encounters real-world data.
Writing JavaScript code
JavaScript adds
behavior to webpages and also powers applications outside the browser. When
requesting JavaScript, explain how the code should interact with the page or
the surrounding application.
For example,
you might want a button to display a message when clicked.
Prompt:
|
PROMPT Write vanilla JavaScript that attaches a
click event listener to a button with the ID show-message. When clicked,
display the text “Welcome!” inside an element with the ID message. Do not use
inline event handlers or external libraries. |
Cursor might
generate a file named script.js containing:
|
JAVASCRIPT const button =
document.getElementById("show-message"); const message =
document.getElementById("message"); if (button
&& message) { button.addEventListener("click",
() => { message.textContent =
"Welcome!";
}); } |
For this code
to work, the HTML page must contain both elements and load the script at the
appropriate time. Create an index.html file in the same folder:
|
HTML <!DOCTYPE html> <html lang="en"> <head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,
initial-scale=1">
<title>Click Test</title>
<script src="script.js" defer></script> </head> <body>
<button id="show-message">Show message</button>
<p id="message"></p> </body> </html> |
The defer
attribute tells the browser to execute the external script after parsing the
HTML document. This allows the browser to create the elements before the
JavaScript looks for them. The if condition also prevents the code from
registering an event listener if either element is missing, although it does
not replace the need to load the script correctly.
Open index.html
in your browser and click the button. The message should appear below it.
When working in
an existing JavaScript application, specify whether you want plain JavaScript
or a particular framework. If the project already uses React, Vue, or another
framework, ask Cursor to follow the existing conventions rather than
introducing a different approach unnecessarily.
Writing HTML code
HTML defines
the structure and meaning of webpage content. When asking Cursor to generate
HTML, describe the content hierarchy and any semantic or accessibility
requirements that matter.
Prompt:
|
PROMPT Create an HTML section for an article card
with a heading, a short description, and a link labeled “Read the full
article”. Use semantic HTML, choose a heading level appropriate for an
existing page, and avoid inline CSS or JavaScript. |
A possible
starting point is:
|
HTML <article
class="article-card">
<h2>Learning to Code with
AI</h2> <p> Discover practical ways to use AI tools
while keeping your code understandable and
maintainable.
</p>
<a href="/articles/learning-to-code-with-ai"> Read the full article
</a> </article> |
The link
destination is an example and must be replaced with a real route on your
website. Likewise, the heading level should match the surrounding document
structure; not every article card needs an h2.
If you want a
particular appearance, ask Cursor to create matching CSS separately or include
the visual requirements in your prompt. When working on an existing website,
point Cursor to the relevant styles or design conventions so that the new
component fits the rest of the page.
These examples
illustrate an important principle: the more clearly you describe the intended
use of the code, the easier it is to evaluate whether the result is
appropriate. Python prompts should clarify data and function behavior,
JavaScript prompts should describe interactions and execution context, and HTML
prompts should define content structure and semantics.
Generating new
code is only part of programming. In an established project, you will often
need to modify something that already works without breaking its surrounding
behavior.
Before
requesting an edit, identify the relevant code and explain what should change,
what should remain intact, and whether the existing function or interface must
be preserved.
Consider this
JavaScript function:
|
JAVASCRIPT function getFullName(user) {
return user.firstName + " " + user.lastName; } |
Suppose you
want to avoid extra spaces when either name is missing. Instead of asking
Cursor to “improve this function,” give it a concrete requirement.
Prompt:
|
PROMPT Modify getFullName so it combines the
available first and last names without extra spaces. Handle missing, null, or
empty-string name values. Keep the function name and its single-argument
interface unchanged. Do not modify other functions. |
A possible
revision is:
|
JAVASCRIPT function getFullName(user) {
const firstName = user?.firstName?.trim() ?? ""; const lastName = user?.lastName?.trim() ??
""; return [firstName, lastName] .filter(Boolean) .join(" "); } |
This version
handles a missing or null user, as well as missing, null, empty, or
whitespace-only string values for the name properties. It assumes that any
provided name values are strings. If your application can supply numbers or
other data types, specify how those values should be handled; otherwise,
calling .trim() on a non-string value can cause an error.
The important
difference is that the prompt defines the required behavior and limits
unrelated changes. This makes the resulting code easier to review than a vague
request to make the function “better.”
A reliable
workflow for modifying existing code involves five steps:
1.
Locate the relevant
implementation. Open the file or identify the function, component, or block
of code involved.
2.
Describe the
required change. State the desired behavior and explain the reason when it
helps clarify the task.
3.
Define the
boundaries. Specify what must remain unchanged, such as function
signatures, public interfaces, dependencies, or unrelated files.
4.
Review the changes.
Follow the review process described in Section 5.4, paying attention to both
modified lines and surrounding changes.
5.
Check related code.
Consider whether other functions, components, or parts of the application
depend on the previous behavior.
For a localized
change, select the relevant code and send it to Agent as context. Cursor’s
documentation lists Ctrl + L or Ctrl + K on Windows and Linux, and Cmd + L or
Cmd + K on macOS, for this. Agent opens with the selected lines referenced in
the input, ready for your instructions. Older versions used Ctrl/Cmd + K for a
separate inline editing box, so your installation may behave differently. Then
describe the change and limit its scope, for example: “Modify only the selected
function.” Shortcuts can change between versions, so consult Cursor’s current
keyboard shortcut reference if yours differs.
When the task
requires searching the codebase or changing several files, describe the whole
task to Agent instead of selecting a single block of code.
|
WATCH OUT Agent may apply edits as it
works, so do not assume every change will remain pending until you approve
it. Review the resulting diff and use a checkpoint or version control to
recover from unwanted changes. Cursor’s Agent documentation explains how
checkpoints work. |
A useful coding
prompt does more than describe an idea. It reduces ambiguity, supplies the
context Cursor needs, and defines what a successful result should look like.
You do not need
a long prompt for every task. A short instruction may be enough for a simple
edit. More complex work benefits from additional detail, especially when
several implementation choices are possible.
As explained in
Section 5.3, a good prompt establishes the goal, requirements, and constraints.
For coding tasks, two additional elements are often useful:
● Context: Which file, function, component, or existing
behavior is involved?
● Acceptance criteria: How will you determine whether the
result meets your requirements?
Consider the
difference between these two requests.
Vague
prompt:
|
PROMPT Add search to my website. |
More
effective prompt:
|
PROMPT Add a search field to the existing article
listing page. Search article titles without regard to letter case, and update
the visible results as the user types. Show a clear message when no articles
match. Use the existing HTML structure and CSS conventions, do not add
external dependencies, and do not change the article data. Before editing,
identify the relevant files and explain your proposed changes. |
The second
prompt clarifies where the feature belongs, how search should behave, what to
display when no results match, and which project constraints apply. It also
asks for an explanation before implementation, which can be useful when the
task affects several parts of the application.
Use examples to clarify
ambiguous behavior.
If a function
must follow a particular rule, provide a sample input and expected output.
|
PROMPT Write a function that formats a person’s
display name. For the input { firstName: "Amina", lastName:
"El Idrissi" }, the output should be "Amina El Idrissi".
If only one non-empty name is available, return that name without leading or
trailing spaces. Keep the function independent of the user interface. |
Examples make
requirements concrete. They are particularly useful for formatting, filtering,
sorting, and other tasks in which different interpretations could produce
different results.
Separate planning from
implementation when the task is complex.
For a feature
that affects many files, do not rush straight into implementation. First ask
Cursor to investigate the existing code and explain the smallest reasonable
change.
For example:
|
PROMPT Inspect the existing code and identify the
files responsible for the navigation menu. Do not modify anything yet.
Explain how the menu currently works and outline the smallest changes needed
to add a mobile-friendly toggle. |
For more
complex tasks, Cursor’s Plan Mode can help you investigate the codebase,
clarify requirements, and review an implementation plan before building. You
can switch to Plan Mode through the mode picker or use Shift + Tab in the chat
input to cycle through modes. Review the proposed plan and refine it when
necessary before asking Cursor to implement it. See the official Plan Mode
guide for details.
Provide relevant
context, not every file.
Cursor can
search the codebase to find relevant information, so you do not need to attach
every file to every request. When you know which files matter, type @ in the
chat input and select the relevant files or folders. For example, a request to
update a component’s appearance may benefit from including both the component
and its stylesheet.
If you are
unsure which files are relevant, let Agent search for them. A request to change
a shared function may also require examining its callers, so avoid restricting
the context so narrowly that important dependencies are overlooked. The
official prompting guide explains how to provide context with file and folder
references.
Refine one requirement
at a time.
If the initial
result is close but not quite right, use a focused follow-up instead of
repeating the entire request.
|
PROMPT Keep the existing search behavior, but
display the number of matching articles above the results. Do not change the
layout or search logic. |
This makes the
requested adjustment explicit and helps reduce unrelated modifications.
Finally,
remember that a well-written prompt improves the chances of obtaining useful
code, but it does not guarantee correctness. Requirements may be incomplete,
and Cursor may make assumptions or overlook edge cases. Treat the prompt as a
way to guide implementation, then inspect the resulting code and verify that it
behaves as intended.
In
the next section, you will apply these techniques to a complete hands-on
project, moving from an initial idea to a working application in manageable
steps.
You now know
how to prompt Cursor, edit code, and review its output. In this section, you
will combine those skills to build a simple task tracker that lets users add
tasks, mark them as complete, delete them, and keep their task list after
refreshing the page.
The project
uses HTML, CSS, and vanilla JavaScript, with browser storage to preserve tasks
between visits. It does not require a framework, a database, or external
libraries, making it a manageable first application.
Rather than
asking Cursor to generate everything in one step, you will build the
application in stages. Each stage introduces a specific requirement, gives you
an opportunity to inspect the implementation, and provides a checkpoint before
moving forward.

Before writing
code, define what the application should do and what you will deliberately
leave out of the first version. A small, clearly scoped application is easier
to build and evaluate than one with too many features.
Step 1: Define the
requirements
The task
tracker should include:
● A text field for entering a new task.
● An Add button that creates a task.
● A list displaying saved tasks.
● A way to mark a task as complete or incomplete.
●
A Delete button for removing individual tasks.
● A message when the task list is empty.
● Automatic saving to browser storage so tasks remain after a page
refresh.
● A responsive layout that works on desktop and mobile screens.
The first
version will not include user accounts, cloud synchronization, team
collaboration, or a backend. These features would introduce additional
complexity without being necessary to learn the basic development workflow.
Step 2: Create the
project folder
Create a folder
named cursor-task-tracker and open it in Cursor. You can
initially leave it empty.
Your intended
file structure is:
|
cursor-task-tracker/ ├── index.html ├── style.css └── script.js |
The HTML file
will define the interface, the CSS file will control its appearance, and the
JavaScript file will implement the task-management behavior.
Step 3: Ask Cursor to
plan the implementation
Open the Agent
panel and switch to Plan Mode using the mode picker or Shift + Tab to cycle
through the available modes. Plan Mode helps you clarify requirements and
review an implementation plan before asking Cursor to build the application.
See the official Plan Mode documentation.
Use this
prompt:
|
PROMPT Plan a small task tracker using HTML, CSS,
and vanilla JavaScript. The application must let users add tasks, mark them
as complete or incomplete, delete them, and preserve the task list using
localStorage. Include an empty-state message and a responsive layout. Use
only three files: index.html, style.css, and script.js. Do not introduce
frameworks, external libraries, a backend, or a build process. Explain the
responsibilities of each file, the main functions needed, and how the
application will be tested. Do not implement the code yet. |
Cursor may ask
clarifying questions before presenting its plan. Answer them briefly, keeping
the original requirements and constraints in mind.
Review the plan
before proceeding. Check whether it covers every requirement, assigns clear
responsibilities to the three files, and avoids unnecessary complexity. Because
the folder is empty, there is no existing code for Cursor to analyze, so the
plan will describe a proposed structure.
If Cursor
proposes a framework or additional dependencies, ask it to revise the plan.
Once you are satisfied, click the Build option on the plan itself to begin
implementation, rather than pasting the plan into a new chat. If the option
does not respond, start a new chat and run the plan again, or reload the window
from the Command Palette.
The objective
is to build a working application without losing track of how its parts fit
together. Let Agent handle related changes, but request one coherent stage at a
time and inspect the result before moving on.
Each prompt
below defines not only what Cursor should do, but also what it should leave
unchanged. These boundaries make the resulting changes easier to review.
Step 1: Create the HTML
structure
Start with the
page structure and its essential elements.
Ask Agent:
|
PROMPT Implement the HTML structure for the task
tracker in index.html. Include a page heading, a form with a task input and
Add button, an area for displaying tasks, and an empty-state message. Give
interactive elements clear labels and use semantic HTML. Link style.css, and
load script.js with the defer attribute. Do not implement the task-management
logic yet, and do not modify any other files. |
Review the
resulting HTML. Make sure the form, input, task list, and empty-state message
have clear purposes and that the stylesheet and script references point to the
correct files.
Open index.html
in your browser to confirm that the page loads. It will look plain and will not
respond to input yet.
You do not need
to memorize every HTML element. Focus on understanding which elements appear on
the page and how JavaScript will identify the elements it needs to update.
Step 2: Add the visual
design
Next, create
the CSS that makes the application readable and usable.
Use this
prompt:
|
PROMPT Style the task tracker in style.css. Create a
clean, uncluttered interface with a centered content area, readable
typography, comfortable spacing, and clearly distinguishable buttons. Make
the layout responsive on narrow screens. Provide visible keyboard-focus
indicators and ensure completed tasks look different from incomplete tasks.
Keep all styling in style.css and do not change the JavaScript behavior or
add external resources. |
Reload
index.html in your browser to inspect the appearance. At this stage, the
interface may look finished without being functional. That is expected because
the task-management behavior has not yet been implemented.
Check that the
input and buttons are easy to identify, text remains readable on a narrow
screen, and keyboard focus is visible when you navigate through the controls.
Step 3: Implement the
task-management logic
Now ask Cursor
to connect the interface to JavaScript.
|
PROMPT Implement the task-management behavior in
script.js. Users must be able to add a non-empty task, mark a task as
complete or incomplete, and delete a task. Update the empty-state message
whenever the list becomes empty or non-empty. Use textContent or other safe
DOM methods to display user-entered task text; do not insert user input
through innerHTML. Keep the implementation in vanilla JavaScript and do not
change the existing HTML or CSS unless a necessary correction is explained
first. |
This prompt
establishes both the required behavior and an important security constraint.
Using textContent for user-entered text prevents the browser from interpreting
that text as HTML markup.
After Cursor
finishes, inspect the code and reload the page. Add several tasks, mark one as
complete, mark it incomplete again, and delete a task. Remove all the tasks and
confirm that the empty-state message returns.
If any action
fails, address that problem before adding persistence. This keeps the number of
possible causes small and makes each correction easier to understand.
Step 4: Save tasks
between visits
A task tracker
that loses everything when the page is refreshed is less useful. Browser
localStorage provides a simple way to preserve data without setting up a
server.
Ask Cursor:
|
PROMPT Update script.js to save the task list in
localStorage and restore it when the page loads. Store each task with a
stable identifier, its text, and its completion status. Update storage after
adding, completing, or deleting a task. Handle missing or invalid stored data
gracefully so that corrupted storage does not prevent the application from
loading. Keep the existing interface and behavior unchanged apart from
persistence. |
Review how the
application loads, saves, and renders its tasks. In particular, check that
restoring the task list does not create duplicate entries and that deleting or
completing a task updates the stored data.
Test
persistence by adding tasks, refreshing the page, and checking that both the
tasks and their completion statuses remain intact.
|
NOTE localStorage is suitable for this
learning project, but it has limitations. Data is stored in the browser for
the relevant origin, is not automatically synchronized across devices, and
can be cleared by the user. Storage can also be unavailable or exceed its
available quota, so robust applications should account for storage errors. It
is not a substitute for a secure backend when an application needs user
accounts, shared data, or server-side storage. |
Step 5: Review the
complete implementation
Before adding
optional features, ask Cursor to summarize what it has built:
|
PROMPT Review the current task tracker against the
original requirements. Explain how the HTML, CSS, and JavaScript work
together. Identify any missing requirements, unnecessary complexity, or
likely weaknesses. Do not make changes yet; report your findings first. |
Compare
Cursor’s response with the actual code and application behavior. Check the
implementation against the original requirements rather than relying solely on
the AI’s summary.
If you discover
a missing requirement, request a targeted correction instead of asking Cursor
to rewrite the entire application. This keeps the changes easier to understand
and reduces the chance of breaking features that already work.
A
working-looking interface is not enough to establish that an application
behaves correctly. Testing means checking expected behavior under normal
conditions, unusual inputs, and situations where stored data or the browser
environment differs from what you anticipated.
For the task
tracker, begin with a manual test plan.
|
Task
tracker test checklist ●
Add a task with ordinary
text. ●
Try submitting an empty
task or whitespace-only text. ●
Add several tasks and
confirm that each appears once. ●
Mark a task as complete,
then mark it incomplete again. ●
Delete one task without
affecting the others. ●
Delete all tasks and
confirm that the empty-state message appears. ●
Refresh the page and
confirm that saved tasks return. ●
Change a task’s
completion status, refresh, and confirm that the status persists. ●
Open the page on a narrow
screen and check the layout. ●
Use the keyboard to reach
and operate the form controls. |
Keep a note of
which checks pass and which fail. A test that you have not performed should not
be treated as a successful test.
Report failures
precisely
If a check
fails, describe what you observed, as you did in Section 5.4. For example, if
tasks disappear after a refresh, try this prompt:
|
PROMPT Tasks appear correctly when I add them, but
they disappear after I refresh the page. Inspect the code responsible for
saving and restoring tasks, identify the likely cause, and propose the
smallest correction. Do not modify unrelated functionality. |
Cursor might
identify a missing save operation, an incorrect storage key, a parsing problem,
or another cause. Review its explanation and the proposed changes before
accepting them.
After the
correction, repeat the exact test that failed. If the problem persists, give
Cursor the new observed result instead of assuming its first attempt solved it.
For more
difficult issues, use your browser’s developer tools (in most browsers, press
F12) to inspect console errors and relevant stored data. Cursor can help
interpret those findings, but your investigation should be grounded in what the
application actually does. Section 8 explores debugging techniques in more
depth.
Start over from the
plan when necessary
Sometimes an
implementation drifts so far from the requirements that repeated small
corrections become inefficient. In that case, reverting the unwanted changes,
refining the original plan, and rebuilding from a clearer specification may be
more effective.
Cursor’s Plan
Mode documentation describes this approach. Before reverting, make sure you
know which changes you want to discard and which work you need to preserve.
Protect the working
version
Before making
substantial changes, preserve a known-working version. Git provides a lasting
project history, while Cursor checkpoints can help you undo Agent changes
during a session. They serve different purposes: checkpoints are stored
separately from Git and are not a replacement for version control. See the
Checkpoints section of the Agent documentation.
If Git is
installed and configured on your computer, you can initialize a repository and
save the initial version from Cursor’s integrated terminal:
|
TERMINAL git init git add . git commit -m "Working task
tracker" |
The first
command initializes a Git repository, the second stages the project files, and
the third records a commit. If Git asks you to configure your identity, follow
its instructions before committing. A commit also requires at least one staged
change; if Git reports that there is nothing to commit, check the repository
status rather than repeating the command blindly.
Before each
substantial improvement, review the changes and create another commit when
appropriate. Use a message that describes the change, such as Add task
filtering.
Keep the first
version simple until its core behavior works. There is little value in adding
animations, themes, or extra features if basic task creation and persistence
are still unreliable.
At the end of
this project, you should have a small task tracker made up of three files:
● index.html provides the structure and form controls.
● style.css defines the visual design and responsive
layout.
● script.js manages tasks, updates the interface, and
saves data in localStorage.
The application
should allow you to add tasks, change their completion status, delete them, and
restore the saved list after refreshing the page. Confirm each of these
behaviors in your own project.
Once the basic
version works, you can extend it gradually. Each improvement should solve a
specific problem or introduce a useful capability.
Possible
next improvements
|
Improvement |
What you will learn |
|
Filter tasks by all, active, or completed |
Managing application state and displaying subsets of data |
|
Add an Edit button |
Updating existing records and handling form input |
|
Add a Clear
Completed button |
Applying an operation to multiple tasks |
|
Display the number of remaining tasks |
Deriving information from the current task list |
|
Add categories or due dates |
Expanding the data model and improving the interface |
|
Add automated tests |
Checking expected behavior consistently as the code changes |
Do not request
all these improvements at once. Choose one, describe its expected behavior, and
ask Cursor to identify which files need to change before implementation. Then
review the diff and test the new feature without losing the functionality that
already works.
This project
illustrates a repeatable development process: define requirements, plan the
implementation, build in manageable stages, test the result, and make focused
improvements. Cursor can accelerate each stage, but your understanding of the
requirements and your verification of the finished application remain
essential.
In
the next section, you will look more closely at debugging with Cursor AI,
including how to investigate error messages, identify likely causes, improve
code quality, and verify fixes systematically.
Every developer knows the moment: the code looked
right, it ran yesterday, and now it’s throwing an error you’ve never seen. This
is where many beginners make their first big mistake with AI tools. They
paste the error, accept whatever comes back, and move on without understanding
what happened.
Cursor can be a
very good debugging partner, but only if you treat it like one. A partner needs
context, asks questions, and gets checked. Think of Cursor as a sharp colleague
who has read your whole project but wasn’t in the room when the bug appeared. Your
job is to tell them what you saw.
A useful bug
report has three parts: what happened, what you expected, and how to reproduce
it. If you can’t describe all three, you’re not ready to ask for a fix yet.
On bigger
projects, add a fourth ingredient: constraints. Tell Cursor which files or
behaviors must stay untouched, for example, “Do not modify unrelated files.” It
keeps the fix small and the diff easy to review.
For simple
problems, Cursor’s Agent mode can read the relevant files, make a change, and
run your tests. For stubborn bugs that you can reproduce reliably, Cursor’s
Debug Mode is worth trying, since it uses runtime information instead of
guessing from the code alone. Features and menus change between versions, so
check what your installation offers.
Here is a small
function that looks harmless:
|
PYTHON def calculate_average(numbers): return sum(numbers) / len(numbers) print(calculate_average([])) |
Run it with an
empty list and Python raises a ZeroDivisionError. The tempting fix is to patch
the division. But the real question is a design question: what should an
average of nothing mean? The function never decided.
Instead of “fix
this,” give Cursor the investigation:
|
calculate_average() crashes with
ZeroDivisionError when the input list is empty. 1. Explain the root cause. 2. Suggest the simplest
appropriate fix. 3. Handle empty input
explicitly. 4. Add tests for a normal list,
a single-item list, and an empty list. 5. Explain every change you
make. |
A good answer
will look something like this:
|
PYTHON def calculate_average(numbers): if not numbers: raise ValueError("Cannot
calculate the average of an empty list.") return sum(numbers) / len(numbers) |
Now the
function fails loudly and clearly instead of accidentally. Some projects would
rather return None or 0 for empty input. Neither choice is universally right.
It depends on what the rest of your code expects, so decide that before Cursor
does it for you.
Then verify.
Run the tests, and check that normal inputs still work. A fix that solves one
problem while breaking another isn’t a fix.
If the first
attempt fails, don’t keep typing “try again.” Give Cursor new evidence: the
exact steps to reproduce, the relevant log output, and the files involved. Ask
it what the evidence rules out. Debugging gets faster when each round narrows
the problem.
Error messages
look intimidating, but most of them are just three questions in disguise: what
kind of failure, where, and under what conditions?
● Error type and message: says what kind of failure
occurred (TypeError, SyntaxError, a missing module).
● File and line number: tells you where it surfaced. In a
stack trace, start with the first line that points to your own code, but
remember the true cause may sit earlier in the chain.
● Context: the input, the previous steps, and the state of
the program when it failed.
Here’s a
realistic example:
|
JAVASCRIPT function findUser(users, id) {
return users.find(user => user.id === id); } const user = findUser([{ id: 1,
name: "Sara" }], 2); console.log(user.name); |
This throws a
TypeError because user is undefined. The line that crashes is user.name,
but that’s only where the problem became visible. The real cause is that
findUser returns undefined when nothing matches, and the caller assumed it
always would.
That’s the
difference between where an error occurs and why it occurs, and it’s what you
should ask Cursor to explain:
|
Explain this error in
beginner-friendly language. Show which expression fails, why
the value is undefined, and trace how that value is
produced. Then suggest a fix for the
underlying cause, not just the visible symptom,
and explain any behavior changes. |
A fix that
addresses the cause checks the result before using it:
|
JAVASCRIPT const user = findUser([{ id: 1,
name: "Sara" }], 2); if (user) {
console.log(user.name); } else {
console.log("User not found."); } |
The
missing-user case is now handled on purpose. In a larger application you might
show an error message or handle it one layer higher, but the principle is the
same: deal with the situation where it actually begins.
When you ask
Cursor to explain an error, request three things separately: the location
(which line triggered it), the cause (which value or assumption produced it),
and the remedy (the smallest change that fixes the underlying problem). Then
ask why the fix works and which cases it still doesn’t cover.
|
WATCH OUT When you paste an error into
chat, include the command you ran and what you did right before. And scrub
the log first. Passwords, access tokens, and personal data have a way of
hiding in stack traces and environment output. |
One habit to
avoid: asking Cursor to “just make the error go away.” A blanket try/catch or a
silent default value can hide a bug rather than fix it, and a hidden bug is
much more expensive to find later.
Debugging fixes
something that’s wrong. Refactoring improves something that works, making it
easier to read, change, and test, without changing what it does for the user.
You’ll want it
when functions grow long, logic gets copied around, or names stop making sense.
Here’s a typical starting point:
|
JAVASCRIPT function calculateTotal(price,
quantity, discount) { let total = price * quantity; total = total - (total * discount / 100); return total; } |
It’s short, but
a stranger reading it has questions. Is discount a percentage or a fraction?
Can quantity be zero? What happens with negative prices? Settle those rules
first, then hand them to Cursor:
|
Refactor
calculateTotal() to improve readability and handle
invalid inputs. Requirements: - Preserve the calculation for
valid inputs. - Use
descriptive parameter names. - Require a
finite, non-negative price. - Require a
positive integer quantity. - Require a discount between 0
and 100. - Do not add external
dependencies. - Explain any behavior changes. - Add tests for normal and
boundary cases. |
Here’s a
version that meets every requirement:
|
JAVASCRIPT function calculateTotal(price,
quantity, discountPercent = 0) { if
(!Number.isFinite(price) || price < 0) { throw new RangeError("Price must
be a non-negative number."); } if (!Number.isInteger(quantity) ||
quantity < 1) { throw new RangeError("Quantity
must be a positive whole number."); } if ( !Number.isFinite(discountPercent) || discountPercent < 0 || discountPercent > 100 ) { throw new RangeError("Discount
must be between 0 and 100."); } const subtotal = price * quantity; const discountAmount = subtotal *
(discountPercent / 100); return subtotal - discountAmount; } |
Notice what
happens when the requirements are vague. A common AI result is a prettier
function with nicer names that quietly skips the validation. It looks like
progress. Always compare the output against your list, one line at a time.
Notice also
that adding validation changes behavior. The original function might have
accepted a fractional quantity, while this one rejects it. That’s only correct
if your application really requires whole numbers. The Number.isFinite()
checks also catch NaN and Infinity, which a plain price < 0
comparison lets through.
Those rules are
business decisions, not universal truths. Another shop might allow fractional
quantities or treat a bad discount differently, so make the call yourself
before Cursor makes it for you. And if you handle real money, consider working
in cents (integers) or a decimal library, because floating-point math can
produce results like 0.30000000000000004.
For a small
change in one place, Inline Edit is usually enough. For changes that span
several files, Agent can inspect the related code and coordinate the edits.
Either way, read the diff before you accept anything.
A safe
refactoring routine:
1.
Ask Cursor to explain
the current code and point out specific weaknesses.
2.
Define the intended
behavior before anything changes.
3.
Request a focused
change, not a rewrite of unrelated parts of the project.
4.
Read the diff and check
that every requirement has been addressed.
5.
Run the existing tests,
then add new ones for anything that changed.
Small,
reviewable steps feel slower for about five minutes and are much faster after
that.
AI-generated code has a particular talent: it
looks convincing. It runs on the happy path and then fails on an empty
list, a missing field, or a value nobody thought to try. Treat it exactly like
code from a new teammate: probably good, not yet proven.
Cursor can
write tests, run them, read the failures, and suggest fixes. But a green
checkmark only proves the code matches the test. If the test expects the wrong
thing, you’ve proven nothing, so decide the expected behavior first.
Here are tests
for the calculate_average() function from Section 8.1, using pytest:
|
PYTHON import pytest from average import
calculate_average def
test_average_of_multiple_numbers(): assert calculate_average([2, 4, 6]) == 4 def
test_average_of_one_number(): assert calculate_average([5]) == 5 def
test_empty_list_raises_value_error(): with pytest.raises(ValueError): calculate_average([]) |
Save the
function in average.py and the tests in test_average.py. Install pytest in your
project’s Python environment if needed, then run:
|
TERMINAL python -m pytest |
You can have
Cursor do the same work with a prompt that sets the ground rules:
|
Write pytest tests for
calculate_average(). Cover: - Several
positive numbers. - A single
number. - An empty list, which must
raise ValueError. Run the tests if the environment
allows it. If one fails, explain the cause
before changing the implementation. Do not change the expected
behavior merely to make a test pass. |
That last line
matters more than it looks. When a test fails, a careless assistant can “fix”
things by rewriting the test instead of the code.
When a test
fails, don’t ask for an instant fix. Paste the failure output and ask Cursor to
decide where the problem lives:
|
Analyze this test failure and
identify the root cause. Is the problem in the
implementation, the test itself, or the test environment? Suggest the smallest correction
and do not change unrelated behavior. |
For anything
bigger than a small function, layer your checks:
● Unit tests check individual functions in isolation.
● Integration tests check that the pieces work together.
● Manual testing shows what a real user experiences,
including odd input and unexpected clicks.
● Linters and type checkers catch a whole class of problems
before the code even runs.
For a web app,
“the page loads” is not a test result. Check that the buttons work, that
invalid input is handled, that saved data persists, and that the layout stays
usable on a phone screen.
|
WATCH OUT One last warning: if Cursor says
it couldn’t run the tests because of a missing dependency or an unconfigured
environment, the result is inconclusive. That is not a pass. Fix the setup,
or run the tests yourself. |
|
KEY IDEA The takeaway: let Cursor speed up
the investigating, the explaining, and the test writing, but let evidence
decide whether something works. Developers who build that habit early write
more reliable software, and they also learn faster, because every bug ends
with an explanation instead of a lucky patch. |
Your first week
with Cursor can feel like magic. You describe a function, and it appears. You
paste an error message, and Cursor helps you fix it. Then you join a real
project with 300 files, years of development history, and a folder called
legacy_utils. Suddenly, things become more complicated.
The challenge
is no longer simply writing code. It is understanding where a change belongs,
how existing components work together, and what might break when you modify
them.
This is where
Cursor becomes especially useful on larger projects. It can help you explore
unfamiliar codebases, trace dependencies, identify duplicated logic,
investigate performance problems, and generate documentation. The principle is
simple: understand first, change second. Ask focused questions, work in
manageable steps, and review every important change.
In a large
codebase, the hardest question is often not how to write a feature, but where
its functionality already lives. Cursor can search the codebase, identify
relevant files, and help trace relationships between components. This is
particularly useful when you are working with a project you did not build
yourself.
When exploring
an unfamiliar project, tell Cursor explicitly not to modify any files. Start
with a broad overview:
|
Explore this codebase without
modifying any files. Identify the main entry points,
explain the purpose of the major directories, and
describe how the frontend communicates with the backend. Name the specific files that
support each explanation. Distinguish confirmed findings
from assumptions. |
Open the files
Cursor identifies and check its explanation against the actual implementation.
A convincing answer is not necessarily an accurate one, so treat this step as
an investigation rather than a formality.
Next, narrow
your attention to the feature you want to understand:
|
Trace what happens when a user
submits the registration form, from the frontend event
handler through backend validation to the database
operation. List the relevant files in
execution order and explain the role of each one. |
Once you
understand the existing flow, you can plan a change more confidently. A
reliable workflow has four stages:
1.
Explore:
Identify the relevant files and understand how the current implementation
works.
2.
Plan: Define the
intended behavior, affected components, and potential risks. Cursor’s planning
features and workflows may vary by version.
3.
Implement:
Request a focused change that follows the project’s existing conventions.
4.
Verify: Review
the diff, run appropriate tests, and check for unintended side effects.
A few habits
make this process more effective:
● Provide relevant context. Use @ references to include the
files or folders that matter instead of adding unnecessary material.
● Document project conventions. If the project requires
specific patterns, such as keeping database access in service modules, record
those conventions in the appropriate Cursor project rules or instruction files.
● Start a fresh chat when necessary. If a conversation
accumulates outdated assumptions or becomes difficult to follow, begin a new
one with a concise summary of the current findings and requirements.
● Correct inaccurate assumptions. If Cursor overlooks an
important file, point it to that file and ask it to reconsider its explanation.
|
NOTE Large projects may take time to
index, and search results can be incomplete. Do not assume that Cursor has
discovered every relevant dependency simply because it has access to the
repository. |
A project’s
architecture describes its main components, the responsibilities of each
component, and the ways they communicate. Understanding this structure before
making changes helps prevent duplicated functionality and unnecessary
dependencies.
Imagine a
task-management application with the following directory structure:
|
task-manager/ ├── src/ │ ├── components/ │ ├── pages/ │ ├── services/ │ └── utils/ ├── tests/ ├── package.json └── README.md |
The directory
names provide clues, but they do not establish how the application actually
works. A services directory might contain API calls, business logic, or a
mixture of responsibilities.
Ask Cursor to
inspect the real files:
|
Analyze this project's
architecture using its source files and configuration. Explain the responsibilities of
the main directories, identify the application's entry
point, and trace how a task is created and saved. Separate confirmed facts from
assumptions. |
That
distinction matters. When Cursor identifies an assumption, you know what needs
further investigation before you rely on its conclusions.
Once you have a
general understanding of the architecture, ask more targeted questions:
● Which files handle user input?
● Where is the business logic implemented?
● Which components depend on a particular service?
● Where should a new feature be implemented to follow the existing
structure?
You can also ask Cursor to create a diagram. Mermaid
is a text-based diagramming format supported by many development tools,
including platforms that render Mermaid diagrams in Markdown.
Use a prompt
such as:
|
Create a Mermaid flowchart
showing how a user creates a task, from the interface
through validation and data storage to the updated task
list. Include only relationships
confirmed by the codebase. |
The resulting
Mermaid code might look like this:
|
MERMAID flowchart LR A[Task form] --> B[Validation] B -->
C[Task service] C --> D[(Database)] D --> E[Updated task list] |
This diagram is
illustrative only. Your project’s actual flow may differ. For example, an
application might save tasks to local storage or communicate with a remote API
instead of accessing a database directly.
Always compare
generated diagrams with the actual code before sharing them with your team. A
diagram may omit a dependency or describe the intended design rather than the
implementation.
|
KEY IDEA The rule to remember: ask Cursor
to explain the architecture before asking it to change the architecture. |
As projects
grow, similar logic often appears in multiple places, and performance problems
can emerge as data volumes and application complexity increase. Cursor can help
investigate both, but you must determine whether its findings represent genuine
problems.
Finding duplicated code
Consider these
two JavaScript functions:
|
JAVASCRIPT // signup.js function isValidEmail(email) {
return
/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email); } // invitations.js function checkEmail(email) {
return email.includes("@") && email.length <=
254; } |
Both functions
validate email addresses, but they do not enforce the same rules. The first
checks a basic email format, while the second checks only for an @ character
and a maximum length.
They might
represent inconsistent implementations of the same requirement, or the
difference might be intentional. Do not merge them until you understand the
intended behavior.
Ask Cursor to
investigate first:
|
Search the codebase for
email-validation logic. List each implementation,
compare the inputs it accepts and rejects, and explain whether
the functions can safely share a common helper. Identify behavioral differences
and recommend a solution before changing any files. |
If the
functions are intended to enforce identical rules, a shared helper may improve
maintainability. If their requirements differ, merging them without preserving
those differences could introduce bugs.
Finding performance
bottlenecks
Performance
investigations should begin with evidence, not assumptions. A slow page might
result from repeated network requests, expensive rendering, inefficient
database queries, large assets, or problems outside the application itself.
Consider this
JavaScript function:
|
JAVASCRIPT async function
loadPrices(products) {
const prices = [];
for (const product of products) { const response = await
fetch(`/api/prices/${product.id}`); if (!response.ok) { throw new Error(`Failed to load price
for ${product.id}`); } prices.push(await response.json());
}
return prices; } |
Each request
waits for the previous one to finish. If there are 50 products, the function
makes 50 sequential requests, assuming the loop reaches every product
successfully.
One possible
improvement is to run requests concurrently with Promise.all().
However, concurrent requests may overload a service, encounter rate limits, or
fail as a group if one request rejects. A batch API endpoint or limited
concurrency may be more appropriate for a particular application.
Ask Cursor to
investigate before choosing an approach:
|
The product list loads slowly. Trace the relevant data-fetching
and rendering code. Identify plausible bottlenecks
and explain how to measure each one. Recommend the smallest
high-impact improvement first. Do not claim a performance gain
without a way to verify it. |
Confirm its
findings using appropriate tools, such as the browser’s Network panel,
application logs, a profiler, or database query analysis.
A disciplined
optimization workflow looks like this:
1.
Reproduce the
performance problem.
2.
Measure the relevant
behavior and record the baseline.
3.
Ask Cursor to
investigate the code associated with the measurement.
4.
Apply one focused
change.
5.
Repeat the measurement
under comparable conditions.
6.
Run tests to check that
the change has not broken existing behavior.
|
TIP Shorter code is not necessarily
faster code. A performance improvement should be measurable, relevant to the
actual problem, and maintainable over time. |
Documentation
often becomes outdated as a project evolves. Cursor can help create
documentation from existing code and compare current instructions with the
implementation to identify inconsistencies.
If a project
has no README, or its existing README is incomplete, start with a focused
request:
|
Review this
codebase and create a README.md covering: - The project's purpose - Prerequisites - Installation instructions - Configuration - How to run the application - How to run the tests - The main directory structure Base every instruction on the
actual files and package scripts. Flag anything
you cannot verify. Do not invent commands or
configuration values. |
Cursor may
inspect files such as package.json, dependency manifests, environment-variable
examples, and configuration files to determine the appropriate instructions.
Nevertheless, review the result before publishing it.
For example, if
the README recommends npm run dev, confirm that the
project actually defines that script. If it describes a database or environment
variable, verify that the application requires it.
A particularly
useful check is to follow the README on a clean copy of the project or in a
fresh environment. If another developer cannot install and run the application
using the documented steps, the documentation needs improvement.
You can also generate more specialized
documentation.
Documenting a function
|
Explain what this function does,
including its parameters, return value,
possible exceptions, and important edge cases. Add a concise docstring that
accurately reflects the implementation. |
Documenting API
endpoints
|
Identify the API endpoints
implemented in this project. For each endpoint, document its
HTTP method, path, expected inputs, responses,
authentication requirements, and error cases. Use the code as the source of
truth and flag any behavior that needs
confirmation. |
Creating an
architecture overview
|
Write an architecture overview
describing the main modules, their responsibilities,
and how they interact. Include a Mermaid diagram and
identify the relevant source files. Distinguish
confirmed behavior from assumptions. |
Updating an existing
README
|
Compare README.md with the
current codebase. Identify outdated commands,
missing setup steps, and descriptions that no longer
match the implementation. List the proposed corrections
before editing the file. |
Not every
important detail can be discovered from source code. Deployment procedures,
security assumptions, and the reasons behind older design decisions may exist
only in team knowledge or external documentation. When Cursor cannot verify a
detail, it should flag it for confirmation rather than present a guess as fact.
|
KEY IDEA By now, the pattern should feel
familiar: explore before you change, measure before you optimize, and verify
before you trust. Cursor can read a 300-file project far faster than you can,
but only you know what the project is supposed to do. The best results come
when you bring that knowledge to the conversation. |
Cursor can help
you write code faster, explore unfamiliar projects, and solve problems more
efficiently. However, getting reliable results depends on more than writing
clever prompts. You need to provide clear instructions, work in manageable
steps, review changes carefully, protect your project, and verify the results.
This chapter
explains how to build a reliable AI-assisted coding workflow, avoid common
beginner mistakes, and use Cursor to improve both your productivity and your
programming skills.

|
Chapter at
a glance ●
Write prompts with clear
goals, context, requirements, constraints, and acceptance criteria. ●
Break complex tasks into
small, testable steps. ●
Review actual code
changes rather than relying on the AI’s summary. ●
Use Git to preserve
working versions before major changes. ●
Protect secrets and
inspect commands, dependencies, and permissions. ●
Use AI to strengthen your
understanding, not replace it. |
The quality of
Cursor’s output depends partly on how clearly you describe the task. A vague
request leaves important decisions to the AI, while a specific prompt gives it
enough context to work toward a defined result.
Compare these
two prompts.
Vague prompt
|
Make my website better. |
Specific
prompt
|
Improve the layout of the
existing landing page. Requirements: - Keep the current color scheme
and branding. - Make the layout responsive on
mobile and desktop. - Improve
spacing and heading hierarchy. - Preserve existing
functionality. - Do not add external libraries. Inspect the relevant files
first, then make the smallest changes needed and explain what
you changed. |
The second
prompt defines the goal and constraints without prescribing every
implementation detail. It also gives you a clear basis for reviewing the
result.
A practical structure
for coding prompts
A strong coding
prompt usually includes five elements:
1.
Goal: What do
you want to accomplish?
2.
Context: Which
files, functions, or application components are relevant?
3.
Requirements:
What must the solution do?
4.
Constraints:
What must remain unchanged, and which technologies or dependencies are allowed?
5.
Acceptance criteria:
How will you determine whether the result is correct?
For example,
suppose you want to add search to an existing task list.
|
Add a search field to the
existing task-list page. Context: Inspect the current HTML, CSS,
and JavaScript before making changes. Requirements: - Search tasks by title. - Ignore differences between
uppercase and lowercase. - Update the visible results as
the user types. - Show a clear message when no
tasks match. Constraints: - Use the existing technology
stack. - Do not add dependencies. - Preserve task creation,
completion, and deletion. Acceptance criteria: - Matching tasks appear as
expected. - Non-matching tasks are
excluded from the results. - Existing task functionality
continues to work. - An empty search field displays
all tasks. Implement the change, review the
diff, and report which checks you actually ran. |
This prompt
makes the expected behavior testable while leaving Cursor room to choose an
appropriate implementation.
Improve results through
follow-up prompts
You do not need
to solve everything in one message. For complex tasks, investigate the existing
code first, discuss the proposed approach, and then request implementation. If
your version of Cursor provides a planning or read-only mode, use it to explore
significant changes before allowing edits.
Useful
follow-up prompts include:
● “Explain your proposed approach before editing any files.”
● “Which edge cases should this implementation handle?”
● “Review the changes for unintended behavior.”
● “Run the relevant tests and explain any failures.”
● “Which assumptions have you made that I should verify?”
Keep the scope
manageable. A focused change is easier to inspect, test, and reverse than an
unnecessary rewrite of the entire project.
Many problems
with AI-assisted coding arise from unclear requirements, insufficient review,
or unverified assumptions. Recognizing these mistakes early can save time and
protect a working project.
Mistake 1: Giving vague
instructions
A prompt such
as “Fix the website” does not explain what is broken, how the problem occurs,
or what should happen instead.
Better
approach: Describe the observed behavior, the expected behavior, and the
steps needed to reproduce the problem. Include relevant error messages when
available.
|
When I click the Save button,
the task disappears from the page after I refresh
it. Expected behavior: Saved tasks should remain
visible after reloading the page. Inspect the current saving and
loading logic, identify the likely root cause,
and propose a focused fix before making
changes. |
This gives
Cursor a concrete problem to investigate rather than encouraging an unnecessary
rewrite.
Mistake 2: Accepting
changes without reviewing them
Cursor may
modify several files, introduce dependencies, or alter existing behavior while
implementing a seemingly simple feature.
Better
approach: Inspect the diff, check which files changed, and compare the
changes with your original requirements. Run relevant tests before considering
the task complete.
|
Review the changes against my
original requirements. Identify unrelated
modifications, unnecessary dependencies, and potentially
unexpected behavior. Explain your findings and
recommend any corrections. Do not make
further edits until I approve them. |
Mistake 3: Asking for
too much at once
Asking Cursor
to build an entire application with authentication, payments, database
integration, and an administration dashboard in one step makes errors harder to
isolate and results harder to evaluate.
Better
approach: Divide the project into milestones. For a task manager, you
could:
1.
Create the interface.
2.
Add task creation and
deletion.
3.
Implement task
completion.
4.
Add persistent storage.
5.
Introduce search or
filtering.
6.
Test the complete
workflow.
Verify each milestone before moving to the next.
Mistake 4: Assuming
generated code is correct
Code can look
professional and still contain logical errors, insecure practices, or missing
edge cases.
Better
approach: Test normal inputs, invalid inputs, boundary conditions, and
realistic user actions. Ask Cursor to suggest test cases, but check whether
they cover your actual requirements.
For example, a
discount calculator should be tested with a normal discount, a zero discount, a
full discount, negative values, and values above the permitted range. If the
application accepts only discounts between 0% and 100%, those limits should be
enforced and tested explicitly.
Mistake 5: Ignoring the
existing project structure
Beginners
sometimes ask Cursor to create a new helper, component, or configuration file
without checking whether the project already contains a suitable
implementation.
Better
approach: Ask Cursor to locate existing implementations and explain the
project’s conventions before adding new code. Reuse established components and
utilities where appropriate, and avoid creating duplicate logic.
Mistake 6: Treating an
explanation as proof
Cursor can
provide a plausible explanation for a bug or describe an action as successful
without establishing that the result works in your environment.
Better
approach: Distinguish between a proposed solution, an attempted action, and
a verified result. Check actual command output, test reports, application
behavior, and relevant files. If a test could not run because a dependency is
missing, report that limitation instead of claiming that the implementation
passed.
Mistake 7: Keeping
every task in one conversation
A long
conversation can accumulate outdated assumptions and unrelated details. This
may make it harder for Cursor to follow the current requirements consistently.
Better
approach: Start a new conversation when you finish a feature or switch to a
distinct task. Include a concise summary of the current state and reference the
relevant files. Store stable project conventions in project rules rather than
relying on chat history alone.
Mistake 8: Installing
every package the AI recommends
AI tools can
suggest outdated or unnecessary packages, or even names of packages that do not
exist. Attackers can publish malicious packages under such names, and malicious
packages can also imitate legitimate ones, so installing an unfamiliar
dependency without verification creates a supply-chain risk.
Better
approach: Check the package in the official registry, verify its name and
maintainer, review its documentation and recent activity, and decide whether it
is actually needed. Inspect dependency manifests such as package.json or
requirements.txt after any installation.
Using Cursor
effectively does not mean accepting everything it generates. You remain
responsible for deciding whether the implementation meets the requirements,
fits the existing architecture, and behaves correctly.
A practical code-review
checklist
Before
accepting a significant change, consider the following questions:
● Correctness: Does the implementation solve the requested
problem?
● Scope: Did Cursor change only the files and behavior
needed for the task?
● Readability: Can I explain what the new code does?
● Edge cases: What happens with empty values, invalid
input, missing data, or unexpected errors?
● Security: Does the change introduce unsafe input
handling, exposed secrets, or excessive permissions?
● Compatibility: Does it work with the project’s existing
dependencies and architecture?
● Verification: Were the relevant tests or manual checks
actually completed?
You do not need
to understand every detail of a large codebase before making progress. However,
you should understand the purpose and consequences of the changes you accept,
especially when they affect security, data, or important application behavior.
Review the diff, not
just the explanation
Cursor’s
summary can help you understand its work, but it is not a substitute for
examining the actual changes. Review added, removed, and modified lines. Pay
particular attention to configuration files, dependency manifests,
authentication logic, database operations, and code that handles user input.
If a change is
larger than expected, ask Cursor why each affected file needed modification. If
the explanation does not justify the scope, request a smaller implementation.
Use AI as a learning tool
Overdependence
becomes a problem when you can generate code but cannot explain, maintain, or
debug it. You can use Cursor to build your understanding instead of simply
asking it to produce finished solutions.
For example,
try this prompt:
|
Explain this implementation step
by step. Identify the main functions,
describe how data flows through them, and explain any
unfamiliar language features. Point out the most important
assumptions and possible edge cases. Then suggest one small exercise
I can complete to check my understanding. |
You can also
ask Cursor to compare two implementations, explain their trade-offs, or guide
you toward a solution without immediately providing the finished code.
The goal is not
to avoid AI assistance. It is to become more capable through it. The better you
understand the code you accept, the more confidently you can maintain and
improve your projects.
Git is a
version-control system that records changes to files over time. It lets you
compare versions, create a history of meaningful changes, and recover earlier
committed states. This is especially valuable when Cursor makes several edits
in a short time.
Create a Git repository
If your project
is not already under version control, install Git and initialize a repository
from the project’s root directory:
|
TERMINAL git init |
If this is your
first time creating commits on the computer, configure the author information
Git requires:
|
TERMINAL git config --global user.name
"Your Name" git config --global user.email
"you@example.com" |
Replace the
example values with your own name and email address. The --global
option applies these settings to your user account; omit it if you want to
configure only the current repository.
Before staging
files, create a .gitignore file to exclude secrets, dependencies, and generated
files that should not be committed. For example, a project might need entries
such as:
|
.GITIGNORE .env .env.* !.env.example node_modules/ dist/ |
A file such as
.env.example, containing only placeholder values, is normally committed so that
collaborators know which variables the project requires. Adapt these patterns
to your project. Do not ignore files blindly if the application needs them, and
do not assume that .gitignore removes a file that has already been committed.
Check the
repository status:
|
TERMINAL git status |
Stage the files
you intend to include and create your first commit:
|
TERMINAL git add . git commit -m "Initial
project version" |
Review git
status before staging to understand what is untracked or modified. For an
existing repository, always check its current state before starting a
substantial AI-assisted task.
Commit before major
AI-assisted changes
Before asking
Cursor to perform a large refactor or implement a substantial feature, commit
your current working state. For an
isolated experiment, you can also create a separate branch:
|
TERMINAL git switch -c
feature/task-search |
This creates
and switches to a new branch. If a branch with that name already exists, choose
another name or inspect the existing branch before proceeding.
After Cursor
finishes, inspect the changes:
|
TERMINAL git status git diff |
git
diff displays unstaged changes. If you have already staged files, use git
diff --cached to inspect the staged changes as well.
Run the
relevant tests, then stage and commit the changes you want to keep:
|
TERMINAL git add . git diff --cached git commit -m "Add task
search functionality" |
Use meaningful
commit messages that describe the change. Remember that Git records the files
you stage; it does not automatically determine which changes are correct or
safe.
If you need to
discard uncommitted changes to a specific tracked file, you can use:
|
TERMINAL git restore path/to/file |
|
WATCH OUT Caution: This command
discards that file’s unstaged changes. Make sure you understand what will be
lost before running it. If you are unsure, inspect the diff or save a copy
first. Commands that discard changes or rewrite history can cause lasting
problems. |
Understand Cursor
checkpoints versus Git
Cursor may
provide automatic checkpoints for Agent changes. These can help you restore an
earlier state during an editing session, but they are not a replacement for
version control.
|
Feature |
Cursor checkpoints |
Git |
|
Main purpose |
Restore certain Agent changes |
Track project history and versions |
|
Long-term history |
Temporary safety net; checkpoints may be cleaned up |
Preserves committed history |
|
Manual edits |
Not tracked by Agent checkpoints |
Tracked when included in
commits |
|
Collaboration |
Not a substitute for shared version control |
Supports collaboration through repositories and remotes |
Checkpoint
availability and behavior depend on the Cursor version and workflow. Git is the
better choice for deliberate, durable project history; checkpoints provide an
additional recovery option for supported Agent changes.
|
TIP Best practice: Preserve a
known-good version before major changes, inspect the diff afterward, and test
the result before committing it. |
AI-assisted
development raises questions beyond whether the generated code works. You also
need to consider what information is sent to AI services, what actions an Agent
can perform, and whether the resulting code follows secure practices.
Understand Cursor’s
Privacy Mode
Cursor’s
Privacy Mode is designed to prevent customer code and data from being used to
train Cursor’s models or those of its AI model providers. According to Cursor’s
published data-use documentation, Privacy Mode also comes with
zero-data-retention arrangements for supported model providers, subject to the
documented exceptions and the model or workflow being used.
Several
distinctions matter:
● AI requests still
process data. Prompts
and relevant code context may be sent to the services needed to generate
responses. Privacy Mode does not mean that no data leaves your computer.
●
The exact data-handling
terms matter. Cursor’s documentation describes its retention practices,
provider arrangements, and exceptions. Review the current terms rather than
assuming every model or feature follows identical rules. In particular, Cursor may still store some code
data to provide certain features.
● Team policies may apply. An organization may enforce
privacy settings for its members, and team accounts may have Privacy Mode
enabled by default. The setting you can choose may therefore depend on your
account or workspace.
To check the setting, open Cursor Settings and
look for Privacy Mode, commonly under General. You can open Cursor
Settings from the application menu or by searching for it in the command
palette. Interface labels and locations may change, so consult the official
Cursor privacy documentation if necessary.
For sensitive
projects, verify the requirements that apply to your account, organization,
selected model, and workflow. Do not assume that ordinary editor requests,
third-party integrations, and cloud-based Agent workflows all have identical
data-handling arrangements.
Privacy Mode is
an important protection, but it does not automatically make every workflow
appropriate for confidential, regulated, or highly sensitive information.
Follow your employer’s policies and applicable contractual and legal
requirements.
Never expose secrets
unnecessarily
Avoid placing
passwords, API keys, private tokens, database credentials, or confidential
customer information in prompts. For example, do not paste a live production
token when asking Cursor to debug an API request. Replace it with a
placeholder:
|
Authorization: Bearer
YOUR_API_TOKEN |
Keep real
secrets in environment variables or an appropriate secrets manager. Exclude
secret files from version control, and configure .gitignore before committing
files.
If a secret has
already been exposed in code or a conversation, deleting the visible text is
not enough. Revoke or rotate the credential, assess where it may have been
used, and follow the appropriate incident-response procedure.
You can also
use .cursorignore to restrict which files Cursor
includes in supported code-context and file-access workflows. However, Cursor’s
documentation warns that terminal commands and MCP tools may operate outside
those file-access restrictions. An ignore file is therefore a useful protective
measure, not a universal security boundary.
Review AI-generated
code for security problems
Cursor can help
identify possible vulnerabilities, but its review cannot guarantee that code is
secure. Inspect changes affecting authentication, authorization, file uploads,
database queries, user input, and external commands with particular care.
A focused
review prompt could be:
|
Review these changes for
security risks. Check input validation,
authorization, secret handling, unsafe database queries, and
improper use of external commands. For each finding, identify the
affected code, explain the risk, and recommend a
proportionate fix. Distinguish confirmed issues
from potential concerns. Do not claim that the code is
secure simply because no issues were found. |
Treat the
response as an additional review layer, not a substitute for testing,
established security practices, or a professional assessment when one is
required.
Be careful with Agent
permissions, commands, and external content
Depending on
the task, settings, and enabled tools, Agent can read and modify project files,
run terminal commands, and interact with external tools. Review commands that
install packages, delete files, change configuration, access external services,
or modify databases. Keep appropriate approval and execution safeguards
enabled, and do not run unfamiliar commands merely because Cursor recommends
them.
Two additional
risks deserve attention:
● Prompt injection: Files, web pages, issues, and
documentation may contain instructions designed to manipulate an AI agent.
Treat external content as information to evaluate, not as automatically
trustworthy instructions. Review proposed actions before approving them.
● External tools and MCP servers: Connecting third-party
tools can expand what an Agent can access. Use trusted sources, grant only the
permissions required, and understand what information each integration can read
or modify.
For
professional projects, follow your organization’s rules for approved AI tools,
data access, dependency management, code review, and confidential information.
Cursor’s security controls are useful safeguards, but they do not eliminate the
need for human oversight.
Once your
workflow is secure, the following habits can help you get more value from
Cursor without sacrificing code quality.
● Match the tool to the task. Use inline editing for small,
local changes; chat or question-oriented workflows for explanations and
investigation; and Agent for tasks that require coordinated edits or command
execution.
● Keep tasks focused. Define one milestone at a time and
give it observable acceptance criteria.
● Reuse project instructions. Store stable coding
conventions and architectural requirements in project rules instead of
repeating them in every conversation.
● Provide relevant context. Reference the files that matter
and explain how they relate to the task. Unrelated context can make the request
less focused.
● Automate repeatable checks. Use the project’s existing
tests, linters, formatters, and type checkers. Ask Cursor to interpret
failures, then verify the results.
● Use Git consistently. Commit meaningful milestones,
inspect diffs, and keep secrets out of version control.
● Ask for explanations when learning. If Cursor generates
an unfamiliar pattern, ask why it was chosen and what alternatives exist.
● Avoid unnecessary rewrites. Prefer targeted changes when
they meet the requirements. Large rewrites introduce more assumptions and
create more behavior to verify.
● Document important decisions. Keep setup instructions,
design choices, and known limitations in the project’s documentation so future
work does not depend entirely on chat history.
● Evaluate the actual result. A generated solution is
valuable when it saves effort without introducing excessive review, debugging,
or maintenance costs. Judge the final result, not just how quickly the code
appeared.
|
Quick
checklist before accepting an AI change ●
My working code is
committed, or I have another reliable recovery plan. ●
I reviewed the diff and
every relevant changed file. ●
I understand the purpose
of the new code. ●
I checked for secrets,
unnecessary dependencies, and unrelated edits. ●
I ran the relevant tests
and inspected their actual output. ●
I reviewed any commands
or packages the AI proposed. |
|
TRY IT NOW Practice
exercise. Choose a small project, such as a simple task tracker. Ask
Cursor to add one feature using the five-part prompt structure from Section
10.1. Before accepting the result,
preserve your working version, review the diff, and run the checklist above.
Then ask Cursor to explain the new code step by step and describe, in your
own words, what each part does. If you cannot explain a particular section,
use that as a starting point for further study. |
|
KEY IDEA A reliable Cursor workflow
combines clear instructions, controlled changes, meaningful tests, and
version control. Use AI to accelerate your work, but remain responsible for
the code you accept, the information you share, and the behavior of the
software you build. |
Choosing a coding tool can be confusing,
especially for beginners who are still learning how to write, understand, and
debug code. Cursor, Visual Studio Code (VS Code), and GitHub Copilot are
closely related, but they serve different roles in a development workflow.
Cursor is an
AI-focused code editor with integrated tools for understanding codebases,
generating code, and coordinating changes across multiple files. VS Code is a
general-purpose code editor that can be extended with AI features and other
development tools. GitHub Copilot is an AI coding assistant that provides code
suggestions, chat, and agent-based workflows in supported environments,
including VS Code.
The key
distinction is that Cursor combines an editor with integrated AI capabilities,
VS Code provides an extensible editing environment, and GitHub Copilot adds AI
assistance to supported development workflows. These categories overlap: both
Cursor and modern VS Code workflows can use AI agents to work across files and
help with multi-step coding tasks.
|
Chapter at
a glance ●
Cursor is an AI-focused
editor, VS Code is a flexible editor, and Copilot is an AI coding assistant. ●
Their capabilities
overlap, so compare practical workflows rather than relying on product
labels. ●
Features, usage limits,
and prices change. Check official sources before paying for a plan. ●
Choose according to your
experience, budget, existing setup, and preferred way of working. ●
Whichever tool you
choose, review changes, test the results, and use Git to protect your work. |
The main
differences involve how each tool is organized, how AI features are accessed,
and how much control users have over their development environment.
Cursor AI
Cursor is designed around AI-assisted programming.
Its features help developers explore projects, generate code, edit
multiple files, investigate errors, and carry out coding tasks through Agent
mode.
For beginners,
this integrated approach can make it easier to move from a written instruction
to a working implementation. Cursor can inspect relevant files, propose or
apply changes, and help run checks. It can also explain unfamiliar code and
suggest improvements, although its output still needs to be reviewed and
tested.
Cursor is
particularly useful if you want AI assistance to be a central part of your
everyday coding workflow rather than an optional addition.
Visual Studio Code (VS Code)
VS Code is a
flexible, general-purpose code editor that supports a wide range of programming
languages, extensions, debugging tools, and development workflows. Its core
editor is free to use, and you can add AI capabilities through supported
features and extensions.
With
appropriate AI tools enabled, VS Code can support code suggestions,
explanations, chat, planning, and agent-based tasks. It is therefore inaccurate
to assume that VS Code is limited to manual coding or cannot support complex
changes across multiple files.
Its main
advantage is flexibility. You can choose your extensions, configure your
environment, and combine different development tools. The trade-off is that you
may need to spend more time selecting and configuring your preferred AI
workflow.
GitHub Copilot
GitHub Copilot
is an AI coding assistant rather than a standalone code editor in the same
sense as VS Code. It can provide code completions, answer programming
questions, suggest edits, and support agent-based development in compatible
environments.
When used with
VS Code, Copilot can work alongside the editor, terminal, debugger, and testing
tools. It is also available in other supported environments, although its
features can differ depending on where you use it.
Copilot is a
strong option if you want AI assistance while keeping your existing editor and
development setup. It is also worth considering if your workflow relies heavily
on GitHub.
|
KEY IDEA In short, these tools are not
mutually exclusive. VS Code and GitHub Copilot are commonly used together,
while Cursor combines an editor and integrated AI features in one
environment. |
The following
table summarizes the practical differences beginners are most likely to notice.
|
Feature |
Cursor AI |
VS Code |
GitHub Copilot |
|
Primary role |
AI-focused code editor |
General-purpose code editor |
AI coding assistant |
|
Where it works |
Cursor's own editor and supported Cursor interfaces |
Desktop and supported web environments |
Supported editors and other GitHub environments |
|
AI integration |
Built into the editor |
Available through compatible AI features and extensions |
Integrated into supported editors and environments |
|
Code completion |
Built-in AI completion |
Language-aware completion; AI completion through compatible
tools |
AI completion in supported environments |
|
Code explanations and chat |
Yes |
Available with compatible AI tools |
Available through supported Copilot features |
|
Multi-file changes |
Supported through Agent workflows |
Supported through compatible agent workflows |
Supported through agent features in compatible environments |
|
Debugging assistance |
Can help investigate errors and propose fixes |
Includes debugging tools; AI help depends on enabled
features |
Can help investigate errors and propose fixes |
|
Extensions |
VS Code-style extension ecosystem, with compatibility
differences |
Extensive extension ecosystem |
Integrates with supported editors and development
environments |
|
Customization |
Editor settings, rules, and AI workflow options |
Highly configurable editor and extension ecosystem |
Features and settings depend on the environment and plan |
|
Privacy controls |
Privacy settings and project ignore options; see Section
10.5 |
Depend on the editor configuration and enabled AI tools |
Depend on the plan, organization policies, and settings |
|
Cost |
Free and paid plans, with varying usage limits |
Core editor is free; AI
features may have separate costs |
Free and paid plans, with varying features and usage
allowances |
|
Best suited for |
Developers who want AI integrated throughout their workflow |
Developers who value flexibility and control |
Developers who want AI assistance in an existing supported
workflow |
|
WATCH OUT Important: Features, model
availability, usage limits, billing models, and prices can change. GitHub
Copilot's billing arrangements, for example, have evolved to include
usage-based credits for certain features and plans. The included allowance
and the cost of additional usage depend on the applicable plan and current
billing rules. Check the official pricing and billing documentation before
purchasing a subscription or choosing a tool for professional use. |
A Practical Example
Suppose you
want to add a search feature to the task tracker introduced in Section 7.
With Cursor,
you could ask Agent to inspect the project, identify the relevant files,
implement the search field and filtering logic, and help run checks on the
result.
With VS Code,
you could use its editor and development tools directly, then use a compatible
AI extension or agent workflow to plan and implement the feature. The exact
steps depend on which AI tools you have enabled.
With GitHub
Copilot, you could ask for help designing the search behavior, generate or edit
code, and use supported agent features to coordinate changes across files.
All three
approaches can help you achieve the same goal. The difference lies in how the
tools are integrated, which capabilities are available to you, and how much
setup you prefer to manage yourself.
Regardless of
the tool, review the proposed changes, test the search behavior, and confirm
that existing task creation, completion, and deletion still work.
The best choice
depends on your experience, budget, existing workflow, and the type of
assistance you need. There is no single tool that is best for every developer.
Choose Cursor if...
● You want AI assistance integrated directly into your coding
environment.
● You frequently need help understanding unfamiliar projects or
changing several files.
● You prefer describing a task in natural language and reviewing
the proposed implementation.
● You want to use AI for code generation, debugging, refactoring,
and project exploration in one editor.
Cursor is a
reasonable starting point for beginners who want to learn by building small
projects with AI assistance. However, using it effectively still requires
understanding the code it produces and testing the results.
Choose VS Code if...
● You want a flexible editor that you can configure around your
needs.
● You prefer choosing your own extensions and AI tools.
● You already have a development environment that works well for
you.
● You want to begin with a free editor and add AI capabilities as
your needs evolve.
VS Code is also
an excellent choice for learning programming fundamentals. You can start by
writing code manually and introduce AI assistance as your projects become more
complex.
Choose GitHub Copilot
if...
● You want AI assistance without necessarily switching editors.
● You value inline code suggestions while writing and modifying
code.
● You want conversational help with explanations, tests,
debugging, or supported agent-based tasks.
● Your existing workflow already uses GitHub or an editor that
supports Copilot.
Before choosing
a plan, compare its included features and usage limits with your actual needs.
A free allowance may be enough for occasional questions and small coding tasks,
while intensive agent workflows may require more usage.
Quick Decision Guide
|
If your main need is... |
A sensible starting point |
|
An AI-focused
editor for learning by building |
Cursor |
|
A free,
flexible editor with control over your setup |
VS Code, adding AI features gradually |
|
AI assistance inside an editor you already use |
GitHub Copilot |
|
AI features
integrated into a GitHub-centered workflow |
GitHub Copilot |
|
Exploring and changing a large unfamiliar project |
Cursor or VS Code with a capable agent workflow |
Can You Use More Than
One?
Yes. Developers
can try different tools and choose the one that best fits their workflow. When
learning or comparing tools, however, it is often simpler to use one primary
setup for a project. This makes it easier to understand which tool produced a
change and to review the resulting code.
You can still
use other tools when they offer a clear benefit. Avoid allowing overlapping
suggestions, extensions, or automated changes to make the project harder to
understand and maintain.
Final Recommendation
for Beginners
If you are
learning to code and want an AI-focused environment, try Cursor's available
free offering, if it suits your needs, and build a small project such as a task
tracker. If you already use VS Code, try its available AI options before
deciding whether switching editors would provide enough additional value.
You can compare
two tools using the same small task. Ask each to explain an existing function,
implement one clearly defined feature, and help you test it. Then evaluate each
tool against five criteria:
1.
Quality: Is the
code correct and consistent with the project?
2.
Clarity: Are the
explanations easy to understand?
3.
Review effort:
How difficult is it to inspect and verify the changes?
4.
Usage limits: Do
the available limits fit your typical workload?
5.
Comfort: Does
the tool fit the way you prefer to work?
|
KEY IDEA Whichever tool you choose, commit
your work to Git before major changes, review every diff, and test the
results. Treat AI as a coding assistant rather than a replacement for
understanding. The most useful tool is the one that helps you learn, work
efficiently, and maintain code you can explain, test, and improve yourself. |
If you are new
to Cursor AI, you may have questions about its cost, supported programming
languages, safety, and usefulness in real development work. The following
answers address common concerns and help you decide whether Cursor fits your
needs.
Quick
answers
|
Question |
Short answer |
|
Is Cursor free? |
Yes. A free plan offers limited AI usage; paid plans
provide different usage allowances and features. |
|
Can beginners use it? |
Yes, especially when they use it to understand and practice
programming rather than skip learning. |
|
Which languages does it support? |
Many major programming languages, although running and
debugging code may require additional tools. |
|
Does it replace programmers? |
No. Human judgment, testing, and responsibility remain
essential. |
|
Is it suitable for professional work? |
Yes, provided developers follow disciplined review,
testing, and security practices. |
|
Is it safe? |
It can be used responsibly, but privacy settings and
security precautions still matter. |
Yes. Cursor
offers a free plan with limited AI usage, typically including a limited number
of Agent requests and Tab completions. Paid plans offer different usage
allowances and additional capabilities. Because plans, prices, and included
features can change, check the official Cursor pricing page before subscribing.
For beginners,
the free plan is a sensible starting point. Use it to learn the interface,
experiment with prompts, build a small project, and determine whether the
available limits meet your needs. Consider upgrading only when you regularly
reach those limits or need features that are not included in your plan.
|
TIP Check how usage is measured
before choosing a paid plan. Your model selection and the complexity of an
Agent task can affect how quickly you use your allowance. Do not assume that
a subscription provides unlimited access to every model or feature. |
Yes. Cursor can
help people who are learning programming, even if they have little experience.
You can describe what you want to build in everyday language, ask for
explanations of unfamiliar code, and get help investigating errors.
For example, a
beginner could ask:
|
Explain this Python function
line by line. Use simple language, show a
small example, and point out any assumptions I should
understand before modifying it. |
Cursor can help
you create a simple website, practice Python, explore an existing project, or
improve a small application step by step.
However, using Cursor does not remove the need to
learn programming fundamentals. AI-generated code can contain mistakes,
misunderstand requirements, or introduce unnecessary complexity. Copying code
without understanding it can make debugging and maintaining a project more
difficult.
A productive
learning loop looks like this:
1.
Ask Cursor to explain a
solution or a piece of code.
2.
Read the generated code
and identify what each part does.
3.
Make a small change
yourself.
4.
Run the code and test
the result.
5.
Gradually take
responsibility for more of the implementation instead of letting the AI make
every decision.
The goal is not
simply to produce working code. It is to understand why the solution works and
how to improve it.
Cursor supports
workflows involving many major programming languages. Its AI features can help
you write, understand, edit, and debug code, while editor extensions provide
additional language-specific functionality.
Common examples
include:
● Python: automation, data processing, scripting, and
backend development.
● JavaScript and TypeScript: interactive websites, web
applications, and server-side development.
● HTML and CSS: page structure, styling, and responsive
layouts.
● Java and C#: application development and larger software
projects.
● C and C++: systems programming and performance-sensitive
applications.
● Go and Rust: backend services, command-line tools, and
systems software.
● Swift: applications for Apple’s platforms.
● PHP, Ruby, Kotlin, and SQL: web development, application
development, and database work.
This list is
illustrative rather than exhaustive. The quality of AI assistance varies
according to the language, framework, libraries, model, and context available
to Cursor. Support for a language does not guarantee that every library or
specialized tool will be handled correctly.
Cursor is an
editor with AI capabilities, not a replacement for a language’s runtime,
compiler, or development environment. Depending on your project, you may need
to install Python, Node.js, a Java or C++ compiler, Xcode, a database, or other
tools before you can run and test your code.
For better
results, specify the language and framework in your prompt, provide relevant
project files or documentation, and ask Cursor to follow the conventions
already used in your codebase. Install suitable extensions when you need
language-specific diagnostics, formatting, syntax highlighting, or debugging
support.
No. Cursor can
automate or accelerate many coding tasks, but it does not eliminate the need
for human judgment, technical knowledge, or responsibility.
It can generate
boilerplate code, explain unfamiliar functions, suggest fixes, draft tests, and
help implement features across multiple files. These capabilities can reduce
repetitive work and help developers explore possible solutions more quickly.
However,
software development involves much more than producing code. Someone still
needs to understand the problem, define requirements, make architectural
decisions, evaluate trade-offs, protect sensitive information, verify behavior,
and maintain the software over time.
For example,
Cursor might generate a login feature that appears to work but handles
passwords insecurely. A developer must recognize the potential security
implications, review the implementation, and verify that it meets the
application’s requirements.
The most useful
way to think about Cursor is as a coding assistant that can take on substantial
tasks while remaining subject to human review. Developers who understand their
tools and can evaluate AI-generated work are better positioned to use these capabilities
effectively.
Yes. Cursor can
support professional software development, from maintaining existing
applications to implementing features and investigating difficult bugs. Its
codebase-aware workflows can help developers navigate unfamiliar repositories,
plan changes, refactor code, generate documentation, and work across multiple
files.
For example,
when joining an unfamiliar project, a developer can ask Cursor to summarize the
architecture, trace how a feature works, identify the relevant files, and
propose an implementation plan before making changes.
Professional
use still requires disciplined engineering practices. Developers should review
diffs, run the project’s tests and other checks, use version control, evaluate
dependencies, and verify the behavior of generated code. For larger changes,
planning and incremental implementation are generally safer than asking an
agent to modify an entire project at once.
Teams should
also consider privacy requirements, access controls, approved integrations,
usage limits, licensing and intellectual-property policies, and organizational
rules before adopting AI coding tools. Cursor’s suitability depends not only on
its features but also on how well it fits the team’s workflow and security
requirements.
A practical way
to evaluate Cursor professionally is to try it on a small, well-defined task in
a representative project. Compare the result with your usual workflow,
including the time needed to review, test, and correct the changes. This gives you a more useful assessment
than measuring coding speed alone.
Cursor can be used responsibly when its privacy
settings, permissions, and AI-generated changes are handled carefully. However,
no AI coding tool should be assumed to be risk-free.
Before using
Cursor on a personal or professional project, consider these precautions:
● Review privacy settings: Understand how Privacy Mode
affects the handling of code and related data. Cursor states that, with Privacy
Mode enabled, code is not used to train its or its model providers’ AI models.
Prompts and relevant code context may still be sent to service providers to
process AI requests. For teams, Privacy Mode may be enabled by default and
enforced by administrators. Review the current Cursor privacy documentation and
security documentation for the applicable details.
● Protect credentials: Avoid placing real API keys,
passwords, access tokens, or private certificates in prompts or source files
unnecessarily. Use environment variables or an appropriate secrets-management
system.
● Review generated changes: AI-generated code may introduce
security vulnerabilities, expose sensitive information, or weaken existing
safeguards.
● Control agent permissions: Inspect terminal commands and
proposed file changes before approving actions that could delete data, install
packages, modify configuration, or affect external services.
● Treat external content with caution: Files, web pages,
and documentation may contain malicious or misleading instructions designed to
manipulate an AI agent. Review proposed actions before approving them.
● Evaluate dependencies and integrations: Review unfamiliar
packages, extensions, MCP servers, and other connected tools before granting
access.
● Use version control: Keep a clean Git history so you can
inspect changes and recover from mistakes.
Privacy Mode
can reduce certain data-use risks, but it does not guarantee that generated
code is secure or that every workflow is risk-free. Files such as .cursorignore
can help control which files are included in supported AI workflows, but they
should not be treated as a universal security boundary.
For a more
detailed discussion of Privacy Mode, .cursorignore, credential protection, and
agent-related risks, see Section 10.5: Code Security and Privacy (Including
Privacy Mode).
|
KEY IDEA The central rule is simple: treat
Cursor as a powerful assistant, not as a security guarantee. Protect your
data, limit unnecessary permissions, and verify the code before relying on
it. |
Cursor AI can make learning to code and building
software more approachable. It can help you write code, understand
unfamiliar projects, fix errors, and implement features through
natural-language instructions. Good results, however, require more than writing
prompts and accepting whatever the AI generates.
The most
reliable approach is to work in small, manageable steps. Start with a clear
goal, give the AI relevant context, review its proposed changes, and test the
result before moving forward. Use Git to protect your progress, learn from the
code Cursor produces, and pay attention to security and privacy when working
with real projects.
If you are a
beginner, you do not need to master every feature before you begin. Choose a
small project, such as a personal website, a task tracker, or a simple Python
program, and build it gradually. Ask questions whenever something is unclear,
and experiment with different approaches. Each project will strengthen both
your programming skills and your ability to work effectively with AI.
1.
Choose a small project
and define its goal and acceptance criteria before writing your first prompt.
2.
Commit your starting
point to Git so you can track your progress and recover from mistakes.
3.
Make one focused change
at a time, reviewing and testing each change before continuing.
4.
Learn from the results
by asking Cursor to explain unfamiliar code and making sure you understand the
changes you keep.
|
WATCH OUT Two habits are worth adopting
from the beginning: never expose real passwords, API keys, or access tokens
in prompts, and never accept code changes you cannot explain or adequately
verify. |
Ultimately,
Cursor is a tool, not a substitute for understanding software development. Its
suggestions can accelerate your work, but your judgment remains essential for
deciding what to build, whether the code is correct, and how to improve it.
|
KEY IDEA Start small, review carefully,
and learn from every change. The more you understand the code you build, the
more effectively you can use AI to build better software. |
● Cursor. Official Documentation. https://cursor.com/docs
● Cursor. Quickstart: Your First Useful Change. https://cursor.com/docs/get-started/quickstart
●
Cursor. Download Cursor. https://cursor.com/downloads
● Cursor. Tab Completion. https://cursor.com/help/ai-features/tab
●
Cursor. Inline Edit. https://cursor.com/help/ai-features/inline-edit
● Cursor. Agent Overview. https://cursor.com/docs/agent/overview
● Cursor. Prompting Agents and Adding Context. https://cursor.com/docs/agent/prompting
● Cursor. Planning (Plan Mode). https://cursor.com/docs/agent/plan-mode
● Cursor. Rules. https://cursor.com/docs/rules
● Cursor. Model Context
Protocol (MCP). https://cursor.com/docs/mcp
● Cursor. Keyboard Shortcuts. https://cursor.com/docs/reference/keyboard-shortcuts
● Cursor. Debugging with Agent. https://cursor.com/docs/agent/debug-mode
● Cursor. Understand Your Codebase. https://cursor.com/learn/understanding-your-codebase
● Cursor. Reviewing and Testing Code. https://cursor.com/learn/reviewing-testing
● Python Software Foundation. Python 3 Documentation. https://docs.python.org/3/
● MDN Web Docs. HTML: HyperText Markup Language. https://developer.mozilla.org/en-US/docs/Web/HTML
● MDN Web Docs. CSS: Cascading Style Sheets. https://developer.mozilla.org/en-US/docs/Web/CSS
● MDN Web Docs. JavaScript. https://developer.mozilla.org/en-US/docs/Web/JavaScript
● Node.js. Node.js Documentation. https://nodejs.org/docs/latest/api/
● pytest. pytest Documentation. https://docs.pytest.org/en/stable/
● Git. Git Documentation. https://git-scm.com/doc
● Git. gitignore. https://git-scm.com/docs/gitignore
● Git. git-restore. https://git-scm.com/docs/git-restore
●
Visual Studio Code. Documentation. https://code.visualstudio.com/docs
● Visual Studio Code. Using Extensions. https://code.visualstudio.com/docs/getstarted/extensions
●
Cursor. Pricing. https://cursor.com/pricing
● Cursor. Models and Pricing. https://cursor.com/docs/models-and-pricing
● Cursor. Privacy and Data. https://cursor.com/help/security-and-privacy/privacy
● Cursor. Data Use
& Privacy Overview. https://cursor.com/data-use
●
Cursor. Security. https://cursor.com/security
● GitHub. GitHub Copilot Documentation. https://docs.github.com/en/copilot
● GitHub. GitHub Copilot in IDEs. https://docs.github.com/en/copilot/concepts/copilot-surfaces/copilot-in-ides
● GitHub. Using Agent Mode in Your IDE. https://docs.github.com/en/copilot/how-tos/copilot-in-your-ide/use-copilot-agents/use-agent-mode
● GitHub. Plans for GitHub Copilot. https://docs.github.com/en/copilot/get-started/plans
|
NOTE These sources support the
explanations, practical examples, and tool comparisons in this book. Product
interfaces, keyboard shortcuts, available models, pricing, usage limits,
billing models, and privacy policies may change. Consult the relevant
official documentation for the latest details. |


No comments:
Post a Comment