Cursor team workflows in a shared repo

One mental shift decides whether a real team gets value from Cursor.

A great prompt is a personal asset. A great workflow is an organizational one. Adoption stalls when it stays at the prompt layer and it pays off when it moves to the repo layer.

In a shared repo the problem isn't "how do I get the model to do something clever." It's "how do I get fifty people, each prompting differently, to produce changes that look like one disciplined engineer wrote them." That's a governance problem. Your impact is no longer the prompt in your head. It's the artifact checked into the tree.

The progression every team walksad-hoc → governed

1. 1Personal prompts. Each dev has their own habits. They live in one head and die when that person leaves. no team benefit for the team.
2. 2Shared Project RulesVersion-controlled instructions in the repo that every Cursor agent interaction inherits, so standards are encoded once. / `AGENTS.md`. The conventions move into the repo and the model behaves consistently regardless of who's driving.
3. 3Shared commands. Repeatable, named workflows (generate-test, scaffold-endpoint) so the how is encoded once instead of re-typed fifty times.
4. 4Scoped context + ignore controls. You engineer what the agent can see and touch, so it pulls the right files and never the secrets.
5. 5Plan-first, reviewable handoffs. The agent proposes, a human approves and the diff stays small enough to actually read.

Each step trades a little spontaneity for a lot of repeatability. The mature team treats its Cursor configuration the way it treats CI config or lint rules:

• It's part of the codebase.
• It goes through review.
• It's an ITGCIT General Controls. The baseline IT controls auditors check: who can change what, how changes get approved and how systems are run.-adjacent control surface rather than a sticky note.

The governing principle is proximity. The closer a rule lives to the code it governs, the more reliably it's applied and the easier it is to review. Cursor gives you a layered set of places to put intent and a strong field engineer knows which layer each thing goes in.

Project Rules vs AGENTS.md - when to use which

Worth saying in an interview: rules don't replace judgment, they encode defaults. The model still needs a good prompt. It now starts from your team's baseline instead of the internet's average, so fifty drifting styles collapse into one house style.

The actual file mechanics (so you're not hand-waving)where these live and how they fire

Be specific about creation paths and firing behavior - vagueness here is what makes a pitch feel theoretical. A Project Rule is created in Settings > Rules, Skills, and Sub Agents > project > Rules > New > Project rule, which writes a Markdown/MDC file under .cursor/rules with a header carrying its name, description and apply setting. There are four rule types, and the apply setting decides exactly when each one fires:

Commands are the sibling primitive: reusable multi-step slash-prompts created in Settings > Rules, Skills, and Sub Agents > Commands > New, which writes a Markdown file in .cursor/commands. They shine for recurring multi-step jobs - run the test suite, fix compile errors, open a PR, spin up local servers, commit-and-push. A best-practice touch: tell the command how to respond (e.g. 'print the local URL and confirm the server is responding') to cut verbose replies.

In a large repo, getting the right context into the agent is not a prompt-length contest. It's an information-retrieval design problem. Stuffing more text in feels productive and rarely is. The real skill is engineering what the model can find and reach.

Cursor gives you four distinct mechanisms that do different jobs. Confusing them is the most common reason teams get mediocre output on big codebases.

The recall-vs-precision pattern

Use search/indexing for recall when you don't yet know where the relevant code lives. Use @-mentions for precision once you do. The skilled workflow is a funnel:

1. 1Let semantic search surface candidates.
2. 2Pin the exact files with @-mention so the agent works from ground truth instead of a fuzzy memory.

MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. brings the intent (the Jira ticket, the acceptance criteria) alongside the code, so the agent solves the actual business problem rather than its guess of it.

Why precision beats volume - the token rationale

There's a concrete reason @-mention precision wins over pasting more code. An @-mention guarantees the file lands in context instead of hoping semantic search surfaces it - the model reads the exact file, finds the definitions and returns ground truth. @ isn't limited to files: reference a doc, or even a past chat (which summarizes it and reads the transcript, so you inherit the summary without dragging all prior context forward).

And there is a cost lever underneath the proximity rule from the rules section: rules and skills count toward tokens, but only when invoked. A skill costs nothing until the agent chooses it; an always-apply rule rides along on every submission. So glob-scope rules to the files they govern (e.g. *.tsx components) and they only load when a matching file is touched - keeping always-true rules out of unrelated context. Since Cursor 2.4, the harness's dynamic context discoveryThe agent pulling only the relevant parts of files, tools and MCP servers into context as needed, instead of loading everything up front. does the same thing automatically: it pulls in only what it deems relevant rather than loading every file/tool/MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. output, which is part of how it cuts agent tokens by roughly 47% even on other providers' models.

The most dangerous moment in agent-driven development is the green checkmark. "The agent finished" only means it stopped. It tells you nothing about whether the change is correct, scoped or safe to merge. Shaping the change is where senior engineers earn their keep.

The discipline, in four habits

• Small diffs. A reviewable PR is one a human can actually hold in their head. A mega-rewrite PR isn't a productivity win. It's an un-reviewable liability with a huge blast radiusHow much breaks if a change goes wrong; the scope of potential damage..
• Tests as targets. Point the agent at a failing test or a clear acceptance criterion and let it work toward green. "Make this pass" beats "improve this" every time.
• Plan before implement. Have the agent produce a plan you can review before it touches code. Redirecting a plan costs a sentence. Unwinding 600 lines costs an afternoon.
• No mega-rewrite PR. Decompose. If the agent wants to touch thirty files, that's a signal to split the work rather than rubber-stamp it.

The ownership rule (memorize this)

This single rule resolves most of the cultural anxiety around AI code. It does three things at once:

• Preserves separation of dutiesNo single person can author, approve and deploy the same change. The core control AI autonomy has to respect. (the author is still distinct from the reviewer).
• Keeps accountability with a named human.
• Turns AI-code-tracking and audit logs into evidence rather than surveillance.

Provenance stays visible and responsibility stays clear.

Cursor's agent surface is a ladder of increasing autonomy:

• Inline Tab completions.
• The in-IDE agent.
• The CLI agent.
• Cloud agents running in isolated cloud VMs.
• The SDK for programmatic automation.

The governing law: every step up in autonomy demands a step up in guardrails. Each rung gives the agent more blast radiusHow much breaks if a change goes wrong; the scope of potential damage. between human checkpoints and your controls have to cover that gap.

Match the rung to the risk tier

A typo fix in a docs file and a change to the payments authorization path are not the same risk tier and they shouldn't get the same autonomy. Low-risk, well-tested surfaces can run further up the ladder with a lighter touch. High-risk, regulated paths stay low on the ladder, gated by a reviewed plan, mandatory human review and tight allowlists. The cloud agents' isolation (separate VMs, no standing production credentials) is precisely what lets you grant autonomy without granting blast radiusHow much breaks if a change goes wrong; the scope of potential damage..

What each rung actually is

On a team, freeform prompting is noise. Most real work collapses into four repeatable intents and naming them is how you get juniors to operate like seniors. Teach these four and you've taught the workflow.

The capability × SDLC-phase one-pager

Don't talk to a VP of Engineering feature-by-feature. Give them a grid of which capability earns its keep in which phase of the SDLC. That's the artifact that turns a demo into a rollout plan.

Rules encode what. The two newer primitives encode how and who: skills and sub-agents. On a team they matter because they're the same kind of repo artifact a rule is - reviewable, shareable, centrally pushable - not a clever trick living in one person's head.

Skills: agent-invoked, an open cross-tool standard

A skill packages a prompt plus a deterministic standard path (a markdown-backed SKILL.md with name, description and instructions) so the model doesn't re-think a fixed multi-step process every run. Skills are a new open standard supported across Cursor, Claude Code and Codex, and they're portable project-to-project. The non-obvious mechanic: a skill is not auto-loaded every chat. The agent reads its name/description and pulls it in only when it judges it relevant (progressive disclosureHow skills load: the agent boots knowing only each skill's name and description, then pulls a skill's full instructions into context only at the moment it decides to use it.). If a skill isn't firing, the fix is almost always a better description.

Sub-agents: parallel work with isolated context

Sub-agents (shipped in Cursor 2.5) let a parent agent spawn smaller agents that run simultaneously, each with its own contained context window - solving the old multi-tab collision problem where two agents editing the same file would stall. Each sub-agentA child agent a main agent spawns to work in parallel with its own context window, handing results back so the parent's context stays clean. writes its findings to a file; the parent reads the file and pulls only the relevant part into its own context. The payoff: agents run faster, fill the parent context more slowly, cost fewer tokens, and the model stays accurate longer. Three are built in - Explore (understand the codebase), Bash (terminal), Browser - and you can author custom ones.

Heuristic for the parallelism question: if task B is unrelated to task A, start a new chat; if B and C both depend on A's output but are unrelated to each other, use sub-agents. And remember the cost note from the context section - all three primitives sit in the context window, so they count toward tokens only when actually invoked.