Member-only story
9 tips that improve agent protocol files
Tony M9 min read·Just now--
Protocol files are machine-facing context documents that live alongside code. They are not instructions for humans. They are constraint layers written explicitly for automated contributors.
If you’re shipping with agents in the loop, you are likely already using them in some form. Different ecosystems use different names — AGENTS, CLAUDE, etc. — but the job is the same. Protocol files define what automation may do, must not do, and what to do when it can’t proceed safely.
It’s easy to write a protocol file that sounds reasonable and still fails under stress. A “helpful” paragraph becomes ambiguous, or a rule that feels obvious splits into three interpretations across three models. Drift rarely arrives as a single mistake. Drift shows up as small ambiguities that snowball into inconsistent outcomes.
Here’s the challenge. Write protocol files that are deterministic enough to trust. They don’t have to be perfect, just solid enough so that different automated contributors converge on the same decisions, the same escalation points, and the same artifacts. If automation feels boring and consistent, you got it right.
The listed tips are lessons learned in real-world environments. If you’d like examples, Prism (https://github.com/tonym/prism) is a useful reference system that organizes protocol files in an…
