"Almost every time" vs "every time": why hooks beat instructions for AI agents

The rule your agent keeps ignoring

You write "always run tests before committing" in your CLAUDE.md. Your agent follows it. Mostly. On the third run, it skips the tests. On the fifth run, it runs the wrong test suite. By the eighth run, you find a commit with zero test coverage and a cheerful "all checks passed" in the summary.

You add the instruction again, in bold this time. Maybe caps. ALWAYS RUN TESTS.

It helps -- for a while.

I spent months in this loop before I realized the problem wasn't the instruction or the agent. The problem was the mechanism. Instructions are requests. The agent can forget, deprioritize, or misinterpret them. What I needed wasn't a better-worded request. I needed a constraint that couldn't be ignored.

The line that changed how I think about agent control

SmartScope published an analysis of agent harness patterns that included one line I keep coming back to:

Writing "run the linter" in CLAUDE.md vs enforcing it with a hook is the difference between "almost every time" and "every time without exception."

Read that again. "Almost every time" vs "every time."

In normal software engineering, "almost every time" might be acceptable. Humans compensate. We notice when something feels off, we double-check, we catch our own mistakes. But agents don't have that instinct. An agent that skips the linter on one run doesn't feel guilty about it. It doesn't think "hmm, I should probably go back and check." It just moves on.

The gap between 90% and 100% execution isn't 10%. It's the difference between a system that mostly works and a system you can trust.

Soft constraints vs hard constraints

Let me make this concrete.

Soft constraint -- an instruction in CLAUDE.md:

## Rules
- Run tests before committing
- Check for TypeScript errors before pushing
- Lint all changed files

This is a suggestion. The agent reads it, intends to follow it, and usually does. But "usually" has a failure rate. The agent might decide the tests aren't relevant to a docs change. It might hit a context window limit and lose the instruction. It might just... not.

Hard constraint -- a pre-commit hook:

#!/bin/bash
# .claude/hooks/pre-commit.sh

# 1. Type check
npx tsc --noEmit
if [ $? -ne 0 ]; then
  echo "TypeScript type errors found -- commit blocked"
  exit 1
fi

# 2. Lint
npx eslint . --max-warnings 0
if [ $? -ne 0 ]; then
  echo "ESLint errors found -- commit blocked"
  exit 1
fi

# 3. Tests
npm test
if [ $? -ne 0 ]; then
  echo "Tests failed -- commit blocked"
  exit 1
fi

echo "All checks passed"

This is a law. The agent can't skip it. It can't reinterpret it. It can't decide "this time it's not relevant." The hook runs, the checks either pass or they don't, and if they don't, the commit doesn't happen. Period.

flowchart TD
    A[Agent writes code] --> B{Constraint type?}

    B -->|Soft: CLAUDE.md instruction| C[Agent decides whether to comply]
    C -->|~90%| D[Runs checks ✓]
    C -->|~10%| E[Skips checks ✗]
    D --> F[Commit]
    E --> F

    B -->|Hard: pre-commit hook| G[Hook runs automatically]
    G --> H{Checks pass?}
    H -->|Yes| I[Commit allowed ✓]
    H -->|No| J[Commit blocked ✗]
    J --> K[Agent must fix issues first]
    K --> G

    style E fill:#e74c3c,color:#fff
    style J fill:#e67e22,color:#fff
    style I fill:#27ae60,color:#fff
    style D fill:#27ae60,color:#fff

Think of it this way: you can keep telling someone to wash their hands before dinner. Or you can install a sensor on the faucet that won't let them leave the bathroom until water has run for 20 seconds. One approach relies on memory and goodwill. The other relies on plumbing.

I'll take plumbing.

What hooks actually are

Hooks are scripts that auto-execute at specific points in the agent's lifecycle. Claude Code's hooks system is the clearest implementation I've seen: you define a script, attach it to a lifecycle event (pre-commit, post-file-write, pre-tool-use, etc.), and the system runs it every time that event fires.

The key insight is that hooks operate at the infrastructure layer, not the instruction layer. The agent doesn't need to "remember" to run the hook. The hook runs because the system is wired that way. It's the same principle as CI/CD pipelines -- you don't ask developers to please run the build before merging. The pipeline runs the build, and if it fails, the merge is blocked.

NxCode's analysis of agent harness architectures puts it well:

Hook systems let you inject custom scripts at critical points in the agent lifecycle. Security scans, linting, policy enforcement -- all of it runs before changes are committed, not after someone remembers to ask for it.

"Not after someone remembers to ask for it." That's the whole game.

The 4 feedback loops

Hooks are the foundation, but they're part of a bigger picture. The quality of your agent setup depends on how many feedback loops you've built, and how fast each one closes.

I think of it as four layers, each operating on a different timescale.

graph TD
    subgraph "Loop 1: Immediate (seconds)"
        A1[Agent writes code] --> A2[Linter / type-checker fires]
        A2 --> A3[Agent fixes errors instantly]
    end

    subgraph "Loop 2: Task-level (minutes)"
        B1[Agent completes task] --> B2[Test suite runs]
        B2 --> B3[Agent fixes failures]
    end

    subgraph "Loop 3: Session-level (hours → days)"
        C1[Agent finishes session] --> C2[Human reviews output]
        C2 --> C3[Improvements go into AGENTS.md]
        C3 --> C4[Next session starts with better context]
    end

    subgraph "Loop 4: Strategic (weeks → months)"
        D1[Evaluate monthly results] --> D2[Restructure harness architecture]
        D2 --> D3[Add new hooks and skills]
        D3 --> D4[Agent operates in redesigned system]
    end

    A3 -.->|feeds into| B1
    B3 -.->|feeds into| C1
    C4 -.->|feeds into| D1

    style A1 fill:#3498db,color:#fff
    style B1 fill:#2ecc71,color:#fff
    style C1 fill:#e67e22,color:#fff
    style D1 fill:#9b59b6,color:#fff

Loop 1: immediate feedback (seconds)

The agent writes a line of code. The linter catches a type error. The agent fixes it before it finishes the function.

This is the tightest loop and the cheapest to run. Type checkers, linters, and formatters belong here. They catch 80% of trivial errors before those errors have a chance to compound.

The pre-commit hook I showed earlier is a Loop 1 mechanism. It's fast, automatic, and leaves no room for negotiation.

Loop 2: task-level feedback (minutes)

The agent finishes a feature. The test suite runs. Three tests fail. The agent reads the failures, traces the cause, and fixes the implementation.

This is where CI pipelines, integration tests, and quality scans live. Loop 2 catches the errors that Loop 1 can't -- things like "the function compiles but returns the wrong result" or "the API endpoint works but breaks the existing contract."

One thing I've learned: the test suite needs to be external to the agent. If the agent writes both the code and the tests, you get circular validation -- the agent confirms its own bugs as expected behavior. (I wrote about this specific failure mode in a previous article.) Loop 2 only works when the evaluation is independent.

Loop 3: session-level feedback (hours to days)

The agent completes a day's work. I review the output. I notice patterns -- maybe the agent keeps writing overly verbose error messages, or it's using a deprecated API, or it's not following the project's naming conventions.

I take those observations and add them to AGENTS.md. Tomorrow's agent reads the updated file and works in an improved environment. The agent didn't learn anything -- but the harness did.

This is the loop most teams skip, and it's the one that matters most for long-term quality. Without Loop 3, you're running the same agent in the same environment forever, hoping it'll get better on its own. It won't. The harness has to evolve.

Loop 4: strategic feedback (weeks to months)

Zoom out further. Look at a month of agent output. Are the hooks catching the right things? Are there failure patterns that none of the current loops address? Is the overall architecture of the harness still serving the project?

This is where you make structural changes: adding new skills, restructuring the AGENTS.md hierarchy, introducing new hook types, or rethinking which tasks the agent should handle at all.

Loop 4 is slow and expensive. But it's how you go from "I have a bunch of scripts" to "I have a system that keeps getting better."

The context reset pattern

One more concept that ties this together: what happens when agents run for a long time?

Anthropic documented a pattern they call the "Initializer-Worker" split. The idea is simple but effective. Instead of running one long agent session that gradually loses context as the window fills up, you split the work into two roles:

• Initializer: reads the project state, decides what needs doing, and writes a focused brief
• Worker: reads only the brief and executes the task in a fresh context

The Worker starts clean every time. No accumulated confusion from previous tasks. No context window bloat. The hooks and feedback loops still apply -- they're attached to the lifecycle, not to the session length.

This matters because context degradation is one of the sneaky ways agents fail. The agent starts strong, but after 45 minutes of accumulated context, it starts making weird decisions. Hooks can't fix context degradation directly, but the Initializer-Worker pattern can -- by ensuring the Worker always starts with a focused, clean context.

What this looks like in practice

Here's how these pieces fit together in a real project:

CLAUDE.md holds the soft constraints -- conventions, preferences, project-specific knowledge. This is the "what" and "why."

Hooks enforce the hard constraints -- linting, type-checking, testing. This is the "no exceptions" layer.

Feedback loops connect the two. When a soft constraint keeps being violated, you promote it to a hook. When a hook keeps catching the same error, you add the pattern to CLAUDE.md so the agent stops making it in the first place. The system tightens over time.

Week 1: Agent skips linting sometimes
  → Add lint to CLAUDE.md (soft constraint)

Week 2: Agent still skips linting
  → Add pre-commit hook (hard constraint)

Week 3: Hook catches 15 lint errors per day
  → Add common patterns to CLAUDE.md
  → Lint errors drop to 2 per day

Week 4: Hook rarely fires
  → The harness taught the agent (through Loop 3)

This is the real payoff. The harness doesn't just catch mistakes -- it reduces them over time. Each loop feeds into the next, and the whole system converges toward fewer errors and fewer interventions.

The harness evolves, the agent doesn't

Here's the thing that took me longest to internalize: the agent isn't going to get better at following your instructions. Not across sessions. Not across weeks. Every new session starts fresh.

But the harness can get better. Every hook you add, every AGENTS.md update, every feedback loop you close -- that's permanent improvement. The agent stays the same, but it operates in a progressively better-designed environment.

Stop optimizing the agent. Start optimizing the harness.

And if you take one thing from this article, let it be the SmartScope line: instructions are "almost every time." Hooks are "every time without exception." The gap between those two phrases is where your bugs live.

What's the one rule your agent keeps ignoring? That rule is your first hook.

---

Want to go deeper? Hooks, lifecycle management, and feedback loops are chapters in a larger framework I wrote about in Harness Engineering: From Using AI to Controlling AI -- covering the full architecture of building systems that control AI agents, not just use them.