Architecture decision

Hooks vs Agent Instructions

Should the model be told to do something, or should the system enforce it?

Get the short answerReview evidence

The short answer

Use instructions for contextual judgment. Use hooks for formatting, validation, logging, blocking, or environment work that must happen at a specific event.

Choose

Hooks

Deterministic handlers that run at defined points in an agent lifecycle to validate, block, transform, log, or trigger work.

  • A command must run before or after a tool call or file change.
  • Policy enforcement cannot depend on model attention.
  • A deterministic result, exit code, or audit record is required.
Open the Hooks guide

Choose

Repository instructions

Durable, version-controlled guidance that tells coding agents how a repository is organized, how to verify work, and which boundaries matter.

  • The agent needs context to choose among several acceptable approaches.
  • The guidance describes repository architecture or team preference.
  • Strict execution at a lifecycle event would be unnecessarily rigid.
Open the Repository instructions guide
Use both

How the layers combine

  1. 01

    Explain the policy and desired behavior in repository instructions.

  2. 02

    Enforce the narrow, non-negotiable part with a scoped hook.

  3. 03

    Return clear hook feedback so the agent can recover instead of looping.

Decision review

Questions to answer before implementation

  • Would forgetting the instruction create material risk?
  • Is there one narrow lifecycle event to target?
  • Can the hook fail safely and within a timeout?
  • Are downloaded commands and destinations reviewed?
  • Does the instruction remain useful after enforcement moves to code?

Evidence ledger

Primary documentation for both sides

Reviewed July 26, 2026. Use the provider documentation for current configuration and security behavior.

Codex hooks

OpenAI

Codex lifecycle hooks, configuration, and trust guidance.

Automate workflows with hooks

Anthropic

Claude Code hook events, deterministic controls, configuration, and examples.

AGENTS.md specification and examples

AGENTS.md

The portable AGENTS.md format and repository instruction pattern.

Codex AGENTS.md guidance

OpenAI

Codex discovery, precedence, scope, and maintenance guidance.

How Claude remembers your project

Anthropic

CLAUDE.md locations, loading behavior, concise instruction guidance, and AGENTS.md interoperability.