← Back to Blog

Steering, Rules, and Hooks: The Referee's Whistle for Coding Agents

November 8, 2026 · 4 min read
Steering, Rules, and Hooks: The Referee's Whistle for Coding Agents - Why instructions in AGENTS.md get ignored, how deterministic hooks block bad commits, and how subagents eliminate self-review bias.

An engineer adds a bold rule to their project guide: “Always run tests before completing a task, and never leave broken imports.”

Three turns into a complex refactor, the coding agent touches six files, ignores the test command completely, and proudly reports: “Refactoring complete! All functions have been updated according to your request.”

The engineer runs git diff and finds broken syntax and twelve failing tests.

This failure happens because teams confuse advice with control.

In football, a manager can tell players in the pre-match talk: “Never touch the ball with your hands inside the penalty box.” That is tactical guidance. But when a defender is off balance and a shot flies toward the top corner, human instinct overrides verbal advice. The arm goes up.

The referee’s whistle is not tactical guidance. It is an immovable barrier. When the ball touches an outstretched hand, the whistle blows, play halts instantly, and the referee points to the penalty spot. The player cannot negotiate or talk their way out of it. The game stops until the penalty is taken.

In coding agents, files like AGENTS.md and CLAUDE.md are the manager’s pre-match talk. Hooks are the referee’s whistle.


The Reality

Large language models generate text based on probability. Under heavy context load, soft rules written in markdown become easy to overlook. When a model faces an ambiguous error, its training pushes it toward concluding the conversation and telling you the job is finished.

To steer an agent reliably across an entire codebase, you need four distinct layers, each loaded at a different point in the loop.

1. Global Repository Knowledge (AGENTS.md)

This file should be short, usually under one page. It defines baseline facts: what package manager to use, what command boots the development server, and where the core architecture lives. If you put fifty micro-rules in this file, you waste tokens on every prompt and dilute the model’s focus.

2. Path-Scoped Rules

An agent working on frontend CSS does not need to know how your backend validates database migrations. Path-scoped rules live inside specific directories and load only when the agent edits files in that tree. A rule stating “all HTTP handlers must validate payloads with Zod” belongs inside your API folder, not in the root project file.

3. Deterministic Gates: Hooks

A hook is not a prompt. It is a shell script wired into the agent’s execution harness.

When the agent attempts to finalize a task, a Stop Hook executes your test suite and linter in the background. If the command fails with exit code 1, the harness blocks the agent from quitting. It feeds the terminal errors directly back into the conversation as a new observation.

The model is trapped in the loop until the code actually compiles and passes. You do not ask the agent to test its code. You make exit mechanically impossible until the tests turn green.


The Why

Why can’t a single agent just check its own work?

When a single agent plans, writes, and reviews its own code, it suffers from confirmation bias. It assumes its implementation works because it just wrote it. By delegating work across three distinct subagents, you break that cycle:

  1. A Planner with read-only permissions that investigates the codebase and drafts a specification without touching files.
  2. An Implementer that writes the code following the agreed plan.
  3. A Reviewer that inspects the git diff with zero access to the planner’s notes, evaluating the work with fresh, uncorrupted eyes.

Where does this break down?

Prompt creep and fragile hooks.

When teams treat AGENTS.md like a junk drawer, the file grows to hundreds of lines. The agent spends half its attention reading irrelevant rules before touching code. On the other extreme, slow hooks that run a 15-minute end-to-end test suite freeze the agent loop. Hooks must be fast and deterministic: typechecks, linters, and fast unit tests.

The Takeaway

A sentence in your instructions asks for compliance; an executable hook enforces it.


AI specialists call it: Repository Steering / Path-Scoped Rules / Deterministic Harness Hooks / Subagent Triad
Instruction adherence degrades under context saturation. Hard constraints must be enforced deterministically outside LLM inference via harness-level lifecycle hooks (pre-tool execution, post-edit verification, and stop gates). Global repository documentation (AGENTS.md) provides static environment invariants, while scoped rule sets minimize working context. Decoupling planning, implementation, and review into isolated subagent scopes prevents confirmation bias and catches hallucinations.

💬 What rule in your team repository do AI agents ignore most consistently?

Part 4 of 10 | #CodingAgentsForHumans

Have a project in mind?

Let's talk about how we can help.

Got a project idea? →