Every engineering team has the same artifact: a wiki page, a README section, or a Notion doc titled something like "How We Work Here." Naming conventions. Branch policies. PR etiquette. The way migrations should be written. The list of files no one is allowed to touch without architecture review. It's usually a respectable document. It's also, in most teams, decorative — referenced during onboarding and then quietly ignored.

The reason it's decorative is structural. Conventions only become real when they're enforced at the moment of action. Pre-commit hooks catch some of them. CI catches more. Code review catches the rest, when reviewers happen to remember. But all three mechanisms only run on human-authored code. The moment an AI agent starts taking actions inside the repo, the convention layer has nothing watching it.

Claude Code's hook system is the fix for this gap. And once you've used it for a week, you start seeing the wiki page differently.

What Hooks Actually Do

Hooks in Claude Code are user-defined shell commands that run automatically in response to events inside an agent session. They fire before or after tool calls, on prompt submission, when the agent stops, when a notification triggers — events that, until recently, were entirely opaque to anything outside the model.

Pre-tool-call hooks. These run before Claude executes a tool — typically before an Edit, Write, or Bash call. They can inspect what the agent is about to do, mutate the parameters, or block the action entirely by returning a non-zero exit code. This is where most enforcement lives: catching an edit to a file the team has marked off-limits, blocking a Bash command that touches production, or rewriting a path before the action runs.

Post-tool-call hooks. These run after a tool succeeds. They're the right place for side effects — auto-formatting a file after Claude edits it, regenerating a type definition, refreshing a dependency lock, posting an event to a queue, or writing an audit log.

Stop hooks. These fire when the agent's work in a session ends. Teams use them to summarize changes, push notifications, attach diffs to a tracking system, or run a final validation sweep.

The hook layer is plain shell. It reads JSON from stdin, returns JSON or exit codes to control the flow. There's no SDK to learn, no permission model to negotiate. Anything you can do from a shell, you can do as a hook — and that ends up being most of the enforcement surface a team needs.

Why This Changes the Convention Calculus

In a human-only repo, conventions are a recommendation backed by social cost. A developer can technically break them; they just absorb the friction of a frowned-upon PR. That friction does a lot of work — it's why mature teams can ship without rigid enforcement everywhere.

In a repo with active AI agents, that friction disappears. The agent doesn't read the wiki page. It doesn't feel embarrassed when a teammate sighs at a naming choice. It optimizes for whatever the prompt told it to optimize for, against the patterns it sees in the codebase. If your convention is "never edit files in legacy/ without a senior review," the agent will happily edit them whenever the task seems to require it. The social mechanism that protected those files for years isn't part of the agent's loop.

Hooks turn the convention from a recommendation into a guarantee. A pre-tool-call hook that exits non-zero on any edit to legacy/** makes the convention real for the agent in a way the wiki page never was. The agent learns within the same session that the action is blocked, and either reroutes or asks. The convention stops being something humans remember and starts being something the system enforces.

This also changes what's worth writing down. Conventions that can be expressed as a hook script become valuable engineering artifacts. Conventions that can only be expressed as prose stay decorative. Teams that take hooks seriously start rewriting their wiki page in code.

What Teams Are Actually Wiring Up

The hook patterns that have shown up across early-adopter teams cluster into a few recognizable categories.

File-level guardrails. The most common first hook. Block edits to migrations after they've shipped. Block edits to config files outside a review process. Block writes to .env* files entirely. These three rules alone catch a significant share of the "the agent did something it shouldn't have" incidents that teams report in the first month.

Action-level guardrails. Bash commands need their own filtering. A pre-Bash hook that scans for rm -rf, git push --force, DROP TABLE, kubectl delete, or anything touching production credentials becomes table stakes once the agent has shell access. The cost of writing this is one afternoon; the cost of not writing it is one incident.

Automatic side effects. When the agent edits a TypeScript file, the post-edit hook runs the formatter, regenerates the API client, and updates the affected tests' snapshots. When it adds a migration, the hook regenerates the schema dump. The agent doesn't have to know about any of this — the hooks make the workflow consistent regardless of which tool wrote the file.

Audit and observability. Post-tool-call hooks that append events to an audit log let teams reconstruct exactly what the agent did across hundreds of sessions. This is the first thing security teams ask for, and it's also the first thing that helps when an agent does something surprising and you need to figure out why. The audit trail makes the agent reviewable in a way the agent's own logs don't.

Cross-team notifications. Stop hooks that post to Slack when an agent finishes a long-running task, or that file a PR comment summarizing the agent's changes. These don't enforce anything — they make the agent's work visible to humans who weren't watching the session.

How to Build a Hook Layer That Actually Holds

Teams that get hooks right tend to follow a similar pattern, even when they arrive at it independently.

Start with the blast-radius rules, not the niceties. The first hooks should block actions that are genuinely dangerous: edits to credentials, force-pushes, production touches, irreversible deletions. These are the rules that justify the hook system on day one. Style and formatting rules can come later.

Make hooks idempotent and fast. Hooks run on every matching tool call, often in tight loops. A hook that takes two seconds adds an hour to a long session. A hook with side effects that aren't safe to run twice will corrupt state when the agent retries. Write them like you'd write a critical-path script.

Fail loud and explain. A blocked tool call should return a clear message the agent can read and respond to. "Edit to legacy/auth.ts blocked — this file requires review by the security team. Open a ticket or use a different path." The agent can act on that. A bare exit code can't be interpreted.

Version-control the hook directory. Hooks are policy. They belong next to the code, reviewed in PRs, tested when they change. The team that treats hooks as ad-hoc scripts in someone's home directory loses the leverage. The team that treats them as production code keeps it.

Add a kill switch. Sometimes a hook itself becomes the bug. A way to bypass hooks for a specific session — with an audit log entry recording the bypass — is the difference between a hook layer the team trusts and one the team disables in frustration.

What This Means for How Teams Operate

The teams that have wired hooks into their Claude Code workflow seriously aren't just adding safety rails. They're encoding institutional knowledge in a place where it actually runs. The convention about which directories are off-limits used to live in a senior engineer's head. Now it lives in a file that fires on every edit. The convention about formatting used to live in a CI step that ran twenty minutes after the PR opened. Now it runs in the same session as the edit.

This compounds. Once the team has a hook layer they trust, they start delegating more to agents — because the safety surface is real, not aspirational. The agents take on bigger chunks of work, and the team's leverage scales without proportional risk. Teams that don't build the hook layer either stay timid with their agent usage or absorb the occasional incident, and both costs are larger than the hooks would have been.

The wiki page can stay. But the hook directory is where the conventions actually live now.

Conventions only matter when something enforces them. For most of engineering history, that something was a human reviewer who happened to remember the rule. Claude Code's hooks make it possible to encode the rule directly into the system's behavior — which means, for the first time, the convention layer can scale with the agent layer. Teams that treat their hooks the way they treat their CI will pull ahead of teams that treat them the way they treat their wiki.