There are two places to put the standing rules you want a coding agent to follow: in a file in the repo, or built into the tool that runs the agent. I've ended up with both, and they trade off differently.
In the repo, the rules are versioned. They show up in pull requests, the whole team sees them, and they travel with a clone. The cost is that you write and maintain them per project, and they're only as good as the last person who edited them.
In the tool, they work in every project and for every agent with no setup. The cost is that they're invisible: nobody reviews a diff of them, and they can clash with how a particular repo does things.
Styx does the second kind. It builds in guidance from a few public repos: Ponytail for coding, Impeccable for interfaces, design-critique for reviewing a design, and architecture-designer for system design. Only the core rules are included, each applies only to that kind of work, and your project's own design system and rules come first.
That last part is the rule I'd defend: when the two disagree, the repo wins, because it knows the project and the tool doesn't.
Do you agree, or do you let the tool override the repo?
Top comments (1)
Repo wins for me too, with one exception: safety rules. A tool-level "never force-push to main" should hold even when a repo forgets to say it, because a repo can only add the rules someone remembered to write. Conventions, style, architecture: the repo, every time.