How is AGENTS.override.md different from AGENTS.md? Why not just edit the current AGENTS.md file instead?
Override is usually for temporary or unique cases. Examples:
- Temporarily testing different agent behavior
- Override an inherited team file without deleting it. Could be for a developer-specific environment or local workflow.
- When certain files of a group of files require different instructions. So you create a new directory and add an override to be more explicit.
To say this differently, AGENTS.override.md is best when the override is specific to a directory, environment or process, while AGENTS.md remains the default shared config.
Example
MyApp/
├── AGENTS.md # Still loaded
└── Features/
└── ImageRendering/
├── AGENTS.md # Ignored
└── AGENTS.override.md # Loaded instead
How to have multiple agents.md files?
If you’re dropping specs into your repo and want to view / edit the specs from Xcode, then make sure the files are deselected from the target. Otherwise you end up having the compiler building multiple AGENTS.md files which cause an error in the compiler.
Multiple commands produce ‘/Users/mfaani/Library/Developer/Xcode/DerivedData/MYAPP-kwlcavcsytcadfajdfslfgiebfljl/Build/Products/Debug-iphonesimulator/MYAPP.app/AGENTS.md’