# Cursor for Complete Beginners A practical guide to understanding and using Cursor — written for someone who has never used an AI code editor before. --- ## Table of Contents 1. [The Big Picture](#the-big-picture) 2. [Key Terms (Plain English)](#key-terms-plain-english) 3. [Setting Up](#setting-up) 4. [The Three Places You Work](#the-three-places-you-work) 5. [Ask vs. Agent](#ask-vs-agent) 6. [Talking So It Helps](#talking-so-it-helps) 7. [Giving It the Right Files](#giving-it-the-right-files) 8. [Reviewing What It Changes](#reviewing-what-it-changes) 9. [Rules (Standing Instructions)](#rules-standing-instructions) 10. [The Terminal Inside Cursor](#the-terminal-inside-cursor) 11. [A Simple Daily Loop](#a-simple-daily-loop) 12. [Cursor vs. Other Tools](#cursor-vs-other-tools) 13. [Common Mistakes and How to Avoid Them](#common-mistakes-and-how-to-avoid-them) 14. [Quick Reference Cheat Sheet](#quick-reference-cheat-sheet) 15. [Glossary](#glossary) --- ## The Big Picture ### What problem does Cursor solve? ChatGPT and Claude in a browser are smart — and **blind**. They cannot see your folder, edit your files, or run a command unless you paste everything in and copy everything out. **Cursor** is a text editor with an AI that *can* see the project you opened. You chat on the side. It reads files, proposes edits, and (when you allow it) runs commands. You stay in one window instead of being the copy-paste layer. It is built for: - **Writing and editing** — Markdown, HTML, notes, prompts, code - **Asking about *this* folder** — “what 101 guides do we have?” - **Doing the work** — “write the Terminal guide and put it next to the others” - **Keeping context** — rules and chat history so you do not re-explain yourself every time You do not have to be a developer. If you can open a folder and type a sentence, you can use Cursor. These Aspi 101 pages were written in it. ### The workshop analogy | Real world | Cursor equivalent | |---|---| | A workbench with your project spread out | The **folder** you opened (the workspace) | | The tools on the bench | The **editor** — you can still type by hand | | An apprentice who can see the bench | The **agent** in the chat | | “Don’t touch the finished pieces” | **Ask** mode — look, don’t edit | | “Build the next piece to match these” | **Agent** mode — allowed to change files | | A sticky note on the wall | A **rule** — standing instructions | | Pointing at a drawing | **@** a file or folder so it looks there first | ### What makes Cursor different 1. **It works on files, not just a chat bubble.** Changes show up as real documents on disk. 2. **You open a project.** Context is “this folder,” not the whole internet. 3. **You can say no.** Review diffs. Reject junk. You own the files. 4. **It can use the Terminal** (see the [Terminal 101](https://goaspi.com/101/terminal/)) — still your machine, still your approval when it matters. 5. **It is not Buzz.** Cursor is *your* workshop. [Buzz](https://goaspi.com/101/buzz/) is a *shared room* with teammates and agents. Use both. --- ## Key Terms (Plain English) ### Workspace / folder The project you opened. Example: the TestBot folder that holds these 101 guides. Cursor mostly sees what is in here. ### Editor The big middle pane. A file you opened. You can type like any notes app. ### Chat The side conversation with the AI. This is where you ask and assign work. ### Agent The mode that **can change files** and run tools. Use it when you want something *done*. ### Ask The mode that **answers questions** without editing (or without treating edits as the job). Use it when you want to understand, not rewrite. ### Tab / autocomplete Gray ghost text as you type. Press Tab to accept. Handy; not the same as the Agent. ### @ mention You type `@` and pick a file, folder, or doc. That pins the agent’s attention. Better than “look at the HTML file” when you have six HTML files. ### Diff A view of **what would change** — red removed, green added. Read this before you keep the edit. ### Rule A standing instruction: user rules (all projects) or project rules (this folder). Example: “When you publish a 101, push to main. Do not open a PR.” ### Terminal (in Cursor) The command-line panel inside the app. Same idea as the Mac Terminal app. [Guide](https://goaspi.com/101/terminal/). --- ## Setting Up 1. Download Cursor from [cursor.com](https://cursor.com) and install it. 2. Sign in (you need an account for the agent). 3. **File → Open Folder** and pick the project — not a single file if you can help it. Open the *parent folder* that holds your work. 4. Open the chat (usually the sidebar on the right, or the composer/chat shortcut in the command palette). 5. Confirm you can see your files in the left sidebar. ### First five minutes - Open one file you already know (a `.md` guide). - Switch the chat to **Ask**: “Summarize this file in five bullets.” - If that looks right, switch to **Agent** for a *small* task: “Add a glossary term for ‘prompt’ at the end. Don’t change anything else.” - Look at the diff. Keep or reject. If the agent cannot see your files, you opened the wrong folder — or you never `@` mentioned the file. --- ## The Three Places You Work ``` Sidebar Editor Chat (files) (the page) (the agent) ``` - **Sidebar** — click a file to open it. This is Finder, inside Cursor. - **Editor** — you type. Fine for a typo or a heading you want *exact*. - **Chat** — you describe the job. Fine for “make a whole section” or “match the other 101s.” Beginners get stuck using *only* chat and never looking at the file, or *only* the editor and wondering why the AI “doesn’t know” what they typed. Glance at all three. --- ## Ask vs. Agent This is the most important switch in the product. | | **Ask** | **Agent** | |---|---|---| | **Job** | Explain, find, compare | Create, edit, run, publish | | **Touches files?** | Should not rewrite your project | Yes — that is the point | | **Use when** | “What guides are in this folder?” | “Write the Terminal 101 and add it to the index” | | **Risk** | Low | Higher — review diffs | **Default to Ask** when you are exploring. **Switch to Agent** when you have a clear outcome and you will review the result. Cursor may also offer planning or debug-style modes depending on version. If you see **Plan**, use it when the task is big and you want a design *before* files move. If you see **Debug**, use it when something is already broken and you want evidence, not a rewrite of the whole app. --- ## Talking So It Helps Bad: “Make it better.” Good: “Add a cheat-sheet table at the end, same columns as the GitHub 101. Don’t change the hero.” A usable request usually has: 1. **Outcome** — what should exist when you are done 2. **Where** — which file or folder (`@buzz-for-beginners.md`) 3. **Constraints** — “don’t change the COO prompt,” “match the other guides,” “no PR” 4. **Done look** — “update `/101/` index too” The agent is not a mind reader. It is very good at *this folder* if you point it. ### One job per message (at first) “Write the Terminal guide, the Cursor guide, redesign the homepage, and fix Vercel” is four projects. Split them. You can always send a follow-up. --- ## Giving It the Right Files ### @ mentions Type `@` in the chat and pick: - A **file** — the exact page - A **folder** — “everything in 101” - Sometimes **docs** or other attached context, depending on your setup Use `@` when names are common (`index.html` exists in many projects). ### Open the file If the file is open in the editor, many chats already treat it as “current.” Still `@` it if the task is important. ### Don’t dump the whole company More files is not more intelligence. Extra noise makes wrong edits. Attach the two or three things that matter. --- ## Reviewing What It Changes When the agent edits, Cursor shows a **diff**: - **Green** — added - **Red** — removed Read it like a teammate’s pull request (see [GitHub 101](https://goaspi.com/101/github/)). - Keep the change if it matches what you asked. - Reject or undo if it rewrote a section you needed. - If it “fixed” something you did not mention, be suspicious. **You are the editor-in-chief.** The agent drafts. You ship. Some commands (pushing to a live site, deleting files, talking to the network) may show an **approval** card. That is Cursor being careful. Read the command. Approve only if you asked for that publish or install. --- ## Rules (Standing Instructions) Rules are sticky notes the agent sees at the start of a chat. **User rules** — apply in every project. Good for: how you like to write, “don’t open a PR for Aspi 101,” your name and defaults. **Project rules** — live in the repo (often `.cursor/rules`). Good for: “this site is Eleventy,” “101 pages go in `public/101/`.” Write rules like you write a brief: - When this happens → do this - Do not do that - Concrete paths and names A vague rule (“be helpful”) does nothing. A sharp rule (“push 101s to `aspinalljohn/aspi` `main`; do not open a PR”) changes the path. Rules are **not** a magic override of safety checks. They steer the agent. Approvals for production deploys can still appear. --- ## The Terminal Inside Cursor **View → Terminal** or `` Control + ` ``. This is the same Terminal as in the [Terminal 101](https://goaspi.com/101/terminal/) — `pwd`, `ls`, `cd`, `git status`. The difference: it usually **starts in your project folder**. You skip a lot of `cd`. The **agent** can also run terminal commands. That is useful (`git status`) and dangerous (`rm`). If a command looks like publish-to-production, pause. That is the same habit as not pasting mystery commands into Terminal.app. --- ## A Simple Daily Loop For work like these 101s: 1. **Open the folder** (TestBot, or the site repo). 2. **Ask** — “What’s already here? What would break if we add Terminal and Cursor guides?” 3. **Agent** — “Write `terminal-for-beginners.md` in the same structure as GitHub 101.” 4. **Read the diff.** Skim the file in the editor. 5. **Follow-up** — “Now the HTML page, phosphor-green theme, then the Cursor guide.” 6. **Git** — commit / push if you want it saved (GitHub 101). 7. **Check the live URL** if you published. You can still type a heading yourself. Hybrid is normal. --- ## Cursor vs. Other Tools | Feature | Cursor | ChatGPT / Claude web | VS Code | Buzz | Obsidian | |---|---|---|---|---|---| | **Sees your folder** | ✅ | ❌ unless you paste | ✅ (no agent by default) | ⚠️ Shared workspace | ✅ Vault | | **Edits files for you** | ✅ Agent | ❌ | ⚠️ Extensions | ⚠️ Agents in the room | ⚠️ You / plugins | | **Good for 101 / site work** | ✅ | Drafts only | If you already live there | Team + agents | Notes, not deploys | | **Shared with teammates** | ❌ Your machine | ❌ | ❌ | ✅ | ⚠️ Sync | | **Git / Terminal** | ✅ Built in | ❌ | ✅ | Early Git in Buzz | ❌ | | **Best for** | Building in a project | Thinking out loud | Classic editing | Humans + agents together | Second brain | **Choose Cursor** when the work *is* the files in a folder. **Choose a web chat** when you have no project open and just want to think. **Choose Buzz** when the team (and other agents) should see the same room. **Choose Obsidian** when the artifact is a personal note, not a deploy. **Choose GitHub** to store history — Cursor does not replace that. --- ## Common Mistakes and How to Avoid Them | Mistake | Why it is a problem | Better approach | |---|---|---| | Leaving it on Agent for “just looking” | Unwanted file edits | Use **Ask** to explore | | “Fix everything” | Huge, sloppy diffs | One outcome, one constraint | | Never `@` a file | It edits the wrong `index.html` | `@` the real path | | Accepting every diff | Silent regressions | Read green/red | | No folder opened | Agent has nothing to stand in | **Open Folder** | | Treating chat as the source of truth | Chat is not the file | Open the `.md` / `.html` and read it | | Skipping Git | You cannot undo last Tuesday | Commit when a guide is good | | Pasting secrets into chat | They can land in logs / context | Use env files; don’t paste keys | | Expecting it to know Buzz.com’s UI | It knows what you give it | `@` docs or paste a screenshot description | --- ## Quick Reference Cheat Sheet | I want to… | Do this | |---|---| | Start | Install Cursor → **Open Folder** → open chat | | Understand, not edit | **Ask** mode | | Make or change files | **Agent** mode + a specific outcome | | Point at a file | Type `@` and pick it | | See what changed | Read the **diff** (green / red) | | Undo a bad agent turn | Reject / revert that change | | Standing preferences | User **Rules** or project `.cursor/rules` | | Run `git status` | Terminal panel, or ask the agent to run it | | Learn the black box | [Terminal 101](https://goaspi.com/101/terminal/) | | Save history | [GitHub 101](https://goaspi.com/101/github/) | | Write `.md` | [Markdown 101](https://goaspi.com/101/markdown/) | | Shared agents with a team | [Buzz 101](https://goaspi.com/101/buzz/) | --- ## Glossary | Term | Meaning | |---|---| | **Cursor** | AI editor: your files plus a chat that can work on them | | **Workspace** | The folder you opened | | **Agent** | Mode that may edit files and run tools | | **Ask** | Mode for questions, not a rewrite | | **Diff** | The proposed add/remove view | | **@ mention** | Pin a file, folder, or doc into the chat | | **Rule** | Standing instruction for the agent | | **User rule** | Applies across all your projects | | **Project rule** | Applies in this repo / folder | | **Tab** | Inline autocomplete as you type | | **Approval** | Extra confirm for a sensitive command | | **Hallucination** | Confident wrong answer — check the file | --- Open a folder. Ask first. Agent second. Read the diff. That is the whole product. More Aspi 101: [Terminal](https://goaspi.com/101/terminal/) · [GitHub](https://goaspi.com/101/github/) · [Markdown](https://goaspi.com/101/markdown/) · [Buzz](https://goaspi.com/101/buzz/) · [All 101 Guides](https://goaspi.com/101/).