Announcing Code Rules!
Agent guidance, one small insight at a time.
Code Rules is not the original tool I set out to build. In fact, how I got here is kind of an interesting story. But first, let's talk about what's shipping.
What is Code Rules?
Code Rules helps you organize your agent guidance into granular rules that you can hand to your agent at just the right time.
You write rules as individual Markdown files (or import them from rules libraries), and the Code Rules CLI will transpile all your rules into a set of consolidated Markdown files that guide agents to exactly the right place. Code Rules also includes a way to update your AGENTS.md file so that agents are explicitly instructed to read the code rules.
For example, you can define or import a bunch of rules for how testing should be handled, how observability should be implemented, or how Golang code should be written. You can put those in a project repo, or a shared repo, and the Code Rules CLI will pull in the right rules at the right versions at the right time and make them available as consolidated Markdown files in a /.code-rules folder in your repo.
Also introducing Rulemart!
Of course, writing rules can be a pain, and we all want to take advantage of the hard-earned insights others have already discovered. That's why I'm also excited to announce Rulemart, a registry of rules built by others so that you don't have to write all the rules yourself.
Rulemart has around 120 rules today, and I'm hoping that will grow over time.
Code Rules vs. alternatives
Skills
The primary alternative to using rules is giving agents guidance with skills.
I like skills a lot and use them often. But they suffer from a few issues.
- Skills are coarse-grained. A skill on how to write good tests is often a composite of many best practices, not all of which will apply all the time.
- Updating skills can be awkward. Ideally, you update your skills automatically based on your real-world agent sessions, but because they're coarse-grained, that's problematic, too. Do you pour all your insights into a single update? Do all your insights apply to all consumers of that skill?
- Skills are versioned, but only kind of. We tend to just ignore their version and assume latest is best.
- Skills are hard to read. In theory, you can just open up a Markdown file and read through the full skill. But in practice it's painful to do that. Plus, some skills are short, and some long. So there's no good way to scan a skill's contents at a glance.
So, skills are a key ingredient of a modern agentic setup, but skills can also be clumsy as a delivery vehicle for guidance.
Static checks
Static checks like linting rules or a script that returns a deterministic result are a complement to Code Rules, not an alternative.
If you have an opportunity to deterministically enforce a best practice, that will always be the best option. Deterministic checks are cheap and, by their nature, guaranteed. For example, I use linting rules in my TypeScript codebase to enforce that one layer of my system only ever calls a specific other layer by using Oxlint rules on the import statements.
But alas, deterministic checks don't cover all the guidance we want to give agents. When determinism isn't an option, rules are a good next step.
It started with a plan visualizer
Ok, back to that interesting story I mentioned.
When I started Fabrica, the first thing I wanted to build was a new and better plan visualizer: a tool for thinking through an idea and its architecture with an agent before any code gets written. In theory, planning should come first. If the plan is garbage, the best code in the world doesn't matter. So that's where I put my attention.
I started by designing the UX and getting alignment with the traditional agent plan. I had what I thought was a decent architecture, and, since coding is solved, I didn't need to worry much about the actual implementation. Because coding is solved, isn't it?
Well, I quickly discovered that coding may well be solved...for the teams who have invested a considerable amount of time locking down their codebase, sifting through the right skills, automating verification, setting up proper adversarial review, and applying a bunch of other techniques.
But I was building this tool on my own, and I was getting so buried in code reviews that had so many small issues that I was losing perspective of the big picture, not to mention my sanity.
Getting your agents to write good code by default
So I switched gears to solve that upstream problem: how can I tell my agents what I want them to do ("build feature X") and trust that how they do it aligns with what I want ("Yep, this code is structured exactly as I was hoping")?
It became clear that there were two moments in time to address this:
- Implementation. The agent builds it the right way.
- Validation. Something checks that the agent built it the right way.
I wanted to systematically insert agent guidance during both of these phases:
For implementation, I wanted the agent to automatically receive the directive "hey agent, when you build this, follow rules 5, 8, 9, and 16." For validation, I wanted my adversarial review to ask "does this pull request abide by rules 5, 8, 9, and 16? If not, how can we fix it?"
Working with rules
My workflow today makes use of a large collection of granular rules, each of which describes a single best practice.
Now I can capture a single insight as one rule. I can continue evolving that one insight over time with successive rule versions. I can convey whether my update is a "breaking change" (previous guidance no longer applies!) or a mere improvement on the same core guidance.
I can organize my rules into groups to help me, other humans, and agents make sense of when rules should apply. And when I want to share my rules with others, I can upload them to a rules library that's simply a git repo with rules in it. Consumers can then pull down exactly the rules they want.
Finally, I can browse available rules on Rulemart.
The big idea here is that granularity opens up many new possibilities and is, in certain situations, a better way to work.
But will agents really follow the rules?
Yes! I tested it across dozens of combinations, and all the major models implemented the rule guidance...except for Claude Haiku. He just did his own thing. So don't implement your production code with Claude Haiku.
But writing rules is hard
It is, but you can lean on others to do that!
First, we at Fabrica have published our own Fabrica Public Rules Library, but the best way to browse it is at Rulemart, which indexes rules from many different rules libraries and gives you a snazzy UI to browse it all.
And of course, you can ask your agent to write rules. In fact, Code Rules comes with a whole rubric about how to write rules that your agent can follow.
Try out Code Rules and Rulemart
Take a look at Code Rules and let me know what you think by filing a GitHub issue or reaching out via Fabrica.