My AI's rules only worked because one tool bothered to read them

I had a rule I was proud of. Always start from the real product. Never redraw a screen from scratch when we've already captured the real one. It was written down, it was clear, and it worked beautifully. Then I pointed a different AI tool at the same project and watched it cheerfully redraw a screen we already had, pixel-perfect capture sitting right there unused.

My first reaction was to be annoyed at the tool. That was unfair. It hadn't disobeyed. Nobody had told it the rule existed.

The rule was fine. It was unreachable.

Here's what I'd missed. My rule lived in CLAUDE.md, and Claude Code auto-loads that file at the start of every session, nested, all the way down the folder tree. So the rule was always just there, quietly steering everything, and I'd started to think of it as a property of the project. It wasn't. It was a property of one tool's habit of reading one filename.

The tool I'd pointed at the project was Pencil, a design-file agent. It read the one document that looked like project context to it and got on with the job. It has no project-instruction auto-load convention at all, which is not a criticism, it's just a fact about it that I hadn't checked. Its own guidelines tool returns its built-in design recipes, not anything about my product.

So the rule wasn't wrong. It was unreachable. And an unreachable rule is exactly as useful as no rule at all.

The fix has a filename, and the filename is the least important part

The convention people are converging on is AGENTS.md, a vendor-neutral entry file that a growing list of tools auto-load. It's the portable analogue of the host-specific one. So I added it.

That took ten minutes and it is not the interesting part of this post. Three decisions around it were.

It's a real file, not a symlink. My instinct was to symlink AGENTS.md at CLAUDE.md so there would be one source of truth. Don't. Symlinks don't survive a zip reliably across platforms, and this package gets distributed as a zip, so the elegant version would have silently arrived as a broken pointer on somebody's Windows machine.

It's written to work alone. It points at the full instruction file as the real source of truth, and then it inlines the handful of rules that break most often when something else is driving: start from the captured baseline, stop at every gate, the AI recommends and the human decides, never fabricate a value, one feature per session. A host that reads only the entry file and nothing else still behaves. If you write your portable file as a table of contents, you've written a file that only helps hosts that were going to be fine anyway.

The move that would actually have prevented the whole incident had nothing to do with either file. Pencil didn't read my instructions, but it did read the product context document, because that's the file that looks like context. And that document contained zero references to the captured baselines. Not a mention. So I added a callout to the top of it, pointing at the snapshot library as the primary source of layout truth.

That one edit, on its own, would have caught the miss. Put the pointer in the artifact the other agent actually opens, not only in the file you wish it opened.

Reachability, not naming

So I stopped treating "I wrote it down" as "the AI will follow it," and started asking a different question before I hand a project to anything new. Will this particular tool actually load this?

If it auto-loads a known file, great, and the vendor-neutral name gives you the best odds. If it doesn't, the rule has to ride in the prompt itself, pasted in at the top, because that's the one channel every tool reads. I keep a short kickoff snippet at the bottom of the portable file for exactly this, so handing the rules to a convention-less tool is a copy and a paste rather than a decision.

And check the artifacts. Your instruction file is one of several things a new agent might open, and it is usually not the first.

Your carefully written AI rules are worth exactly as much as the odds that the host reads them. One tool's helpful auto-load habit had been quietly making my rules look load-bearing when they were really just lucky. The moment I changed tools, the luck ran out.

Write the rules to the lowest common denominator of how these things load context. Put them where the most hosts will read them, mirror the important ones into the files the others read instead, and for anything that reads nothing, hand the rules over in the prompt yourself. A rule the tool never sees isn't a weak rule. It's not a rule.

---

Part of a series on building an AI collaborator for our design team at Xflow. Each post stands on its own.