Step-by-Step Teaching

Step 1: The Problem Being Solved

Before understanding Projects, understand why it exists.

Traditional AI coding tools work like this:

You → Ask AI → AI writes code → Done

The limitation: each conversation starts fresh, you manage everything manually, and your laptop must stay open.

Projects solves this by moving up one level:

You → Direct a Coordinator → Coordinator manages thousands of agents → Work gets done

🧠 Key mental shift: You stop managing how work gets done and start directing what work gets done.

---

Step 2: What Projects Actually Is

Projects is a persistent, autonomous work system inside Cursor designed for:

Not ideal for: Quick, single questions or small one-off edits.

---

Step 3: The Three Core Capabilities

🖥️ Capability 1: Cloud by Default, Local When Needed

• The Project runs on its own computer in the cloud
• Closing your laptop does not stop the work
• Enables more parallel agents than your machine could handle
• When local testing is needed → coordinator spins up a local agent temporarily

Cloud Agents (parallel, always running)
        ↕
Your Machine (only when local testing needed)

---

📁 Capability 2: Shared Context

This solves the "re-onboarding problem" — having to explain your codebase every time.

How it works:

1. Agents write down what they learn (codebase structure, your preferences, testing methods)
2. These files sync across all agents — cloud and local
3. Each new agent inherits all previous knowledge
4. Context grows over time, making the coordinator smarter

Practical example:

Agent #1 figures out how to test Service X → writes it down → Agent #47 uses those exact instructions without being told

---

🔔 Capability 3: Subscriptions

The coordinator can watch for signals and act without you prompting it.

🧠 Key idea: Projects moves from reactive (you ask → it responds) to proactive (it watches → it acts).

---

Step 4: The Three Usage Patterns

🔨 Pattern 1: Feature Work

Flow:

1. Create Project for the feature
2. Agents research your codebase → store findings as shared context
3. Coordinator creates a plan
4. Agents implement different parts IN PARALLEL
5. You give feedback → Project learns your preferences
6. Coordinator tests locally when ready
7. After shipping → same Project monitors logs and handles bugs

Why it's powerful: The Project retains the reasoning behind decisions, not just the code.

---

🔄 Pattern 2: Migrations

Migrations are "easy to start, hard to finish" — Projects excels here.

Flow:

1. You + coordinator establish a safe approach
2. Coordinator applies it incrementally across codebase
3. Early: you review every PR closely
4. Later: as fixes prove reliable → you review less
5. Coordinator continues working independently

Real example from Cursor: Hundreds of PRs to replace a styling system — handled by one Project.

---

🌱 Pattern 3: Gardening (Ongoing Maintenance)

For work that never ends — code quality, regressions, design consistency.

Real example from Cursor's team:

Start:    Engineer reviews every design-system fix manually
↓
Middle:   Coordinator scans new PRs, extracts reusable components
↓
Now:      Coordinator adds lint rules automatically when it sees repeated mistakes
↓
Goal:     20–100 PRs touched per day, engineer only checks in where needed

---

Step 5: When To Use Projects — Decision Framework

Is this work larger than a single conversation?
        ├── NO  → Use regular Cursor chat
        └── YES ↓
Does it involve multiple PRs, parallel tasks, or ongoing monitoring?
        ├── NO  → Maybe still regular chat
        └── YES → USE PROJECTS

Strong signals to use Projects:

• ✅ Feature spanning multiple PRs
• ✅ Migration across many files
• ✅ Work you want done while you're away
• ✅ Recurring tasks (monitoring, quality checks)

---

Summary: The Big Picture

🎯 One-sentence summary: Projects lets you describe what you want built or maintained, then a coordinator manages thousands of agents to make it happen — continuously, in the cloud, getting smarter over time.