Someone’s teammate spent a few days doing something almost nobody bothers with. They read a hundred real AGENTS.md and CLAUDE.md files instead of guessing what belongs in one. The result became ossrules.md, an index pulling instructions straight from major open source repos like Next.js, Ollama, and Transformers. The original poster, a Redditor going by u/arcanearts101, shared the find in r/PromptEngineering after spending a couple of days poking through the raw files. I went and read a chunk of them myself, which is a strange way to spend an evening, but it paid off.
Quick start: if you maintain an AGENTS.md or CLAUDE.md file for your own repo, this post is for you. You’ll get four patterns worth stealing, the reasoning behind each one, and a pro tip on adapting them without copying blindly.
Here’s the twist. None of this is theoretical. Every file in the catalog is a rule set some maintainer actually shipped to production. It got tested against real contributors and real agents breaking real builds. That’s a different animal than a generic prompt-engineering thread. Most guides tell you what a good instructions file should look like in theory. This index shows you what one looks like after six months of an agent misbehaving, and a maintainer patching the rule that let it happen.
Four patterns keep showing up across the strongest files. Together they work as a mini workflow for rewriting your own instructions this week.
- 🧪 Map tests to what changed, don’t just say “run tests.” The Next.js file skips its test suite entirely for doc-only changes. It triggers codegen the moment a schema file moves. One commenter in the thread said mapping tests this way cut their token usage roughly in half. The agent stopped re-running suites that had nothing to do with the edit it was making. If your instructions currently say “run the tests” and leave it there, this is the easiest upgrade on the whole list.
- 🚫 Never leave a “don’t do X” rule floating on its own. Pair every prohibition with the exact alternative in the same sentence. “Don’t edit generated files” is a dead end for an agent with no other information, so it improvises. “Don’t edit generated files, edit the schema and run the generator instead” gives it somewhere to go. That’s the difference between a rule the model follows and one it quietly works around.
- 🔒 Flag autogenerated files by name. A single line like “*.d.ts and everything in /dist is generated, don’t hand-edit it” does the job. It stops an agent from politely “fixing” your build output on every single run. That sounds obvious once it’s written down, but plenty of instructions files never say which files are off-limits because a build step already owns them.
- 🗺️ Keep the root file small, route to nested ones. Instead of dumping 2,000 lines into a single system prompt, point to something like packages/*/AGENTS.md for anything package-specific. The agent only loads context for the part of the repo it’s actually touching. The root file stays readable for the humans on the team too.
Pro tip: steal the format before you steal the content. Pick two or three files from repos close to your own size and shape. A monorepo should study a monorepo, and a single-package library should study another single-package library. Copy the structure, not the specific wording. One Redditor in the thread flagged something else worth stealing too. Forcing the model to justify every edit against the rules changed their output more than any amount of rewording ever did. Add a line requiring the agent to name which rule an edit follows before it makes the change. Then watch how much sloppier work quietly disappears on its own.
That justification habit is worth calling out on its own, honestly. It turns your instructions file from a list of hopes into something the agent has to actively check itself against. That’s a small change with an outsized effect on how often it goes rogue.
If your instructions file hasn’t been touched since the day you wrote it, this is a decent excuse to crack it back open. Go browse the raw index yourself and see how a repo your size actually structures its rules. Pull the one pattern that would save you the most tokens this month. Then swing by the Reddit thread. 🔍 The comments have a few more patterns the post itself didn’t get to, and they’re worth the read. Half an hour there will save you more than half an hour of trial and error later.
Frequently Asked Questions
Q: How much can conditional test suites actually save on token usage?
Real users reported cutting token usage by roughly 50% on doc-only changes. The pattern is simple: map which tests run based on what changed (skip tests for docs, trigger codegen for schema changes). This keeps your agent from running unnecessary checks and burning context on irrelevant test failures.
Q: Why does my agent keep trying to “fix” auto-generated files like .d.ts or build outputs?
Without explicit guards, agents don’t know those files are auto-generated and treat them like regular code to improve. The fix: explicitly tell your agent which files are autogenerated so it stops wasting effort manually patching them.
Q: How do I prevent AI-generated content from being “publishable but forgettable”?
Require the AI to justify every edit before applying it, have it explain why a line is weak before it changes it. This forces you to review and agree (or push back) instead of blindly accepting rewrites. It’s slower, but the final output actually sounds like a person wrote it.
Q: Is it really better to pair “don’t do X” rules with exact alternatives instead of just stating the prohibition?
Yes. Open-ended rules like “don’t make breaking changes” leave too much interpretation. Instead, pair the prohibition with the exact behavior to use: “If the API changes, create a deprecation wrapper first.” This removes ambiguity and gets consistent results.
Cool resource: ossrules.md catalogs production AGENTS.md and CLAUDE.md files across open-source projects
by u/arcanearts101 in PromptEngineering