You ask an AI coding agent to fix one bug.
The diff comes back with 14 changed files. Variables were renamed, imports reordered, a dependency was bumped "while it was there", and a helper you already had was rewritten from scratch. At the end it tells you the tests pass. You check, and nobody ran them.
The agent is capable. It just has no idea where the boundaries are.
So I wrote them down.
AGENTS.md
UNIVERSAL-AGENTS.md is a single, technology-agnostic AGENTS.md you drop into the root of any repository. It tells an AI agent how to analyze, plan, change, verify, and report, with one core idea:
When uncertain, do less, not more.
It is not tied to a language, framework, or tool. It works for Android, iOS, web, backend, desktop, games, libraries, and SDKs.
Here is the same request, "fix the login button", handled two ways. This is an illustration, not a benchmark.
Without guardrails
With the rules
The result is a small diff you can review in two minutes.
The original 26 sections cover the whole workflow. These are the ones that make the biggest difference.
1. Minimal changes only. Every changed line must have a clear relationship to the request. No drive-by refactors, formatting changes, renames, or dependency upgrades. The file puts it plainly: a change being beneficial does not make it in scope.
2. Existing code first. Search before writing. Reuse, then extend, and create new code only when nothing suitable exists.
3. Plan before implementing. A concise plan with a Before vs After visualization, kept proportional to the change:
Before After
User User
│ │
▼ ▼
Submit Submit
│ │
▼ ▼
No Validation Input Validation
│
▼
Processing
4. Ask, don't guess. If a request is ambiguous in a way that matters, the agent stops and asks the minimum number of questions.
5. Honest reporting. The agent must not claim tests passed unless they ran, or that something was verified when it wasn't.
There is also a full section on .gitignore management: detect the real stack, preserve existing rules, never ignore required files.
Agents now run commands, edit files, and touch Git. Sections 27–36 add rules for that:
The new sections only add to the original rules. Sections 1–26 keep their numbering and purpose.
adapters/ folder (Claude Code, Gemini CLI, GitHub Copilot, Cursor). Many tools read templates/AGENTS.project.template.md to AGENTS.project.md and fill in your build and test commands, conventions, and protected paths.
Project rules rank above the universal ones, except for the safety rules, which only an explicit user instruction can override.
The rules include a short report format, so every task ends the same way:
Changed: <files and a one-line description each>
Not changed: <things intentionally left alone>
Reused: <existing code relied on>
Documentation: <updated files, or "no update required">
Verification: <commands run and their actual results, or "not run: reason">
Assumptions: <or "none">
Observations: <unrelated issues worth knowing, or "none">
Reviewing becomes a checklist instead of an investigation.
The agent should behave like a disciplined software engineer:
None of that is exotic. It is what you'd expect from a good teammate, written down so an agent can follow it.
It's MIT licensed, so use it, fork it, and adapt it to your workflow:
👉 https://github.com/NTDevLops/UNIVERSAL-AGENTS.md
If it saves you one painful diff, a star helps other developers find it. If a rule is unclear or an agent finds a loophole, open an issue and I'll tighten it.
What's the worst thing an AI agent has done to your repo? Tell me in the comments.