Why Cursor's Background Agent Skips AGENTS.md
Cursor's background agent skips AGENTS.md because of a documented, unresolved bug, not because your file is malformed or in the wrong place. Cursor's own rules documentation says AGENTS.md is "automatically applied when working with files in that directory or its children," with no carve-out for background or cloud sessions. In practice, a background agent asked directly whether it has the file will sometimes answer that it doesn't.
That's not a paraphrase. In a forum thread reporting the gap, a user asked their background agent point-blank about its AGENTS.md, and the agent replied: "I can see a reference to AGENTS.md in my workspace rules, but I don't have the full content loaded." The original poster tagged the bug across GitHub, Slack, and Cursor's web dashboard; another user in the thread confirmed the same gap independently for files in .cursor/rules/ and for environment.json. A Cursor moderator acknowledged the reports and said they'd been forwarded to the team. That was over a year ago as of this writing, and no fix or root cause has been posted in the thread since.
Why the docs and the background agent disagree
The mismatch traces to two different pages describing two different context models, neither of which mentions the other. The rules page describes AGENTS.md as project-wide instructions, loaded automatically, no session type mentioned. The background agent page describes a separate mechanism entirely. Background and cloud agents get their understanding of your codebase from a configured development environment, built from a snapshot, a Dockerfile, or an agent-led setup recorded in .cursor/environment.json. The docs describe environment setup as what "give[s] agents full context on your codebase and organization," and AGENTS.md isn't part of that description.
Read the two pages side by side and there's no sentence anywhere that says "background agents also read AGENTS.md." It's an inference, and a reasonable one, since interactive Cursor sessions do read it. But a background agent's context is assembled once, at environment build time, from a different pipeline than the one a local agent chat pulls from live. If AGENTS.md isn't wired into that build step in your setup, or Cursor's forwarding of it into a background session drops it, the agent runs the task with a hole where your instructions were supposed to be, and nothing tells you that happened.
What this looks like in a live repo
Say a repo's AGENTS.md carries one load-bearing rule: every database migration ships with a matching rollback script. An engineer, call her Priya, tags Cursor's background agent on a GitHub issue asking for a schema change. The agent opens a PR with the migration, no rollback script attached.
Priya, in the PR thread: Every migration in this repo needs a rollback file next to it, that's in AGENTS.md. Can you add one?
Agent: Added the rollback script. I don't see an AGENTS.md file in this workspace's context, but I've applied the pattern from your other migrations for consistency.
The agent hadn't ignored the rule. It had never received it. Priya pasted the relevant paragraph directly into her review comment, and the agent applied it correctly on the next pass, because a comment in the task thread is context the background agent unambiguously has. The rule sitting in the file, the one meant to make this automatic, wasn't reaching the session that needed it.
How to confirm it's this bug and not your file
Before assuming you've hit the same gap, rule out the ordinary causes first:
- Ask the agent directly. In the task thread, ask "do you have the contents of AGENTS.md loaded?" A background agent that says no, or describes only "a reference" to the file, is showing you the same symptom from the forum thread.
- Check the file lands in the environment. If your background agent runs from a Dockerfile or snapshot, confirm
AGENTS.mdis copied into the image; a.dockerignoreor a snapshot built before the file existed will produce the same silence for an unrelated reason. - Test the same repo state locally. Open the identical branch in an interactive Cursor session and ask the same question. If the local agent has the file and the background agent doesn't, you're looking at the split described above, not a formatting problem.
If all three point to the gap, there isn't a documented setting to flip. The forum thread's most recent request, someone asking for a workaround, went unanswered.
The ceiling on pasting rules into every task
The practical workaround, repeating the load-bearing instructions in the task prompt itself, works because the prompt is context the agent definitely receives. It also has an obvious ceiling. It only helps with facts a person remembers to retype, every time, for every task, which is fine for one rollback rule and breaks down once a repo accumulates a dozen of them. It says nothing about facts that change on their own schedule, like which customer is escalating this week, which account renewal makes a bug urgent, or which team owns a service now versus who owned it when the rule was written. AGENTS.md, loaded correctly, is still just what someone wrote into a file at some point in the past. Loaded incorrectly, as background agents currently sometimes do, it's nothing at all.
“we need SSO before rollout”
“any update on single sign-on?”
“SSO came up twice on this call”
Linear issue, quotes attached
insight report in Notion
Cursor's background agentPast that point, the fix isn't a better file, it's not putting the load-bearing facts in a file at all. Modem reads Slack, support tickets, and sales calls continuously and keeps a live graph of accounts, people, and open topics. Through the Cursor integration, Modem can hand a background agent task the current facts, who's affected, how urgent it is, what's already been tried, written directly into the task description at the moment the task is created, so there's no separate file that has to load correctly first. An agent working locally can also query the same graph over Modem's MCP server, asking which customers are hitting a given bug right now rather than trusting whatever was last typed into a rules file. Full disclosure: we build Modem. The free path is a well-maintained AGENTS.md plus manually working around the ways Cursor rules get ignored, and that stays the right call for facts stable enough that nobody minds re-typing them occasionally. For a broader comparison of ways to get customer context in front of Cursor at all, see the six best tools to give Cursor customer context.
Habits that catch this early
Add the direct question, "do you have AGENTS.md loaded?", to your background agent task template so the gap shows up immediately instead of three review comments later. Keep the rollback-script rule, or whatever yours is, short enough to paste into a task prompt without friction, since that's the fallback that reliably works today. And treat anything in the file that changes faster than your team edits markdown as a sign that the fact belongs somewhere other than a file waiting to be loaded.
