Cursor Best Practices From Running an Agent on a Large Codebase

The usual list of cursor best practices is short and mostly right: use Plan Mode, keep the context small, review the diff, commit often. If you have been using Cursor on a real project for a few weeks you already do those, and the results are still uneven. One session lands a clean feature. The next renames a concept, passes its own tests, and breaks the type check in a package it did not open.

The habits below come from running an agent every day on a monorepo with several apps and shared packages. Each one exists because something went wrong without it. They are written for Cursor's mechanics: rules, Plan Mode, checkpoints, run modes, hooks and cloud agents.

If you use Cursor mainly for tab completion and single-file edits, skip most of this. It pays back when the agent makes multi-file changes you do not read line by line.

Make the agent prove the change, with more than tests

The most expensive failure we have seen is a green test run that meant nothing. After a test-runner upgrade, tests passed at runtime while the type check failed on every assertion, because the matcher typings had drifted. The agent ran the tests, saw green, and reported the work done.

So the finish line is three commands, in a rule the agent sees in every session: lint the files it edited, run the type check for the app it touched, then run the tests. In Cursor that is a project rule set to Always Apply, kept to a few lines because it is paid for in every chat. Name the exact commands.

Cursor's hooks can enforce the same thing without relying on the model's memory. A project-level .cursor/hooks.json can run a script after a file edit or when the agent stops, which is a reasonable place for a linter.

Get a failing repro before any fix

Ask Cursor to fix a bug and it will read the code, form a theory, and edit three files. You cannot tell from the diff whether the theory was right.

The rule we use: before touching the fix, the agent writes a test that fails on this bug, and runs it red once. Then one hypothesis at a time against that test. The fix is done when the test goes green and the surrounding suite still passes, and the test stays in the codebase as the regression test.

This is where Cursor's checkpoints mislead people. A checkpoint snapshots files during an agent session and lets you undo the agent's edits. It is stored locally, separate from Git, and restoring one reverts files without removing the conversation. That is an undo button, not a record of what was tried. Commit the failing test on its own before the agent starts on the fix. If the session goes sideways, you restore to a commit that still contains the repro.

Give it a glossary and a decision log

Two failures look like carelessness and are really missing information.

The first is synonyms. Over a month, an agent with no vocabulary to follow will call the same thing an account, a user, and a member, in three tables and two route paths. A one-page glossary at the repository root fixes it: one line per term, with the definition. Cursor's own guidance for rules is to reference files instead of copying their contents, so the always-on rule is two sentences: use the terms in the glossary exactly, and add a line when you introduce a concept.

The second is the helpful undo. You chose a query builder over the ORM for one hot path, and three weeks later the agent tidies it back. Short decision records stop that: context, decision, consequences, a few paragraphs each, with a rule telling the agent to read the records for the area before proposing structural changes and to ask before working around one.

Plan Mode fits here. It researches the codebase, asks clarifying questions and writes a plan you can edit before anything is built. Plans are saved outside the repository by default, and there is a "Save to workspace" option. Use it for the plans that contain a decision, so the reasoning sits in the repository for the next session to read.

Say what not to run, and gate what leaves

Agents start things. A dev server already running in your terminal gets started again on another port, and the session spends minutes on a build that only existed to see whether the page renders.

Cloud agents also change what "do not start the server" means. Locally the servers are yours. In a cloud agent's machine nothing is running, and the agent is only as capable as its environment, which Cursor lets you define in .cursor/environment.json. Scope the banned-commands rule to local work, or the cloud agent will refuse to boot the one thing it needs.

Where a foundation helps, and where it does not

Every practice above assumes the repository has something to check against: a type check that crosses the API boundary, a test setup the agent can run, conventions written down. On a new project you can start with those in place instead of writing them in month three.

That is the part we make. Hype Stack is a full-stack TypeScript template, and its agent rules are authored as Cursor .mdc files in .cursor/rules, then converted to other editors' formats when you ask for them. Cursor is the default editor in create, so a new project gets the rules as written: an always-on set, and scoped ones that load only when the agent opens a matching path. They cover backend error handling, feature structure, testing workflow and verification after changes. create also installs a starter set of skills into .agents/skills. The MCP server lets Cursor add accounts, billing or a team workspace through the real installer, and npx @hype-stack/cli@latest mcp install --editor cursor writes the entry into ~/.cursor/mcp.json.

What is not in the box matters more. Rules files do not make an agent correct. They are conventions for one stack. They do nothing for a codebase that is not built on it, and copying them into an existing repository gives the agent confident instructions about files you do not have. The template does not ship your glossary, your decision records or your push gate either, because those describe your product. On an existing codebase, the practices on this page are the work, and no template shortens it.

What you write yourself, on any foundation: the glossary, the decisions, the banned commands, and the table of checks each kind of change needs. A starting point with the rules in place follows below.