Why prompt files, skill definitions, and agent instructions aren't enough for production agent systems — and what actually works.
The common pattern for building AI agent systems goes like this: write a detailed prompt file. List the rules. Describe the workflow. Maybe add a skills file with best practices. Deploy. Hope the agent follows the instructions.
It doesn't.
We run seven autonomous agents building an intelligence product in parallel sprints. After months of production use, one finding is consistent: instructions in prompt files drift and get ignored. Not maliciously. Not randomly. Predictably — in proportion to how much other context the agent is holding and how many steps deep it is in a task.
A 200-line agent definition that says "always read user feedback before planning" works great on turn one. By turn fifteen, with a full sprint of build context in memory, the agent has quietly deprioritized it. Not because it decided to — because the instruction is competing with hundreds of other tokens for attention, and losing.
Instructions in flat files are suggestions to the model. The model has its own agency — its own judgment about what matters right now. If your system requires something to happen every time, a suggestion isn't enough.
These aren't hypothetical failure modes. These are things that happened repeatedly in a system with well-written agent definitions, detailed skills files, and clear CLAUDE.md instructions:
Agents were instructed to read user feedback before every planning phase. They did — sometimes. Over 10 sprint sessions, agents skipped feedback reading in roughly 40% of sprints. The instruction was right there in the prompt. They just... didn't.
The sprint has six phases. Agents would occasionally merge two phases into one, or skip verification entirely when they felt confident about their work. "I already checked this during build" — a judgment call no one asked them to make.
Agents scored their own output 8/10 while human evaluation averaged 2.5/10. The scoring instructions were explicit. The agents followed them — they just applied different standards than the human would.
Agent files were modified on the development machine but never deployed to production. Two full sessions of improvements existed only locally. The instruction to deploy after changes was in CLAUDE.md. Nobody checked.
Agents were told to read other agents' sync updates before planning. They would read them on the first sprint, then stop. By sprint three, agents were building in isolation — duplicating work or creating conflicts.
The specification phase existed in the workflow. Agents would write a one-line spec and jump straight to code. The instruction said "write detailed acceptance criteria." The agent decided its mental model was sufficient.
Every one of these failures happened despite clear, well-written instructions. The instructions were correct. The agents were capable. The problem is the mechanism: prompt-based instructions are inputs to reasoning, not constraints on behavior. The agent reasons about whether to follow them.
A hook is a shell script that runs automatically at a specific point in the agent's lifecycle. It executes outside the model — in deterministic code, not in the LLM's reasoning loop. The agent doesn't choose whether to follow it. It just happens.
The key distinction: instructions operate inside the model's reasoning. Hooks operate outside it. Instructions can be deprioritized, reinterpreted, or skipped. Hooks execute regardless of what the model thinks.
Block an action until a condition is met. "Don't start planning until you've loaded the latest feedback." "Don't stop the session until the build trace is updated." The agent literally cannot proceed until the gate opens.
Automatically add context the agent needs but might forget to load. Before every planning phase, inject the feedback queue. Before every build phase, inject the spec criteria. The agent doesn't have to remember to look — the information is already there.
After the agent completes an action, check if the result meets standards. Did the spec actually contain acceptance criteria? Did the build output match the spec? If not, send the agent back with specific feedback about what's missing.
Control which agent runs next and what it sees. After the build phase completes, the router reads the sprint state, determines the next phase, and launches the correct specialist agent with the right context. The model never decides its own phase ordering.
Our system has seven agents running six-phase sprints to build an intelligence product for venture investing. Here are the hooks that make it actually work:
What it does: Before any agent launches, a hook reads the machine's sprint state file, determines which phase should run next, and injects the correct specialist prompt. The agent receives its assignment — it doesn't pick one.
What it replaced: An instruction that said "check your manifest and execute the next phase." Agents would sometimes re-run a phase they'd already completed, or skip ahead to a phase they found more interesting.
Why it matters: In a six-phase sprint (Plan, Spec, Build, Review, Verify, Sync), phase ordering is critical. A build without a spec is guesswork. A sync without verification ships unchecked work. The router makes this impossible to violate.
What it does: Before the planning phase launches, a hook checks if the agent's feedback store has unread items. If it does, the hook injects those items into the planning context. The agent literally cannot plan without seeing its feedback.
What it replaced: An instruction that said "read your feedback store before planning." Agents followed this ~60% of the time. The other 40%, they planned based on what they remembered from previous sprints — which was often wrong or outdated.
Why it matters: The entire system improves through feedback. If agents skip feedback, the improvement loop breaks. This was the single highest-impact hook we deployed.
What it does: When an agent tries to end its session, a hook checks if any agent definition files or skills were modified. If they were, it checks if the deploy script ran. If not, it blocks the session from ending and tells the agent to deploy first.
What it replaced: An instruction that said "deploy after modifying agent files." Across two full sessions, agents modified files on the development machine and marked their sprint as complete — without deploying to production. The improvements existed only on a laptop.
Why it matters: An undeployed improvement doesn't exist. This hook closes the gap between "I built it" and "it's live."
What it does: Before any file write, a hook checks if the target is a sprint state file (manifest). If it is, the hook validates the write: is the new state a valid transition from the current state? Is the format correct? If not, the write is blocked.
What it replaced: Agents occasionally wrote malformed state files, or transitioned to invalid states (e.g., jumping from Plan directly to Sync, skipping Build entirely). With seven agents sharing a state system, one corrupted file cascades.
Why it matters: Shared state in a multi-agent system is like a shared database. You don't let applications write arbitrary SQL — you validate inputs. Same principle.
This isn't about distrusting the model. It's about using the right tool for each job. Models are extraordinary at reasoning, analysis, and creative problem-solving. They're unreliable at procedural discipline — doing the same thing the same way every time, especially under context pressure.
Hooks handle the procedural. Models handle the reasoning. The system gets both.
| Put in Prompts / Skills | Put in Hooks |
|---|---|
| How to analyze a problem | Which problem to analyze next |
| How to write good code | What spec criteria to verify against |
| How to synthesize research findings | That research must happen before building |
| How to evaluate quality | That evaluation can't be skipped |
| How to write a useful sync update | That the session can't end without one |
| Domain knowledge and reasoning patterns | Workflow sequencing and state transitions |
Before hooks, we spent hours rewording prompts: "Always read feedback" became "You MUST read feedback" became "CRITICAL: feedback reading is mandatory." None of it worked reliably. Hooks made the wording irrelevant — the behavior is enforced regardless of how the prompt is phrased.
When hooks handle sequencing, gating, and validation, the agent can focus entirely on reasoning. You give it more freedom within each phase because the guard rails are structural, not verbal. Better reasoning, better constraints — not a trade-off.
Running seven agents in parallel sounds chaotic. It isn't — because hooks manage the coordination. State transitions are validated. Shared files are protected. Context is injected. No agent can corrupt another's work. The coordination layer is deterministic, even though the work layer is probabilistic.
When something goes wrong in a prompt-only system, you don't know if the agent ignored the instruction, misinterpreted it, or never saw it. When something goes wrong in a hook-enforced system, you know the hooks ran (they always do) — so the failure is in the agent's reasoning, which you can debug.
If you're building an agent system that needs to work reliably — not demo-reliably, but production-reliably — you need hooks. Not as an optional enhancement. As the foundation.
Skills and prompts tell the agent how to think. Hooks tell the system what must happen. Both are necessary. Neither is sufficient alone.
The question isn't "can the agent follow instructions?" It's "what happens when it doesn't?" If the answer is "the system breaks silently," you have a demo. If the answer is "a hook catches it and redirects," you have a product.