How to use Cursor or Claude Code on a large codebase

To use Cursor or Claude Code on a large codebase without losing control, give the agent a written map of the project, make it plan before it edits, scope each task to a named area, and keep every change small enough to review and test before the next one starts. The agent can only read part of a big project at once, so most failures come from it guessing about the parts it hasn't seen.

This guide explains why agents drift in big projects and gives concrete practices for each stage: preparing the project, scoping a task, keeping irrelevant files out, reviewing changes, and knowing when to start over with a fresh session.

Why do AI agents lose control in a big project?

An agent works inside a context window: the instructions, files and conversation it can hold at one time. In a small app it can read almost everything. In a project with hundreds of files it searches, reads a sample, and fills in the rest with assumptions. That leads to familiar problems:

• It writes a new helper because it never found the one that already exists.
• It changes a shared function for one screen and breaks three others it never opened.
• It follows the pattern of an old module you meant to retire.
• In a long conversation, earlier details get summarized or dropped, and it repeats mistakes you already corrected.

None of this means the tool is bad at large projects. It means the agent needs the context a new team member would need, and limits a new team member would have.

How do I give the agent a map of the project?

Write a short instruction file that sits at the root and loads at the start of every session: CLAUDE.md for Claude Code, .cursor/rules or AGENTS.md for Cursor. Include:

• What the product does, in two sentences.
• A folder map: where the frontend, API, database migrations, shared types and tests live.
• How to run, test and build.
• Which modules are legacy and must not be copied.
• The handful of rules that, if broken, cause real damage.

Keep it lean. Claude Code's memory documentation suggests aiming for under 200 lines per CLAUDE.md and moving instructions that matter for only part of the code into path-scoped rules under .claude/rules/, which load only when Claude works with matching files. Cursor gets the same effect with rules that apply to specific file patterns, and both tools support extra AGENTS.md files in subfolders for area-specific notes. In Claude Code, /init generates a starting file you can trim.

For the details of writing rules that stick, see our separate guide.

How should I scope a task?

The single biggest lever is asking for less at a time, and asking for a plan first.

Start in plan mode

Both tools have a mode that researches and proposes without touching your files. In Cursor, Plan Mode asks clarifying questions, reads the codebase and produces a plan you can edit before it builds; switch to it with Shift+Tab in the chat input. In Claude Code, plan mode (Shift+Tab, or /plan before a prompt) reads files and writes a plan, and edits stay blocked until you approve it. Read the plan. If it mentions files you didn't expect, ask why before approving.

Point at the exact place

Name the files or folders with @-mentions instead of letting the agent search. Compare:

• Vague: "Add CSV export to reports."
• Scoped: "Add a CSV export button to @src/pages/reports/MonthlyReport.tsx. Use the existing downloadFile helper in @src/lib/files.ts. Don't change the report query. Show me the plan first."

One concern per session

Bug fix, refactor and new feature are three sessions, not one. Mixed requests produce mixed diffs that are hard to review and harder to undo.

How do I keep irrelevant files out of the agent's way?

Large repositories carry noise: build output, generated files, vendored code, large data fixtures. In Cursor, list those in .cursorignore so the agent, Tab and @-mentions don't pull them in. Cursor's documentation is explicit that this is not a security boundary: the agent's terminal and MCP tools can still reach those files. In Claude Code, block reads of sensitive files with a permission rule such as Read(./.env) in .claude/settings.json.

Keep secrets out of the repository entirely. An ignore file is a convenience, not a vault.

How do I review changes at this scale?

Set yourself a budget and stop when a change goes over it.

1. One branch per task. Everything the agent does lands on a branch you can throw away.
2. Read the file list first. If a small fix touched a migration, the auth module and package.json, ask why before reading line by line.
3. Cap the diff. A rough rule: if you can't review it in fifteen minutes, it should have been two tasks.
4. Run the checks yourself. Typecheck, tests and a quick click-through of the affected screens. Don't take "all tests pass" from the summary on faith.
5. Commit each working step. Small commits make it easy to find which step broke something.

Our guide on how to review AI-generated code has a full checklist, and adding tests to AI-generated code covers the safety net that makes larger refactors possible.

When should I start a fresh session?

Start over when a task is done, when the agent repeats a mistake you already corrected, or when the conversation has wandered across several topics. In Claude Code, /clear starts clean, and /compact or the summarize options in /rewind shrink a long session while keeping the important parts. In Cursor, open a new chat.

Before you do, ask the agent for a five-line summary of what was decided and what's left, and paste that into the new session. You keep the decisions and drop the noise.

Can I run several agents at once?

You can, and both tools support it, from Claude Code subagents and background sessions to Cursor's cloud agents. It works when the tasks touch different parts of the code. Two agents editing the same files in parallel will create conflicts you then have to merge by hand. Use separate branches or git worktrees, and merge one at a time.

Quick answers

Is Cursor or Claude Code better for a large codebase? Both can handle it with the practices above. The bigger difference is how you scope and review work, not which tool you pick.

Should I let the agent refactor the whole project at once? No. Refactor one module at a time, with tests around it first, and merge each step separately.

Why does the agent keep creating duplicate functions? It didn't find the existing one. Mention it by path, and list shared helpers in your instruction file.

How long should a session be? As long as one task. When you switch topics, start fresh.

Need help taming a big project?

When months of AI-assisted changes have left a codebase that's hard to steer, the fix is usually structure: a map, tests around the risky parts, and a cleanup of duplicates. Our Cursor project help explains how we approach that, and if technical debt from vibe coding is the real issue, that guide will help you size it. You can also get in touch with a short description of the project.