Cursor @Folder Scope — When to Attach a Directory

In Cursor chat, typing @ lets you attach files and folders as context. The trap is assuming “a folder makes the agent smarter.” Wider scope pulls in sibling packages, legacy trees, and build artifacts, which raises bad edits and path hallucinations.

This post covers three axes only: file vs folder · too-wide symptoms · monorepo minimum scope. No pricing, plans, token quotas, affiliates, or invented reviews.

Grounded in Cursor’s help page @ mentions and context: attach a file like @auth.ts or a folder like @src/components/, type / after a folder to go deeper, use @ when you know the relevant files, and skip @ when you do not—Agent will search. Attach multiple items by typing @ again.

File vs folder — when?

One-line answer: Use @file when you already know the target; use @folder (then / to narrow) when the feature lives in one directory but you cannot name every path yet. Attaching the repo-tip folder is not the default.

Situation	Prefer @	Why
Stack / symbol points at one file	`@path/to/auth.ts`	Exact body in context
Component + its test	`@Comp.tsx` + `@Comp.test.tsx`	Docs: attach known related files
“Feature lives under `apps/web/src/billing/`”	`@apps/web/src/billing/`	Folder = zone hint; deepen with `/`
Paths unknown	Skip `@`	Let Agent search the codebase
Root CI / lockfile only	`@` those root files or skip	Prefer files over tip-as-folder

Practical order:

From the ticket or stack, list 1–3 candidate files first.
If you have candidates, @file them; add tests/types/schema with more @.
Only if the unit is “a directory,” attach @folder, then / one level deeper in the menu.
If still wide, pin one line: “do not edit outside this folder.”

# Prefer — known files
@apps/web/src/billing/InvoiceForm.tsx
@apps/web/src/billing/InvoiceForm.test.tsx

# Prefer — narrow folder, then deepen with /
@apps/web/src/billing/

# Avoid as default
@/          (repo tip as a folder)
@apps/      (whole apps tree)
@packages/  (all packages)

Official guidance: attach when you know the files; skip when you do not. A folder is mid-precision for a known zone, not a substitute for “I have no idea.”

What symptoms show the scope is too wide?

One-line answer: Over-wide @ makes the agent read wrong siblings, legacy, or artifacts, producing noisy diffs, path hallucinations, and mistargeted tests. It looks like model failure; it is usually context pollution.

Symptom	Likely cause	Fix
Huge sibling-package diffs	`@apps/` / `@packages/`	Re-attach under the owning package
Import / path hallucinations	Treating tip as one app	Fall back to `@file`
Tests green, bug remains	Wrong package’s tests in context	`@` the target test file
Mentions of dist / vendor	Folder includes build outputs	`.cursorignore` + narrower `@`
Clash with nested `AGENTS.md`	Broad folder + mixed rules	`@` the rule path explicitly
Slow, scattershot “find related”	Using folder as fake search	Drop `@`; let Agent search

Checklist when symptoms appear:

Inspect the current @ attachments in the chat.
Drop anything at repo tip / apps/ / packages/.
Restart with the ticket’s one owning path and file @s.
If needed, add one leaf folder only.
Fix scope before swapping models.

Too-wide red flags:
- Attached: @apps/ or @packages/ or repo tip folder
- Diff touches sibling package not in the ticket
- Agent cites files under dist/, .next/, build/
- Answer mixes two apps' route names

Recovery:
1. Clear broad folder @ mentions
2. Re-attach 1–3 concrete files
3. Optional: one leaf folder under the owning package
4. Re-state: do not edit outside <path>

A wide @folder is not a safety net. Often omitting @ and letting Agent search stays tighter (same as the official “skip if unsure” advice).

What is the minimum scope in a monorepo?

One-line answer: In a monorepo, the ceiling for @folder is the owning package (or a feature directory inside it). For cross-package work, pick files and @ them multiple times—do not attach the workspace root as a folder.

Minimum-scope rules:

Task	Minimum `@`	Do not attach
Single-app UI bug	Files under `@apps/web/src/…` or that feature folder	`@apps/`, repo tip
Shared package types	Exact files under `@packages/ui/…` + consumer files	Whole `@packages/`
API + web together	2–4 file `@`s per side	`@apps/` + `@packages/`
Root CI / lockfile	Root files only	Tip as a folder
Legacy forbidden	Name Do-not-touch in the brief	`@packages/legacy/` for unrelated work

Brief fragment:

Context for this Cursor session:
- Touch: apps/web/src/billing/**
- Do not touch: apps/admin/**, packages/legacy/**, firmware/**
- Prefer @ files under Touch; if folder, only @apps/web/src/billing/
- Never @ repo tip, @apps/, or @packages/ as a whole
- Cross-package: name exact files with @, do not widen to parent

Pick “one level only” on the tree:

repo/
  apps/
    web/src/billing/   ← OK ceiling for billing work
    web/src/           ← usually too wide
    web/               ← too wide
    admin/             ← out of scope
  packages/
    api/               ← only if ticket lists it (prefer files)
    legacy/            ← never as @ folder for unrelated tasks

Minimum @ scope is not the same as editor cwd. You can open at the tip and keep @ narrow—or open a package and still ruin it with @apps/. Session root choice is covered elsewhere (monorepo agent root); this post is only @ attachment width.

Frequently asked questions

Does @folder dump every file inside?
Help docs say you include files or folders and can deepen with /. Depending on size, settings, and indexing, it may not be a full dump. In practice, do not assume full inclusion—@file anything you truly need.

Should I @folder first when I do not know the paths?
No. Docs say skip @ and let Agent search. Folders are for zones you already know.

Can I attach several folders?
Yes—type @ multiple times. In a monorepo, each extra out-of-scope folder moves you toward the failure modes above. Prefer growing by files.

How does .cursorignore interact with @folder?
Ignored paths may be blocked from @ and indexing. Keep secrets/vendor/artifacts in deny lists; use @ only on the smallest work zone.

What should you remember?

@file is the default, @folder is mid-precision for a known zone, and in a monorepo the ceiling is the owning package / feature directory. When symptoms appear, shrink the @ list before changing models. Source: Cursor @ mentions and context. No pricing or affiliates.

Where are the official sources?

Cursor — @ mentions and context — file/folder @, deepen with /, attach when known / skip when not, multiple @
Cursor — Prompting agents — Agent prompting and @ summary
Adjacent: monorepo-agent-root (session cwd / package allowlist), agent-deny-paths (.cursorignore / secrets)