# Start a new project with Cursor's agent

URL: https://developertoolkit.ai/en/cursor-ide/plan/new-project/
Description: Take a one-line brief to a running Next.js scaffold in Cursor: PRD in Plan Mode, project rules first, gates proven to fail, then a first test-backed feature.

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.

**What this page was checked against**

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](/en/cursor-ide/quick-start/). For a feature inside an existing codebase instead of a new one, use the [PRD workflow in Cursor](/en/cursor-ide/quick-start/prd-workflow/).

## 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.

1. **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.

   **Copy-paste prompt: brief to PRD with testable criteria**

   ```text
   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.

2. **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:

   **Copy-paste prompt: project rules from the PRD**

   ```text
   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](/en/cursor-ide/quick-start/project-rules/).

3. **Scaffold the framework yourself, in the terminal.** Run the generator with every choice supplied, so it never stops to ask:

   ```bash
   # 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.

4. **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.

   **Copy-paste prompt: tooling-only scaffold with a verify command**

   ```text
   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:

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

5. **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.

   **Copy-paste prompt: prove the gates bite, then revert**

   ```text
   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.

6. **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:

   ```yaml
   # .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](/en/cursor-ide/ship/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](/en/cursor-ide/build/checkpoints-branching/).

7. **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.

   **Copy-paste prompt: first feature against the PRD**

   ```text
   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](/en/workflows/ship/evidence-bundle/) is thin. How to write criteria that a test can check is in [executable acceptance criteria](/en/workflows/plan/acceptance-criteria/), and the reasoning behind reviewing evidence rather than diffs is in [evidence, not diffs](/en/ladder/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](/en/cursor-ide/plan/architecture/).

**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](/en/cursor-ide/plan/database-design/) — Grow the data model with constraint tests and reversible migrations.
- [Test-driven development in Cursor](/en/cursor-ide/test/testing-tdd/) — Make the fail-first habit from step 7 the default for every feature.
- [Spec-driven development](/en/workflows/plan/spec-driven-development/) — Keep the spec, not the code, as the thing people review, across Cursor, Claude Code and Codex.
- [Plan with Cursor](/en/cursor-ide/plan/) — 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](/en/codex/plan/new-project/) and [project initialisation with Claude Code](/en/claude-code/plan/project-init/).