An Instruction Is Not a Guarantee

Spec-driven engineering means writing down what an agent should build before it writes code. I still believe in it: a spec is the difference between directing an engineer and hoping a competent one appears in the diff.

Then the work became autonomous: reading the spec, splitting tasks, writing code, running tests, and deciding when to continue. The spec answered what to build, but not what could be skipped, what “done” meant, or whether the model could grade its own homework.

Why does an AI agent stop following instructions in a long session?

Not because the model is careless or dishonest: attention isn't memory. A written rule must be recalled and reapplied at every relevant moment, while a long session keeps putting new demands in front of it.

I wrote rules for it: never commit straight to main; never call a test passing without running it; never skip a step because it looks trivial. Reasonable rules still remained sentences in markdown, vulnerable to drift deep into an autonomous run.

"An instruction like ‘never do X’ in a markdown file is still just an instruction."

Is a better-written spec enough to control an agent?

No. Clearer wording does not turn an instruction into enforcement. If I mean never, wanting isn't a mechanism; the rule must run whether the model remembers it or not.

How do you enforce a rule an agent will actually follow?

Move it out of the prompt: a skill defines the discipline, a hook blocks disallowed actions, a gate checks evidence, and an independent model reviews the draft.

What this looks like on disk

This uses Claude Code's extension points: global rules for the machine, project rules for one repo.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/block-force-push.sh" }
        ]
      }
    ]
  }
}

#!/bin/bash
# Claude Code passes the pending call as JSON on stdin
cmd=$(cat | jq -r '.tool_input.command')

if echo "$cmd" | grep -qE '\-\-force.*(main|master)'; then
  echo "Force-push to main is blocked. Do it on purpose, not by muscle memory." 1>&2
  exit 2
fi
exit 0

#!/bin/bash
# Runs when Claude finishes a turn — checks evidence, not the summary
if ! grep -q "0 failed" test_output.txt 2>/dev/null; then
  echo "Gate failed: no test_output.txt with a real 0-failed line." 1>&2
  exit 2
fi
exit 0

---
name: reviewer
description: Reviews a diff. Never invoked to write one.
model: opus
---

You did not write this code. Assume it's wrong until you find evidence it isn't.
Check the diff against the stated requirement, not against what you'd guess the author meant.
Flag anything you can't verify — don't fill the gap with good faith.

These are plain text files wired in before a run goes sideways. A failed gate or rejected review returns the work for rebuilding; the transcript is not the enforcement layer.

The honest way to describe where this leaves me: Claude Code has stopped being an assistant I supervise and started being an engineer operating inside a factory that has its own inspectors. I still write the spec. I still decide what gets built. I just stopped assuming that writing "and never do X" at the top of a file was the same thing as making it true.