When teammates use different operating systems, shells, containers, or local tools, keep project rules in a shared agents.md and put machine-specific directions in an ignored agents.local.md. That is Vinicius de Santana’s proposed “local override” pattern for reducing infrastructure friction. It is a practitioner’s proposal, not a universal convention: check that your AI-agent harness discovers both files and gives local instructions the intended precedence before relying on it.
Why separate shared rules from local execution details?
A project’s architectural and business conventions should not depend on the environment of the person who first wrote its agent instructions. A shared rule might specify the backend framework or interface architecture; a local direction might specify which shell to use, where a developer keeps a checkout, or how to run a command on their machine.
As an Amazon Associate I earn from qualifying purchases.
De Santana summarizes the distinction this way: “The central thesis is simple: AI instructions must not mix the software’s business or architectural rules with the developer’s local infrastructure commands.” The proposal aims to let the team share project guidance without forcing everyone into one developer’s setup.
What belongs in each instruction file?
| Dimension | agents.md |
agents.local.md |
|---|---|---|
| Owner | The project team | One developer |
| Version control | Committed with the project | Excluded from Git |
| Scope | Shared business, architecture, and technical conventions | Local operating system, shell, paths, tools, and response preferences |
| Intended behavior | Sets common project guidance | Overrides applicable defaults for that developer, if the harness supports the behavior |
These filenames and precedence are part of the author’s suggested pattern. They are not established here as standard names supported by every agent harness.
#1 Best Overall
How to set up the proposed pattern
-
Ignore the local file. Add
agents.local.mdto the repository’s.gitignoreso personal configuration is not committed. -
Keep shared conventions in the tracked file. Version
agents.mdwith the team’s project-wide technical guidance.Rank #2
-
Tell the agent what to check. In the shared file, instruct the agent to look for a root-level
agents.local.mdbefore suggesting or running terminal commands, and explain that its execution directions, paths, and preferences take precedence when present.Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteSpecial offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Write local directions for the actual environment. Each developer can describe their own shell, tools, paths, and preferred response format in their local file.
What can local instructions customize?
Commands and execution environment
One developer could ask the agent to run database migrations through isolated Docker containers; another could use native executables and bash paths under WSL2. A local profile could also prohibit PowerShell syntax for someone who works in WSL2. These are examples of personal configurations, not recommended defaults for every team.
Local tools and workloads
A developer might direct analysis of large local logs to an Ollama model running on their own machine rather than use cloud-model tokens. That example does not establish that a local model is appropriate for every task; suitability depends on the workload and setup.
Rank #4
Response style
A developer could ask for only changed code blocks instead of explanatory prose. Such preferences can be kept personal without making them a project-wide requirement.
Free tools Windows power users keep installed
One-click scans. No signup required.
Verify the harness before depending on overrides
Writing a discovery instruction into agents.md does not by itself prove that a particular tool will load agents.local.md, or that it will treat its contents as higher priority. Test the behavior in the harness and version you use before allowing local instructions to govern commands.
Best Value
- Confirm that the harness reads the shared file and the root-level local file.
- Use a harmless test instruction in the local file that differs from the shared default, then check which one the agent follows.
- Check command suggestions as well as execution behavior if the agent can run terminal commands.
- Make sure teammates know which guidance is shared and which is intentionally private to their working copy.
De Santana argues that the separation can reduce team friction and help prevent agents from disrupting colleagues’ terminals. The article does not report a study, quantified productivity result, or comparative evaluation, so treat those benefits as the author’s rationale rather than measured outcomes.
Source
Vinicius de Santana, “Agents Override: Local Harness in Heterogeneous Teams,” DEV Community, posted October 5, 2026.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →
