~ / ..

.gitignore is not .agentignore

an essay by texarkanine
2026-02-22

Thesis

“Do not track in source control” and “do not let a coding agent see the file” are not the same thing.

Corollary

Defaulting to hiding git-ignored files from agents is a mistaken design.

The Original Problem

As AI coding agents get more popular, people are realizing that they want to be able to keep certain files from the agents. This can be for a variety of reasons:

  1. Sensitive local configuration / credentials (.env.local, etc.)
  2. Text content generated by build tooling that is never manually edited (Documentation sites, code coverage reports, etc.)
  3. Binary content generated by build tooling that is never manually edited or even read by developers (*.class, *.jar, etc.)
  4. Personal, repo-specific agent guidelines that are not relevant to the project at large
  5. node_modules and other such directories
  6. 
and more!

The Red Herring

Many of those things are also things that should not be tracked in source control - and .gitignore (and its lesser-known cousin, .git/info/exclude) exist!

Cursor was an early and high-profile pioneer of this approach, hiding content in .gitignore by default, in addition to its own .cursorignore file.

The result was that most projects never bothered to set up a .cursorignore - because their .gitignore covered most of what they needed to exclude.

The Emerging Problem

There are at least three things on that ignore list that indeed shouldn’t be in source control but you may very well want to let an agent see:

  • Text content generated by build tooling that is never manually edited
  • Personal, repo-specific rules that are not relevant to the project at large
  • node_modules

Text Content

Access to generated text content is actually required if you want an agent to use and be able to verify that the build tooling works! Imagine asking an agent to update your documentation site, but then it can’t see the generated content to check afterwards!

For example
 this very blog! When changing how Jekyll builds it, the agent must be able to see the output in site/ - but we do not commit site/ to source control!

Personal, Repo-Specific Rules

The problem here emerges for agentic coding power-users: Once you start customizing an agent’s behavior, you realize:

  1. Most customizations that your harness supports live within the repository’s directory tree.
  2. Even if your harness does support global customizations, many customizations are specific to a particular repository.
  3. Other people working on the project may not share your preferences for those customizations.
  4. Other people working on the project may not even use the same harnesss you do (e.g. you use Cursor, they use Claude Code).

So, you want to put something in the repository directory tree that is there for you and your agent, but not committed to source control.

Git Ignore is the right tool for the job! Specifically, .git/info/exclude, which is itself not tracked in source control.

But an agentic coding harness that assumes all git-ignored files are also irrelevant to the agent doesn’t allow this (you have to end up doing insane things to make it work
).

node_modules

This is a point of contention, but in my experience, allowing an agent to be able to access node_modules - or other such installed-dependency directories - is amazing.

The reason it’s amazing is the agent can directly read all the source code in the entire call graph, including all the dependencies. This makes understanding architecture and tracking down bugs way easier. Nothing to download, no reliance on prose documentation or StackOverflow claims - just, go follow the entirety of the code in use in the project.

As an aside, I think this is one of the reasons that JavaScript (via node) has become one of the most-popular languages for agentic development, despite human devs’ longstanding complaints about JS. The available context can expand all the way up to the entirety of all possible call graphs!

The Right Ideas

The solution is a dedicated, standardized “Agent Ignore” file.

You’ve got a semantically-new class of thing that accesses most files in a directory tree but shouldn’t always access the full set of files? It gets its own ignore file!

Whether it be a harness-specific file like .cursorignore, or an emerging standard like .agentignore, this is a pattern that has prior art and is worth continuing.

Consider,

At the moment, we’ve got a bunch of nearly-identical implementations with no real standardization, including but likely not limited to:

Tool Ignore Method
Android Studio .aiexclude
Claude Code “Deny” tool settings
Cline .clineignore
Cursor .cursorignore
Gemini Code Assist .geminiignore, .aiexclude

The Solution

It’s time for “Agent Ignore” to become an officially-proposed standard somewhere with traction
 and then get adopted.

AND, it’s time to *stop deferring “Agent Ignore” to “Git Ignore”!

If you’re building a new agentic coding harness, take heed!

“Do not track in source control” and “do not let a coding agent see the file” are not the same thing.

~ / ..