Start a new project with Cursor's agent

Level 4 How-to Updated 2026-10-12

A new project with Cursor’s agent takes seven steps: turn the brief into a PRD in Plan Mode, write project rules before any code, scaffold the framework, add tooling with one verify command, prove each gate can fail and require it in CI, then build the first feature test-first. The gates, not your reading, then prove the agent’s work.

This page is for the developer who owns a new codebase from an empty directory, and for the tech lead who wants every new repository on the team to start from the same checkable baseline. The situation: your product manager writes “we need something like Trello but simpler, for daily standups, prototype by Thursday”. There is no spec and no wireframe. If you let the agent build features straight away, you get a demo on Thursday and a codebase on Friday that nobody can change safely.

The Cursor 3.x line; the current release on 2026-10-12 is Cursor 3.24 (2026-10-09, Cursor’s release notes). Cursor’s docs list four agent modes, Agent, Ask, Plan and Debug, and Shift+Tab cycles through them; Cmd+I (Ctrl+I on Windows and Linux) opens the Agent panel. Its run modes are Auto-review, Allowlist and Run Everything, and Cursor names no single default model (all checked 2026-10-12). Plan Mode and Rules were first verified against Cursor’s docs on 28 August 2026. The rule-file pattern of Cursor’s SDK agent was read from @cursor/sdk 1.0.32. Package versions were checked with npm view on 26 September 2026: create-next-app 16.3.6, drizzle-orm 0.45.3, drizzle-kit 0.31.11, better-sqlite3 13.0.3, zod 4.6.5, vitest 5.0.2, @playwright/test 1.63.0.

What a Cursor project bootstrap gives you

A PRD in docs/prd.md whose acceptance criteria are written as Given/When/Then statements that map to tests
Two project rules in .cursor/rules/, written before the agent writes any code, that tell every later chat the stack and the command that defines “done”
A tooling-only scaffold with one npm run verify command that runs lint, type check, unit tests and end-to-end tests
A table that shows each gate going red on a deliberate break, which is the evidence that later green runs mean something
Five copy-paste prompts, one per step that needs the agent, and recovery steps for the ways a bootstrap usually fails

Prerequisite: Cursor installed and signed in, Node.js and Git on your PATH. If Cursor is new to you, start with the Cursor quick start. For a feature inside an existing codebase instead of a new one, use the PRD workflow in Cursor.

Bootstrap a new project in Cursor, step by step

The order is the point. Each step leaves a file on disk that the next chat reads, so no step depends on a long conversation surviving. Start each step in a new chat.

Turn the brief into a PRD in Plan Mode. Plan Mode “creates detailed implementation plans before writing any code” (Cursor docs, verified 28 August 2026), so the agent can question the brief without touching files. Create an empty folder, open it in Cursor, open a new chat, switch it to Plan Mode, and paste the prompt below with your PM’s message in place of the quoted brief.

Brief from the product manager: "Something like Trello but simpler, focused on
daily standups, for one team of 8-12 people. Prototype by Thursday."

Act as the senior engineer who has to ship this in two days. Do not write code.
1. Ask me up to five questions whose answers change the scope or the data model.
   Wait for my answers before continuing.
2. Then produce a PRD for docs/prd.md, under 600 words, with these sections:
   - Problem (2-3 sentences) and the single user workflow the MVP must support
   - MVP features, at most five, each with 2-4 acceptance criteria written as
     Given/When/Then. Every criterion must be checkable by an automated test.
   - Out of scope: what we explicitly cut to hit Thursday
   - Stack: Next.js App Router with TypeScript, SQLite through Drizzle ORM,
     Zod for input validation, Vitest for unit tests, Playwright for end-to-end
     tests. Justify any change you would make to this stack in one line.
   - Data model: tables, columns and relationships
   - Risks: the two unknowns to resolve first, and how we will know they are resolved
Be opinionated. Give me decisions, not option lists.

Answer the questions, then leave Plan Mode and ask the agent to write the PRD to docs/prd.md. Read this file properly: it is the one document you review line by line, because everything after it is checked against it.

Write the project rules before any code exists. Write rules as .mdc files in .cursor/rules/; that is the pattern Cursor’s SDK agent (@cursor/sdk 1.0.32) loads, and it reads the frontmatter keys alwaysApply, globs and description: alwaysApply: true applies a rule to every request, globs applies it when matching files are in play, and description lets the agent decide. Cursor’s docs agree: “Project rules live in .cursor/rules as .mdc files”, with the frontmatter keys description, globs and alwaysApply (checked 2026-10-12). Paste this prompt in a new chat:

Read @docs/prd.md. Do not create any application code.
Create two Cursor project rules:

1. .cursor/rules/project.mdc with frontmatter `alwaysApply: true`. Under 40 lines:
   - The stack from the PRD, with major versions
   - Folder layout: src/app for routes, src/db for schema and queries,
     src/lib for domain logic, tests/e2e for Playwright specs,
     unit tests next to the source as *.test.ts
   - "Done" means `npm run verify` exits 0. Never report a task as done otherwise.
   - Never edit an existing test to make it pass; stop and explain instead.
   - Validate every request body with Zod at the route boundary.
   - Secrets go in .env.local, which is gitignored; document names in .env.example.

2. .cursor/rules/database.mdc with frontmatter `globs: src/db/**` and a one-line
   `description`. Under 25 lines: every schema change goes through a generated
   Drizzle migration, never an edit to an applied migration; foreign keys are
   declared explicitly; every query function has a unit test against a
   throwaway SQLite file.

Write concrete rules a reviewer could check, not style advice.

The verify command does not exist yet; the rule names it now so that step 4 has a fixed target. For the full rule syntax and more templates, see project rules in Cursor.

Scaffold the framework yourself, in the terminal. Run the generator with every choice supplied, so it never stops to ask:
Terminal window
```
# In the project folder, in Cursor's terminal or your own
npx create-next-app@16.3.6 . --ts --tailwind --eslint --app --src-dir --use-npm --yes
```
The generator accepts a folder that already holds docs/ and .cursor/. By default it also writes an AGENTS.md with Next.js guidance and initialises a Git repository (pass --no-agents-md or --disable-git to skip either). Cursor supports AGENTS.md in the project root and subdirectories, so the agent reads that file too (Cursor docs, checked 2026-10-12). Running the generator yourself rather than through the agent keeps the one step that downloads a template out of the chat, and its output is a known template rather than generated code.

Add the tooling and one verify command, and no features. The agent now installs the rest of the stack and wires the gates. Keep features out of this step: a scaffold that already contains half a board is harder to check.

Read @docs/prd.md and follow the project rules.
Add the tooling for this stack. Do not build any feature from the PRD.

1. Install drizzle-orm, better-sqlite3 and zod; install drizzle-kit, vitest,
   @playwright/test and @types/better-sqlite3 as dev dependencies.
2. Create src/db/schema.ts with the PRD's tables, a drizzle.config.ts that uses
   SQLite at ./data/dev.db, and generate the first migration. Add ./data/ to .gitignore.
3. Add package.json scripts: db:generate, db:migrate, lint (eslint --max-warnings=0),
   typecheck (tsc --noEmit), test (vitest run), test:e2e (playwright test), and
   verify = lint + typecheck + test + test:e2e, in that order, failing on the first error.
   Run `npx playwright install chromium` once.
4. Add one unit test that inserts and reads a row through Drizzle against a
   temporary SQLite file, and one Playwright test that loads / and checks the
   page title. Configure Playwright to start the dev server itself.
5. Run `npm run verify` and paste the last 30 lines of its output.
Stop and show me the error if any command fails. Do not work around a failing
check by skipping or deleting it.

Approve each terminal command the agent proposes unless your run mode lets it run commands without asking. Cursor’s run modes are Auto-review (the recommended default since Cursor 3.6: allowlisted calls run immediately, and other shell commands run in the sandbox when possible), Allowlist (actions on your allowlist run without approval) and Run Everything (every tool call runs automatically). You choose one in Settings > Agents > Approvals & Execution, and Cursor’s docs describe them on the Run modes page, under Agent security (checked 2026-10-12).

When verify passes, commit everything so far. Step 5 reverts its probes against this commit, and git restore only works on files Git already tracks:

git add -A
git commit -m "Baseline: PRD, project rules, tooling and verify gate"

Prove every gate can fail. A green verify on day zero proves nothing until you have seen each gate go red. This step is what lets you trust later agent work without reading all of it.

I want evidence that each check in `npm run verify` can fail. For each gate:
1. Make the smallest change that should break only that gate:
   - lint: add an unused variable in src/app/page.tsx
   - typecheck: add `export const typecheckProbe: string = 1;` to src/db/schema.ts
   - test: change the expected value in the Drizzle unit test
   - test:e2e: change the expected page title in the Playwright test
2. Run `npm run verify` and report which gate failed and its exit code.
3. Revert with `git restore <file>` and confirm `git status --short` shows no
   changes to tracked files.
Finish with a table: gate, breaking change, failed as expected (yes/no), exit code.
If a gate did not fail, stop and explain why instead of fixing it.

A “no” in that table is the most valuable output of the whole bootstrap. Fix that gate, then run the prompt again.

Make the baseline a required check. If step 5 made you fix a gate, commit that fix now, so the baseline is the version whose gates you have seen fail. Then add a CI job that runs npm ci, npx playwright install --with-deps chromium and npm run verify on every pull request. It installs only Chromium, the same browser as your local setup, so CI and your machine test the same thing:
.github/workflows/verify.yml
```
name: verify
on: [pull_request]
permissions:
  contents: read
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: lts/*
          cache: npm
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npm run verify
```
Push it, then make the verify job a required status check in the branch protection rules for main. The agent’s local run is a preview; CI is the gate. That holds only while the agent’s pull request cannot rewrite the gate: on pull_request, GitHub runs verify.yml from the pull request itself, and npm run verify comes from its package.json. Put /.github/ and package.json under CODEOWNERS with a required code-owner review, and treat any diff to them in a feature pull request as a finding. Cursor in CI/CD covers running Cursor’s agent inside such a workflow. Git commits are the restore points you control; for how they combine with Cursor’s own checkpoints, see checkpoints and branching.

Build the first feature test-first from the PRD. Create a branch first: git switch -c feat/move-card. The feature lands on main through a pull request that the required check gates. Open a new chat in Plan Mode and pick one MVP feature. The plan names its tests before the agent writes code, and each milestone ends with a verify run.

Read @docs/prd.md and @src/db/schema.ts. Plan the "move a card between columns"
feature. Do not edit files yet.

The plan must contain:
1. For each acceptance criterion of this feature in the PRD, the name and file
   of the test that proves it: Vitest for domain logic, Playwright for the
   drag-and-drop flow. Each test must fail before the change.
2. Files to create or change, and files you must not touch (existing tests,
   applied migrations).
3. Milestones small enough to revert on their own; each ends with
   `npm run verify` passing.
4. The simplest approach that meets the criteria for 12 users: no WebSockets
   unless a criterion requires live updates, no new services.
End with open questions instead of guessing.

Review the plan against the PRD, not against your taste: every acceptance criterion needs a named test. Then build it. Write the tests first and confirm they fail, then implement. Push the branch and open the pull request. Each later feature, including sign-in, goes through this same step.

How do you check the scaffold without reading every generated file?

You read two things line by line, the PRD and the two rules, because they are short and everything else is checked against them. Everything else is checked by evidence:

What you need to know	Evidence	Where it comes from
The gates can catch a mistake	The gate table from step 5 with “yes” in every row	The prove-the-gates prompt
The agent follows the rules	In a new chat, ask “Which command proves a change is done here, and which files may you not edit?” The answer quotes `npm run verify` and the test rule	`.cursor/rules/project.mdc`
The feature does what the PRD says	Each acceptance criterion maps to a test name that failed before and passes after	The step 7 plan and the test run
The change stayed in scope	`git diff --stat main...HEAD` lists only files named in the plan	Git
Nothing regressed	The required CI check is green on the pull request	CI running `npm run verify`

Sign-off follows the same split. The developer who owns the project approves the PRD and the rules, and a tech lead approves them when the repository is a team template. After that, reviewers read the plan, the test names and the CI result, and open the diff only where that evidence bundle is thin. How to write criteria that a test can check is in executable acceptance criteria, and the reasoning behind reviewing evidence rather than diffs is in evidence, not diffs.

What breaks when you start a new project with Cursor?

The agent reaches for outdated APIs. Models learn from years of older code, so they suggest Pages Router patterns or an auth library’s older API. For example, the latest tag of next-auth is 4.24.15 while version 5 is on the beta tag (checked 26 September 2026), so an agent that writes version 5 code against a latest install produces type errors. Recovery: pin major versions in project.mdc, and when you add a library, tell the agent which version npm view <package> version reports.

Rules do not seem to apply. The file sits outside .cursor/rules/, has a different extension, or its frontmatter is malformed. The SDK’s loader (@cursor/sdk 1.0.32) reads .cursor/rules/**/*.mdc, so use .mdc and both the IDE and the SDK pick the rule up. Cursor’s docs add that a plain .md file in .cursor/rules is ignored by the rules system (checked 2026-10-12). Recovery: check the file is .mdc with a frontmatter block at the top, then ask the rule-check question from the table above in a new chat. If the answer does not quote npm run verify, the rule is not loaded.

The generator stops with “contains files that could conflict”. create-next-app 16.3.6 tolerates docs/, .cursor/, .git and a few other files, but not, for example, a package.json or a README.md you wrote first. Recovery: move the extra file out, run the generator, then move the file back.

verify is green but tests nothing. A test runner with no matching test files, or a Playwright config that points at the wrong port, can pass or skip silently, and ESLint warnings do not change its exit code, which is why the lint script uses --max-warnings=0. Recovery: this is what step 5 catches. Do not start step 7 until every row in the gate table says “yes”.

The agent edits a test to make it pass. This is the cheapest way for the agent to reach green. Recovery: the “never edit an existing test” line in project.mdc, plus a scope check: if git diff --stat shows a changed test file that the plan did not name, reject the change.

The architecture grows past the brief. Asked to plan a board, the agent proposes WebSockets, a queue and a cache for 12 users. Recovery: put the scale in the prompt (“12 users, two days, one SQLite file”) and reject any plan item that no acceptance criterion requires. For decisions that do matter long term, use architecture design with Cursor.

Later chats contradict earlier decisions. Decisions made in one conversation are gone in the next. Recovery: write every decision into the PRD or a rule, not into chat, and start each step in a new chat that references those files.

Where to go after the first feature ships

Design a database schema with Cursor Grow the data model with constraint tests and reversible migrations.

Test-driven development in Cursor Make the fail-first habit from step 7 the default for every feature.

Spec-driven development Keep the spec, not the code, as the thing people review, across Cursor, Claude Code and Codex.

Plan with Cursor The other planning guides in this section, and the shared Plan Mode session.

The same bootstrap in other tools: start a new project with Codex and project initialisation with Claude Code.