Instruction-file rules that actually bind (QWEN.md / AGENTS.md) — 5 free patterns, MIT

[soul-sol]

Most instruction files — QWEN.md, CLAUDE.md, AGENTS.md, whatever your CLI reads — end up saying something like "write clean code, be careful with destructive operations, ask if unsure." The agent reads it, agrees with it, and then does whatever the last 200 lines of context suggested.

The file isn't wrong. It just isn't a rule. Nothing in it can be checked, so nothing in it binds.

After a few months of this I started writing instruction-file clauses in a fixed shape, and the difference was immediate. I open-sourced five of them (MIT): https://github.com/soul-sol/claude-md-patterns

What makes a clause bind

A rule the agent will actually follow has four parts:

1. Trigger — the exact condition where it applies ("any browser launch", "before every commit", "when a worker exits")
2. Check — a command, string, or state that is either true or false. If a reviewer can't grep for it, the agent can't enforce it on itself either
3. Stop condition — what to do when the check fails, named explicitly (ABORT: <reason>), not implied
4. Evidence — what must be left behind so you can see afterwards whether the rule was applied

Compare:

# Doesn't bind
Be careful with browser automation; don't touch the user's data.

# Binds
Every browser launch MUST pass --user-data-dir="<PROJECT_DIR>/.automation-profile".
NEVER read, copy, or enumerate the real profile directories (<PATHS...>).
Log the full launch command before running. If any log shows a launch without
--user-data-dir, stop immediately and report: ABORT: real-profile contact <command>.

The second version has a trigger, a grep-able check, an explicit abort, and a logged artifact. That one gets followed; the first is wallpaper. (I learned this one the expensive way — an automation run using the default profile cost me about 2,000 bookmarks.)

The five free patterns

• Autonomy clause — stops workers that quietly wait for approval nobody will give
• Done is evidence — completion means command + exit code + diff, never prose
• Browser profile quarantine — the one above
• Look before you destroy — read the target before any overwrite or delete
• Reassign, don't retry — same worker fails twice, switch tools instead of burning a third attempt

Two adoption rules that matter more than the patterns

Start with five, not thirty. A bloated instruction file is its own failure mode — the agent's attention budget is finite, and rules at the bottom of a long file effectively don't exist. Add a rule only when you hit the failure it prevents; a rule adopted after the incident gets followed, a rule adopted preemptively becomes noise.

Probe it from a fresh session. New process, no history:

# 1. Can it restate the rule unprompted?
<your-cli> -p "Without looking anything up: what must you do before launching a browser here, and what is the abort condition?"

# 2. Give it a task that would violate the rule if the rule were absent.

Vague answer to (1) → the rule is too long or too far down. (2) proceeds without the guard → it isn't binding. A rule you've never probed is a rule you're guessing about.

Works the same for QWEN.md as for any other instruction file — the shape is what matters, not the filename. PRs welcome if you have clauses that survived contact with real failures.