.gitignore` looks like the easiest file in a repo to get right. Agents still get it wrong in predictable ways:
- They paste a giant generic template covering twenty languages you don't use.
- They add a pattern broad enough to hide real source files.
- They reorder or reformat the whole file.
- They "fix" a problem by ignoring the file that causes it.
- They claim it works without checking.
The UNIVERSAL-AGENTS.md rules give .gitignore its own section (Section 13) for this reason. Here are the main ideas.
Rule 1: Don't touch it unless you need to
The agent should create or update .gitignore only when the requested change requires it, or when needed to stop project-generated, temporary, local, or development-specific files from being tracked by accident.
And the rule is explicit: don't modify it merely because a generic template could be added.
Rule 2: Look at the actual project first
Before changing anything, the agent works through a checklist: the languages in use, frameworks and runtimes, package managers and dependency directories, build systems and output directories, test and coverage tools, IDEs and editors, and the existing .gitignore.
Then it applies a rule I like a lot: never paste a generic template without analyzing the real project. In a monorepo, include rules only for technologies that actually exist in the repo. A Python project does not need Unity rules.
Rule 3: Preserve what's there
When updating an existing file, the agent must:
- Keep valid project-specific rules.
- Not overwrite custom patterns with a generated template.
- Not reorder rules or reformat the file without reason.
- Add new entries in a clear, consistent place.
- Avoid duplicates and conflicting patterns.
The summary is one sentence: make the smallest necessary change. That keeps the diff reviewable and the Git history clean.
Rule 4: Be precise, not broad
Broad patterns are how real files disappear from version control. The rules say to prefer precise patterns that target generated artifacts, and to avoid patterns that could ignore legitimate source files or required assets.
Rule 5: Never hide required files
Section 13.7 lists what must not be ignored: required source, configuration, templates, documentation, assets, intentionally tracked lockfiles, and files needed for builds, tests, or deployment. It also says never to use .gitignore to hide implementation problems.
Environment files get special care. Secrets must never be committed, but the agent shouldn't blanket-ignore all configuration either. Tracked example files like these should be preserved:
text
.env.example
.env.template
config.example
Rule 6: Ignoring doesn't untrack
This one trips up humans as well. Adding a pattern to .gitignore does not remove files Git already tracks. Section 13.8 tells the agent not to remove tracked files, or run destructive Git operations, just to enforce a new rule, unless you explicitly ask.
Section 27 reinforces it: no reset --hard, clean -fd, force-pushes, or history rewrites without explicit authorization.
Rule 7: Verify, honestly
After changing the file, the agent checks that the rules match the stack, required files aren't ignored, existing rules survived, and no duplicate, overly broad, or unrelated patterns slipped in. It must not claim it verified ignore behavior unless it actually checked.
A quick tip from me (not from the rules): you can check what a given path matches with git check-ignore -v path/to/file.
The one-paragraph summary
The rules' own summary of the whole section: when a modification is required, base .gitignore changes on the project's actual language, framework, runtime, package manager, build system, and tools, preserve existing custom rules, and add only the minimum patterns needed to keep logs, temp files, caches, build outputs, and local environment files out of version control.
Try it
Drop AGENTS.md into your repo root and your agent gets the full policy, plus the rest of the guardrails. MIT licensed, any stack.
👉 https://github.com/NTDevLops/UNIVERSAL-AGENTS.md
What's the worst .gitignore mistake you've seen an AI make?
Top comments (0)