## 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](https://git-scm.com/docs/gitignore)!

Cursor was an early and high-profile pioneer of this approach, hiding content in `.gitignore` by default, *in addition* to [its own `.cursorignore` file](https://cursor.com/docs/context/ignore-files).

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](https://jekyllrb.com/) 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](/2025/12/12/hook-based-local-mode-for-ai-rizz.html) 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,

* `.dockerignore` - [for Docker builds](https://docs.docker.com/build/concepts/context/#dockerignore-files)
* `.helmignore` - [for Helm charts](https://helm.sh/docs/chart_template_guide/helm_ignore_file/)

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](https://developer.android.com/studio/gemini/aiexclude)        |
| Claude Code       | ["Deny" tool settings](https://code.claude.com/docs/en/settings)           |
| Cline             | [.clineignore](https://docs.cline.bot/customization/clineignore)           |
| Cursor            | [.cursorignore](https://cursor.com/docs/context/ignore-files)              |
| Gemini Code Assist| [.geminiignore, .aiexclude](https://geminicli.com/docs/cli/gemini-ignore/) |

## 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.*