Cursor Agent in Large Projects: 7 Solutions to Missing Files and Wrong Code

1 AM. I stared at the third error message on my screen, fingers hovering over the keyboard, unable to type.

I’d just asked Cursor Agent to refactor the login module - a task spanning 5 files: frontend form component, API routes, authentication middleware, user model, and Redis cache layer. After two minutes of work, Agent confidently declared “done.” I ran the code with high hopes, and… it crashed.

After investigation, I discovered: Agent found 4 files but only modified 3. Worse still, it “optimized” the perfectly fine middleware logic, causing all login requests to return 401. I spent half an hour manually rolling back code, untangling dependencies, and finishing the remaining work myself.

Alibaba Cloud - Top choice for developers, exclusive 15% off for Lighthouse servers

Get 15% Discount →Ad

Honestly, at that moment I seriously doubted: Can AI coding assistants really handle large projects?

Later, I spent two weeks researching how Cursor Agent works, reading dozens of technical blogs, and constantly experimenting on real projects. Gradually, I developed a system to make Agent more reliable in large projects. Now, my success rate with Agent refactoring has increased from under 50% to over 90%.

In this article, I’ll share 7 practical techniques across three dimensions: context management, task splitting, and code review. These aren’t theoretical speculations - they’re lessons learned from real project failures.

Why Agent Struggles in Large Projects

Before diving into solutions, we need to understand why Agent makes mistakes. It’s not “stupid” - there are three objective limitations at play.

Context Limitation is the Biggest Bottleneck

You know this - even models claiming 200k tokens struggle with real projects. A medium-sized full-stack project easily has hundreds of code files, each ranging from hundreds to thousands of lines. Add package.json, config files, test code… and you’ll blow past the token limit.

Agent can’t “see” the entire project. It only sees files mentioned in the current conversation, plus whatever dependencies Cursor’s auto-indexing system manages to associate. It’s like asking someone who can only see 5 meters to find something on a football field - missing things is inevitable.

I tested this on a React + Node.js project: same requirements, small project (20 files) had 85% one-shot success rate, medium project (50 files) dropped to 60%, large project (100+ files) crashed to 35%. The difference is stark.

Agent’s “Nearsightedness” Problem

There’s an interesting phenomenon: Agent easily “misses” indirectly dependent files.

For example, you ask it to modify an API route. It dutifully modifies the route file and corresponding Controller. The problem? That Controller calls a utility function, which depends on a config module… Agent often stops following these hidden dependency chains after the second layer.

What’s worse is recency bias - Agent prioritizes recently opened files and those explicitly mentioned in conversation. If you mentioned a file earlier in the chat history, even if it’s irrelevant to the current task, Agent might pull it in and modify it randomly. Conversely, truly critical files get ignored if you don’t explicitly mention them.

Lack of Global Perspective

This is the killer.

Human developers mentally review the overall architecture before making changes: Which modules does this feature touch? How do modules communicate? Will changing A affect B? Agent doesn’t do this. Each task execution is “local optimization” - looking only at code in the current scope, finding what seems like the most reasonable solution, then executing it.

The most outrageous case I’ve seen: Asked Agent to optimize database query performance, it diligently added indexes and tuned SQL statements. Definitely faster. But three days later, the system ran out of memory - turned out that to “optimize,” it added full data preloading logic in the cache layer, crashing Redis.

Agent doesn’t understand “overall architectural design.” It sees performance issues and optimizes performance, sees duplicate code and extracts functions, completely ignoring whether this breaks the original design intent.

3 Core Context Management Techniques

Now that we know the problems, we can prescribe solutions. Context management is paramount - control what Agent can “see,” and many problems naturally disappear.

Technique 1: Optimize Project Rules Configuration

Many people take the lazy route and dump all project rules using always mode. This is the biggest mistake.

always mode means “load these rules every conversation.” Sounds good, but it devours tokens. Your project likely has multiple modules - frontend, backend, testing, documentation - each with different coding standards. Loading everything with always consumes a third of your tokens before Agent even starts working.

The right approach: Use Auto Attached + glob patterns

For example, here’s how I configure the full-stack project I maintain:

# .cursorrules (project root)

# General rules (only the essentials)
- type: always
  rules:
    - Use TypeScript
    - Follow ESLint configuration
    - All async operations must have error handling

# Frontend rules (only load when modifying frontend code)
- type: auto
  glob: "src/frontend/**/*.{ts,tsx}"
  rules:
    - Use React Hooks
    - Components must have PropTypes or TypeScript types
    - Use Tailwind CSS, no inline styles

# Backend rules (only load when modifying backend code)
- type: auto
  glob: "src/backend/**/*.ts"
  rules:
    - API routes must have input validation
    - Database operations must use transactions
    - Sensitive info cannot be logged

# Test rules
- type: auto
  glob: "**/*.test.ts"
  rules:
    - Each test case must have clear description
    - Use Jest's describe/it structure

With this configuration, Agent only loads relevant rules when truly needed. I tested it - token usage dropped 70%, and Agent no longer gets distracted by irrelevant rules.

Pro tip: Add “if unsure, ask me first” at the end of each rule. I found Agent will proactively ask about edge cases instead of guessing.

Technique 2: Leverage Long Context and Summarized Composers

Cursor has two useful but often overlooked features.

Long Context

This is a toggle option - remember to enable it for complex tasks. When enabled, Agent uses a larger context window and can see more code.

Don’t leave it on all the time - it burns through tokens quickly and slows Agent thinking. My habit:

• Simple tasks (modify a function, fix a bug): Off
• Complex tasks (refactor module, add feature): On
• Very complex tasks (cross-module refactoring): On + manually reference key files

Summarized Composers

This feature lets Agent access summaries of previous conversations instead of full history. Perfect for long-term projects.

For instance, yesterday you had Agent write a utility function, today you want to extend it. Just saying “use yesterday’s function” might not work. But with Summarized Composers enabled, it automatically searches conversation history and finds relevant content.

My workflow now: After completing a major feature module, I create a new Chat window and start with “This project previously implemented XX feature, code in XX directory.” This references historical context without getting bogged down in details.

Technique 3: Actively Manage Context Scope

This is most important and most often overlooked.

Don’t expect Agent to find all files on its own - you must actively tell it what to see and what to ignore.

Reference key files: Use @ syntax

Vultr - High-performance NVMe VPS with 32 global locations, one-click Docker deploy

View Pricing →Ad

When describing tasks, mark key files with @filename:

Refactor user authentication flow, involving these files:
@src/routes/auth.ts (authentication routes)
@src/middleware/jwt.ts (JWT middleware)
@src/models/User.ts (user model)
@src/utils/password.ts (password encryption utility)

Do not modify other files.

That last sentence “Do not modify other files” is crucial. I tested it - adding this reduces Agent’s probability of randomly modifying unrelated code from 30% to under 5%.

Limit modification scope

If the task only involves a subdirectory, say so explicitly:

Add a password recovery component in src/frontend/components/auth/ directory,
do not modify code in other directories.

There’s an advanced technique: Combine whitelist + blacklist

Can modify: all files under src/api/**
Do not modify: src/api/legacy/** (this is legacy code, awaiting deprecation)

This gives Agent enough freedom while preventing it from touching what it shouldn’t.

I’ve developed a habit: Before assigning Agent a task, I mentally review “At most how many files should this task modify? Which directories are involved?” Then I explicitly tell Agent this scope. Sounds tedious, but it saves massive bug-fixing time later.

2 Golden Rules for Task Splitting

Context management solves the “Agent can’t see everything” problem, but there’s another pitfall: even when it sees everything, overly complex tasks cause Agent to mess up. That’s where task splitting comes in.

Technique 4: Split by Responsibility, Not by File

This was my biggest mistake.

Initially I thought splitting tasks was simple - just split by file. For example, implementing user registration, I’d split it like:

1. Write frontend form component first
2. Then write backend API routes
3. Finally write database model

Seems reasonable, right? But in practice, each step had problems:

• Writing frontend, don’t know what backend interface looks like, can only guess
• Writing backend, find frontend passes different parameters than expected, must go back and change frontend
• Writing database model, suddenly realize a field type is wrong, frontend and backend need changes again

Back and forth - actually slower.

The right way to split: By functional responsibility

Still using user registration as example, now I split it like this:

Step 1: Implement basic registration flow (minimum viable version)

Task 1: Implement most basic user registration
- Frontend: Form with just username and password fields
- Backend: Registration API + basic validation
- Database: User model (minimum fields)
Goal: Complete flow works, can successfully register one user

Step 2: Enhance validation and security

Task 2: Add registration validation and security
- Email format validation
- Password strength check
- Prevent duplicate registration
- Encrypted password storage

Step 3: Improve user experience

Task 3: Optimize user registration experience
- Real-time form validation feedback
- Auto-login after successful registration
- Send welcome email

See the difference? Each task is “vertical” - from frontend to backend to database, completely implementing an independent functional point.

Benefits of splitting this way:

1. Each task can be independently tested: After task 1, it runs - don’t need to wait for all features
2. Less rework: Frontend and backend together, interface issues discovered immediately
3. Easier for Agent to understand: Task goals are clear, won’t get confused

I tested it - using “split by responsibility,” Agent task completion success rate increased from 60% to 85%.

Technique 5: Set Clear Checkpoints

This technique has saved me countless times.

A fatal problem in large projects: After modifying code extensively, you discover the direction was wrong, but it’s too late to go back. Especially when Agent helps - it won’t ask “should we save first?” - it just modifies. By the time you notice something’s wrong, it may have changed dozens of files.

Use Checkpoint Feature

Cursor has a very useful but seriously underestimated feature: Checkpoint.

Before starting a task, create a checkpoint:

Railway - Modern deployment platform, zero-config, go live in minutes

Start Now →Ad

# In Cursor press Cmd/Ctrl + Shift + P
# Type "Create Checkpoint"
# Add note: Before refactoring login module

Then let Agent work. If something’s wrong, you can rollback to checkpoint state with one click, all changes undone.

My habit:

• Starting a new major task: Create checkpoint
• After Agent completes task: Test passes → Delete checkpoint; Test fails → Rollback checkpoint
• Multiple small tasks: After completing 2-3 small tasks, create a checkpoint

This way even if Agent messes up, you lose at most one small task’s work.

Test-Driven Development (TDD)

There’s a more advanced approach: Write tests first, then let Agent implement features.

Sounds tedious, but particularly useful in large projects. You can do this:

1. Manually write test cases (define expected behavior)
2. Run tests, confirm failure (because feature not yet implemented)
3. Let Agent implement feature until tests pass
4. If tests keep failing, Agent misunderstood - stop immediately

The beauty of this method: Test cases set a clear termination condition for Agent. Agent won’t drift infinitely - it focuses on “making tests pass.”

I used this method to refactor an entire authentication module in a Node.js project. Agent nailed it in seven tries, completely on track. Previously without tests, the same task took Agent over a dozen attempts and still had bugs.

2 Key Practices for Code Review and Monitoring

Everything above is about “making Agent make fewer mistakes,” but zero errors are impossible no matter how careful. The final line of defense is code review and monitoring - discovering problems early, stopping losses quickly.

Technique 6: Establish Multi-tier Review Standards

There’s a common misconception: Using AI means you don’t need Code Review anymore.

Quite the opposite - Code Review becomes more important after using AI. Because Agent’s mistakes are often subtle - syntactically fine, logically sound, but just “not quite right.” Humans can spot these issues immediately, but Agent may be completely oblivious.

Configure Cursor Rules for Automatic Review

Cursor supports defining Code Review rules in .cursorrules. My configuration:

# .cursorrules (review rules section)
code_review_rules:
  # Critical level (must fix)
  critical:
    - "No hardcoded passwords, API keys or sensitive info in code"
    - "Database operations must use parameterized queries to prevent SQL injection"
    - "All external input must be validated and sanitized"

  # Warning level (strongly recommended to fix)
  warning:
    - "Function length should not exceed 50 lines, consider splitting"
    - "Avoid using any type, define types explicitly"
    - "Async operations must have try-catch or .catch() error handling"

  # Info level (optional optimization)
  info:
    - "Consider adding unit tests"
    - "Complex logic should have comments"
    - "Duplicate code should be extracted to common function"

After configuring, whenever Agent completes a task, I have it self-review:

Task complete, now review the code according to code_review_rules in .cursorrules,
list all critical and warning level issues.

Agent will dutifully list the problems. Interestingly, it often finds issues in code it wrote when reviewing from a different angle. This is like having Agent “look at the code from a different perspective.”

Human-Machine Combined Review Strategy

Relying entirely on Agent review is unreliable, entirely manual review is exhausting. My current approach is tiered handling:

1. Agent initial review (automatic): Check obvious syntax errors, code standard issues
2. Manual focus review: Focus on these aspects
   • Business logic correctness (Agent’s biggest weakness)
   • Boundary condition handling completeness
   • Performance impact (e.g., N+1 queries)
   • Security risks (SQL injection, XSS, etc.)
3. Test verification: Run test suite, ensure no broken existing functionality

The key is don’t review line-by-line - that’s too time-consuming. Focus on core logic and risk points, leave other details to tools and tests.

I’ve tracked this - in large projects, about 15-20% of Agent-modified code has issues. Breakdown:

• 5% serious bugs (logic errors, security issues)
• 10% code quality issues (performance, maintainability)
• 5% “works but doesn’t follow project standards”

Without review, these issues slowly surface over the following weeks, with much higher debugging costs.

Alibaba Cloud - Top choice for developers, exclusive 15% off for Lighthouse servers

Get 15% Discount →Ad

Technique 7: Git is Your Final Insurance

This sounds basic, but many people really don’t take it seriously.

Use git diff wisely

After Agent modifies code, the first thing isn’t running tests - it’s:

git diff

See exactly which files changed and what changed. I scan through every time, focusing on:

• Whether the change volume matches expectations (be alert if dozens of files changed)
• Whether unrelated files were modified
• Whether key logic was altered

Pro tip: Use git diff --stat to see change statistics first, then decide if detailed diff is needed:

git diff --stat

# Example output:
# src/api/auth.ts          | 25 +++++---
# src/models/User.ts       | 12 ++--
# src/utils/password.ts    |  3 +-
# src/config/database.ts   | 150 ++++++++++++++++++++++++++++++++++++++++++++++

If you see a file with 150 lines added, and your task never required modifying that file… go check what happened immediately.

Combine Checkpoint and Git

Use the previously mentioned Checkpoint with Git for double insurance:

1. Before starting task:
   - git checkout -b feature/xxx  (create new branch)
   - Create Cursor Checkpoint

2. After Agent completes task:
   - git diff (check changes)
   - Run tests
   - If OK: git commit
   - If not OK:
     - Small issue: Fix manually or have Agent correct
     - Big issue: Rollback Checkpoint or git reset --hard

3. After confirming no issues:
   - git push
   - Create Pull Request

Benefits of this workflow:

• Checkpoint: Quick rollback, no Git history handling
• Git branch: Isolate changes, don’t affect main branch
• Commit history: Preserve record of each step’s changes

I also have a habit: When having Agent do tasks, I note in commit messages:

git commit -m "feat: Add user registration (by AI Agent)"

This way if problems arise later, one look at commit shows it’s Agent-written code, extra caution when debugging.

Conclusion

Back to that 1 AM scenario at the article’s beginning.

If I were asked to use Cursor Agent to refactor the login module now, I’d do this:

1. Context management: Create authentication module-specific .cursorrules, only load relevant rules; use @ to reference 5 key files, explicitly tell Agent “only modify these 5 files”
2. Task splitting: Not refactoring all features at once, but implementing basic login flow first, then adding validation after it works, finally optimizing cache
3. Code review: After each small task, git diff to check changes, run tests, confirm no issues before continuing

Doing this, Agent’s probability of missing files drops from 50% to under 10%, probability of wrong code drops from 30% to under 5%. And my extra time investment? Just 5-10 minutes per task.

Honestly, AI coding tools aren’t omnipotent. They can’t do architectural design for you, can’t understand business logic for you, and can’t take responsibility for code quality. But if used correctly, they can genuinely double your development efficiency - provided you learn how to “manage” them.

Context management, task splitting, code review - these three dimensions are indispensable. Context management makes Agent “see accurately,” task splitting makes Agent “do correctly,” code review lets you “sleep soundly.”

Final suggestion: If you’re currently using Cursor Agent to develop large projects, take 10 minutes today to check your Project Rules configuration. Change always mode to auto + glob patterns - this one change alone saves massive tokens and immediately elevates Agent’s performance.

Technology advances, tools evolve, but some principles remain constant: Clear requirements, split tasks, continuous verification. This approach applies not just to AI programming, but to any complex project development.

What about you? What pitfalls have you encountered using Cursor Agent? Feel free to share your experience in the comments.

14 min read · Published on: Jan 10, 2026 · Modified on: Feb 4, 2026

Easton

Technology