Cursor Agent Pipeline: How to Set Up Worktrees, Write Effective Instructions, and Measure Real ROI

The previous two Cursor articles established the architecture and the economics. The architecture article explained why parallel agents in worktrees are the productive unit of work. The cost article explained that Standard-tier generation is now cheap enough to run ten candidates for under a dollar. This article is the missing middle: how to actually set up a pipeline that captures that value without collapsing under its own review burden.

The core failure mode in agentic workflows is not generation quality — it is review capacity. Independent research shows that AI-generated pull requests wait 4.6 times longer for review than human-written ones (DX Research, 2026a). That gap exists because agent output arrives faster than reviewers can process it, because diff surfaces are often larger than they should be, and because reviewers don't trust output they didn't supervise. A well-designed pipeline addresses all three. A poorly-designed one makes each worse.

What follows is a practical setup guide: the two-layer instruction system that shapes agent behavior, the worktree configuration that isolates parallel work, the economics of choosing how many candidates to run, the loop that selects the winner, and the measurement framework that tells you whether any of it is working.

Before you write a single rule

Every agent instruction system amplifies what the codebase already has. If your test suite is sparse, agents will produce untested code and have no way to verify it. If your CI pipeline is slow, the gate between generation and review creates a bottleneck that multiplies with N candidates. If your task definitions are vague, even well-instructed agents will produce diffs that are hard to scope and harder to review. Three prerequisites:

The two-layer instruction system

Cursor supports two complementary instruction mechanisms. Using both correctly is the single highest-leverage configuration change you can make.

AGENTS.md is an open standard (Linux Foundation, adopted across 60,000+ repositories) read natively by Cursor, Codex, GitHub Copilot, Gemini CLI, Aider, Windsurf, and Zed (AGENTS.md, 2026). Place it in your project root and in subdirectories where different rules apply. It is plain Markdown — no special syntax. The agent reads the nearest file in the directory tree; more specific files override less specific ones.

.cursor/rules/*.mdc files provide Cursor-specific scoped overrides. Each .mdc file carries a YAML frontmatter block that controls when the rule activates: always, when specific file globs are matched, when the agent decides the rule is relevant based on a description, or only when manually invoked with @rule-name (Cursor, 2026c).

The practical pattern for 2026: maintain an AGENTS.md at the root as the source of truth for all agents, and use .cursor/rules/ for Cursor-specific auto-attach rules where glob-scoping genuinely matters — for example, enforcing testing conventions automatically whenever a service file is touched.

Writing instructions that change behavior

The most common mistake in agent instructions is writing principles instead of behaviors. "Write clean, well-tested code" changes nothing. "Create a corresponding __tests__/[ClassName].test.ts file for every new class you create, with at least one happy-path and one error-case test" changes what gets committed.

Three techniques that make instructions effective:

Be specific about forbidden zones. Name the exact directories and file patterns agents must not touch without human approval. Vague prohibitions ("don't touch sensitive files") are ignored. Explicit paths ("never modify files in /src/auth/, /infra/, or any file matching *.env*") are respected — and can be enforced redundantly in CI.

Encode your architecture in the instructions. Tell the agent which package handles which concern, what your test runner command is, where the types live, which state management pattern you use. This is context the agent cannot infer from the code alone, and it prevents the most common category of hallucination: plausible-looking code that violates your actual conventions.

Use Plan Mode before every non-trivial task. Press Shift+Tab in the agent input to switch to Plan Mode. The agent produces a written plan — files to touch, approach, potential risks — before writing a single line of code. Review the plan, correct it if needed, then approve. A two-minute plan review eliminates the most expensive class of agent failure: correct execution of the wrong approach (Cursor, 2026a).

# AGENTS.md — Project Instructions

## Architecture overview
This is a TypeScript monorepo with three packages:
- `packages/api`    — Express REST API, PostgreSQL via Prisma ORM
- `packages/worker` — Background job processor (BullMQ + Redis)
- `packages/web`    — Next.js 15 frontend

## Running tests
- Unit tests:        npm run test            (Vitest, runs in ~90s)
- Integration tests: npm run test:integration (requires Docker, ~8 min)
- Do NOT write integration tests unless explicitly asked

## Forbidden zones — STOP and ask a human before touching any of these
- /packages/api/src/auth/            — authentication and session management
- /.github/workflows/               — CI/CD pipeline configuration
- /packages/api/prisma/schema.prisma — database schema (requires migration)
- Any file whose name contains SECRET, KEY, TOKEN, or CERT

## Routing rules for model selection
- Standard tier: test generation, scaffolding, doc updates, mechanical refactors
- Fast tier:     multi-file features with a clear spec
- Human only:    anything touching /packages/api/src/auth/ or /infra/

## Code conventions
- TypeScript strict mode — no `any`, use `unknown` and narrow explicitly
- Co-locate types with their implementation (not in a /types folder)
- Every async function needs explicit error handling
- Mock all external dependencies in unit tests — never hit real infrastructure

---
description: Testing and interface requirements for API service classes
globs: ["packages/api/src/services/**/*.ts"]
alwaysApply: false
---

When creating or modifying a service class:
1. Create `__tests__/[ServiceName].test.ts` if it does not exist
2. Test every public method: at least one happy-path and one error case
3. Export `interface I[ServiceName]` alongside the class
4. Mock Prisma with vi.mock('@/lib/prisma') — never import the real client in tests

Worktree setup for parallel generation

Cursor 3 creates and manages git worktrees automatically when you run agents in Worktree Mode. Each agent gets its own directory and branch, sharing the same git history and object store as your main checkout. The isolation is complete: an agent in worktree 3 cannot see uncommitted changes in worktree 1 (Cursor, 2026b).

The platform limit is 8 parallel agents per repository. In practice, the productive limit is lower — your review bandwidth, not the platform cap, constrains how many candidates you should generate. Enable Worktree Mode in Cursor's Settings under the Agents section. For teams that prefer explicit control, or for scripting the setup across a CI environment, manual worktree creation gives you full visibility:

#!/bin/bash
# setup-agent-worktrees.sh
# Usage: ./setup-agent-worktrees.sh feat/checkout-validation 3

TASK_BRANCH="${1:-feat/agent-task}"
N="${2:-3}"
REPO_NAME=$(basename "$(pwd)")

echo "Creating $N worktrees for task: $TASK_BRANCH"

for i in $(seq 1 "$N"); do
  BRANCH="${TASK_BRANCH}-candidate-${i}"
  DIR="../${REPO_NAME}-agent-${i}"

  git worktree add "$DIR" -b "$BRANCH"
  echo "  ✓ Worktree $i: $DIR (branch: $BRANCH)"
done

echo ""
echo "Open each in a separate Cursor window:"
for i in $(seq 1 "$N"); do
  echo "  cursor \"../${REPO_NAME}-agent-${i}\""
done

echo ""
echo "Cleanup when done: git worktree prune"

Each Cursor window runs its agent independently against its own branch. When an agent finishes, you review the diff in that window directly. Cursor's built-in diff view shows exactly what changed; the worktree isolation ensures you are looking at only that agent's work, with no bleed from parallel candidates.

Choosing N: the economics of parallel candidates

The cost constraint is effectively irrelevant. At Standard-tier pricing, ten Composer 2.5 candidates cost under $1.00. The constraint that matters is what happens after generation.

If your CI gate eliminates 60% of candidates — a realistic figure for tasks with strong test coverage — five agents produce roughly two candidates that pass and reach the review stage. Two candidates that fit within the diff limit and pass tests are genuinely comparable; choosing between them takes minutes, not hours. That is the productive operating point: enough candidates to get diversity, few enough survivors that selection is fast.

Three signals that say reduce N: your review queue is growing faster than it clears; agents are producing near-identical diffs (low diversity means low marginal value of additional candidates); CI is slow enough that parallelism creates queuing delay rather than saving time.

Three signals that say N is too low: CI eliminates all candidates consistently (the task needs better decomposition, or N=1 was always going to fail); review finds the same flaw in every passing candidate (you need more diversity in agent initialisation — use different initial prompts or different context injections); generation finishes before CI can process it (the bottleneck is not yet review).

The selection loop

Once you have N candidates that pass CI, you need a selection step. For small N (2–3), reading each diff yourself is fine. For larger N, or as a repeatable process, a conductor agent is more reliable and scales with your generation volume.

The conductor pattern: give a Composer Fast (or Claude Opus 4.7 for high-stakes tasks) agent all the passing diffs and ask it to rank them against explicit criteria. The conductor does not generate new code — it evaluates existing diffs and returns a ranked list.

You are a code review conductor. You will receive N diffs that all pass the
CI gate for the following task:

  [PASTE TASK DESCRIPTION AND ACCEPTANCE CRITERIA]

Rank them against these criteria, in order of priority:
  1. Smallest diff surface that fully satisfies the acceptance criteria
  2. No new external dependencies introduced
  3. Highest test coverage delta (new tests cover the new code)
  4. No changes to files outside the stated scope
  5. No modifications to any file in: /auth/, /infra/, /.github/

For each diff provide:
  - A score 1–10 against each criterion
  - One sentence identifying the main risk
  - A PASS or REJECT recommendation

Return a ranked list with the top candidate clearly identified.
Do not generate new code or suggest modifications — evaluate only what exists.

Measuring real ROI

The most honest thing the data says: vendor marketing sets expectations at 3–10× productivity improvement; most organisations land in the 5–15% throughput gain range (DX Research, 2026b). That is a real return, but it is not the number in the case study. Plan for the realistic range, and measure the right things so you know where you actually land.

Track these weekly, not daily. Weekly averages smooth out the noise of individual task variation. The single metric that most directly signals whether the pipeline is healthy is review time per agent PR: if it grows month over month, you are generating faster than you can review, and the answer is to reduce N or tighten the CI gate — not to generate more.

Six failure modes to avoid

The pipeline in one paragraph

Set up the prerequisites — tests, fast CI, a diff-size cap. Write an AGENTS.md that names forbidden zones and encodes your architecture. Add scoped .cursor/rules/ overrides for file types where conventions need auto-enforcement. Enable Worktree Mode and start with N=3: three parallel agents, three branches, three CI runs in parallel. Route only verifiable, scoped tasks to agents on Standard tier; keep latency-sensitive iteration on Fast; keep judgment work with a frontier model or a human. When the CI gate passes candidates through, use a conductor to shortlist; use a human to close. Measure review time per agent PR weekly and hold it flat even as generation volume grows. That is the whole system.

The 5–15% throughput improvement that well-configured agentic pipelines actually deliver is real and cumulative — a team that operates at 10% above its previous baseline for eighteen months has effectively added months of engineering capacity. It is not the 10× headline, but it is sustainable, it composes with other improvements, and it does not require replacing your engineering process with one that depends on agents getting lucky.