This is Part 4 of a four-part series on onboarding engineering teams with Claude Code. Part 1: The Foundation · Part 2: Plugins and the Marketplace · Part 3: Skills GitHub template →

Hooks: Automated Guardrails

Standards that rely on human memory don't scale. A CLAUDE.md that says "use conventional commits" is only as reliable as the developer's attention at commit time. This is where hooks convert suggestions into enforcement.

Hooks are shell commands that execute at specific points in Claude Code's lifecycle. They can observe, modify, or block operations based on your team's rules.

The Hook Lifecycle

What this means in practice: Hooks are automatic checks that run without the developer doing anything. When Claude opens, before it writes a file, after it finishes editing, when it completes a task—at each of these moments, your team's rules run in the background. A developer can't forget to run the linter. They can't accidentally commit a secret. The guardrails are structural, not advisory.

SessionStart → UserPromptSubmit → PreToolUse → [Tool Execution] → PostToolUse → Stop

Each event gives you a different enforcement point.

SessionStart hooks run when a developer opens Claude Code. Use these to load context, check environment prerequisites, or initialize team-specific toolchains.

What this does: The moment Claude opens, it already knows what sprint the team is on, whether the developer's environment is configured correctly, and what context is relevant for today's work—without the developer asking.

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "echo '{\"message\": \"Current sprint: $(curl -s https://linear.app/api/team/sprint)\"}'"
      }
    ]
  }
}

PreToolUse hooks fire before Claude executes a tool—writing a file, running a command, making an edit. These can block dangerous operations or modify inputs.

What this does: Before Claude writes any file, it runs your secret-detection script. If an API key or token would be written to disk, the write is blocked automatically. No code review needed to catch it. The mistake never happens.

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "scripts/check-no-secrets.sh",
        "matcher": "Write|Edit"
      }
    ]
  }
}

This hook runs a script before every file write or edit, checking that the content doesn't contain API keys, tokens, or other secrets. If the script exits with a non-zero code, the operation is blocked and Claude receives the error message.

PostToolUse hooks fire after a tool succeeds. The most common use: running your formatter and linter after every file modification so that code never exists in a non-compliant state.

What this does: Every time Claude edits a file, it's immediately formatted and linted. The diff in the PR is always clean. Style review comments disappear from your pull requests—not because developers remember to run the formatter, but because it runs automatically after every change.

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "scripts/format-and-lint.sh $CLAUDE_FILE_PATH",
        "matcher": "Write|Edit"
      }
    ]
  }
}

Stop hooks fire when Claude finishes responding. Use these as quality gates—verifying that tests pass, types check, or coverage thresholds are met before a task is considered complete.

What this does: When Claude says "I'm done," a hook verifies that the tests actually pass before the session ends. If they don't, Claude is sent back to fix them. "Done" means done—not "done, but you should probably run the tests."

{
  "hooks": {
    "Stop": [
      {
        "type": "prompt",
        "prompt": "Did the assistant run the test suite and verify all tests pass? If not, reject and ask it to run tests."
      }
    ]
  }
}

The "type": "prompt" hook is particularly useful—instead of running a shell command, it sends the context to a fast Claude model that makes a yes/no judgment call. This lets you express guardrails in natural language rather than brittle regex patterns.

Hook Configuration for Teams

Like skills, hooks can be scoped to different levels:

• Project hooks in .claude/settings.json—committed, shared, team-wide
• Personal hooks in ~/.claude/settings.json—your own guardrails
• Enterprise hooks in managed settings—admin-enforced, non-overridable

For organizations that need strict control, the allowManagedHooksOnly flag disables all user, project, and plugin hooks, ensuring only administrator-approved hooks execute.

Putting It All Together

Here's what a fully configured team environment looks like in practice:

your-project/
├── CLAUDE.md                          # Team standards and context
├── packages/
│   ├── api/CLAUDE.md                  # API-specific conventions
│   └── web/CLAUDE.md                  # Frontend-specific conventions
├── .claude/
│   ├── settings.json                  # Plugin config + hooks
│   └── skills/
│       ├── deploy/SKILL.md            # Deployment ritual
│       ├── new-endpoint/SKILL.md      # API endpoint scaffold
│       ├── review/SKILL.md            # PR review checklist
│       └── incident/SKILL.md          # Incident response workflow
└── scripts/
    ├── format-and-lint.sh             # PostToolUse hook target
    └── check-no-secrets.sh            # PreToolUse hook target

A new developer joins the team. They clone the repo, open Claude Code, and trust the project folder. Here's what happens:

1. Plugins install automatically. The TypeScript language server, GitHub integration, and internal design system docs plugin are all prompted for installation based on .claude/settings.json.

2. CLAUDE.md loads. Claude knows the tech stack, the naming conventions, the testing requirements, and the git workflow before the developer types a single character.

3. SessionStart hooks fire. The developer's environment is checked for prerequisites. Current sprint context is loaded. Environment variables are configured.

4. The developer starts working. They ask Claude to create a new API endpoint. The new-endpoint skill activates, and Claude scaffolds the route handler, schema, database query, and tests following the exact pattern the team uses.

5. PostToolUse hooks format every file as it's written. The code is never in a non-compliant state.

6. PreToolUse hooks block secrets from being written to files.

7. The developer types /deploy. Claude walks through the entire deployment checklist—running tests, checking the branch, monitoring the deploy.

8. Stop hooks verify quality. Tests pass. Types check. The work is done.

The new developer didn't read a wiki. They didn't ask in Slack which linter config to use. They didn't accidentally use default exports because they didn't know the team prefers named exports. The standards were never communicated as documentation—they were experienced as the natural behavior of the tool.

The Rollout Plan

If you're adopting this for an existing team, the practical path is incremental:

Week 1: Write your CLAUDE.md. Start with your tech stack, top five coding standards, and git conventions. Commit it. This alone provides significant value—Claude will apply these standards to every session immediately.

Week 2: Encode your two or three most common workflows as skills. These are the things you explain to new developers most often—the deploy process, the endpoint scaffolding, the PR checklist. Commit them to .claude/skills/.

Week 3: Add PostToolUse hooks for formatting and linting. This removes an entire category of review comments from your pull requests. The code is always formatted. The linter always passes. Stop reviewing style.

Week 4: Evaluate the plugin marketplace for your stack. Configure the project-level plugin requirements in .claude/settings.json. Stand up an internal marketplace if you have organization-specific tooling to distribute.

Ongoing: Treat your CLAUDE.md, skills, and hooks like production code. Review changes in PRs. Iterate based on what you learn. Remove rules that aren't useful. Add rules when you find yourself repeating the same review comments.

GitHub template: All the files described in this series—CLAUDE.md, the four skills, settings.json with hooks, and the format-and-lint / check-no-secrets scripts—are in the accompanying template repository. Copy what you need and adapt it to your stack.

What You're Actually Doing

The goal isn't to automate away engineering judgment. It's to stop wasting that judgment on things that should be automated—formatting, file structure, deployment checklists, secret detection. The more you encode into the toolchain, the more your team's attention is freed for the work that actually requires human thought: architecture decisions, product tradeoffs, and the subtle design choices that no linter will ever catch.

Your coding standards shouldn't live in a document people read once and forget. They should live in the environment where the code is written. That's the difference between standards that are documented and standards that are enforced.