Every developer knows code review matters. It catches bugs, improves architecture, and keeps code maintainable. But when you're deep in a flow state—plan approved, implementation humming along, feature nearly complete—it's tempting to call it done and move on. The review gets skipped, deferred, or reduced to a quick skim. I built a system that makes skipping impossible.
Using Claude Code's hooks system, I created an automated gate that detects when a plan implementation session is complete and blocks the session from ending until a comprehensive code review has been performed. It's like having a senior engineer who never forgets to review the PR before it merges.
The Problem: Review Fatigue After Implementation
If you've read my earlier post on Plan Mode, you know I'm a big believer in structured planning before writing code. Plan Mode ensures you think through architecture, edge cases, and user experience before a single line changes. But there's a gap in that workflow.
After a planning session produces a solid roadmap and the implementation is complete—sometimes spanning dozens of file changes across frontend and backend—the natural instinct is to wrap up. You've been collaborating with Claude Code for an extended session, the feature works, and you're ready to commit. The problem is that implementation mode is fundamentally different from review mode. When you're building, you're focused on making things work. When you're reviewing, you're asking whether things are built well. Those are two distinct mindsets, and context-switching between them at the end of a long session is exactly when quality slips.
How Hooks Work
Claude Code hooks are shell commands or prompts that execute automatically in response to lifecycle events. You configure them in your settings file, and they run without manual intervention. The key events include things like Stop (when Claude is about to end its turn), and hooks can return approve to allow the action or block to prevent it.
The hook type I'm using is a prompt hook—rather than running a shell command, it sends a prompt back to Claude Code itself to evaluate the conversation and make a decision. This is powerful because the hook has access to the full conversation context to make intelligent, nuanced decisions.
The Hook: An Automated Code Review Gate
Here's the Stop hook I configured:
{ "hooks": { "Stop": [ { "matcher": "", "hooks": [ { "type": "prompt", "prompt": "Review the conversation transcript to determine if this stop follows a PLAN IMPLEMENTATION session..." } ] } ] } }
The prompt instructs Claude Code to analyze the conversation and determine whether a code review is warranted. It should approve stopping (allow the session to end) if any of these are true:
- A code review was already completed in this session
- The session only involved questions, discussion, or file exploration
- Only a single small edit was made
- No plan was discussed or approved
- Changes were limited to configuration or documentation
It should block stopping only when all of these are true:
- A development plan was explicitly discussed and approved
- Multiple source code files were created or modified to implement the plan
- Claude indicated the implementation is complete
- No code review has been performed yet
When the hook blocks, it triggers a system message instructing Claude Code to spawn a specialized code-reviewer agent. This is a separate subagent—a distinct process with its own context window and its own set of instructions. It doesn't inherit the main agent's reasoning or biases from the implementation session. It reads the changed files fresh, evaluates them against its own review-focused criteria, and reports back its findings.
Why This Design Works
Smart Filtering, Not Blanket Rules
The most important design decision was making the gate conditional. A hook that forced a code review on every single session would be annoying—you don't need a full review when you're asking a question, exploring a codebase, or tweaking a config file. By scoping the trigger narrowly to plan implementation sessions with substantial code changes, the review only fires when it actually adds value.
The Right Mindset at the Right Time
The code-reviewer is a separate agent with its own context and instructions—it doesn't share the main agent's conversation history or reasoning. This matters more than it sounds. The agent that just spent an hour implementing a feature has built up justifications for every decision it made. It's not going to second-guess itself. The reviewer agent has none of that baggage. It sees the code as-is, evaluates it against its own review-focused instructions, and flags concerns the implementation agent would rationalize away. This separation mirrors how human code review works best—the author builds, someone else reviews—except here it's enforced architecturally rather than by org chart.
Zero Friction When Not Needed
If you're just chatting, reading files, or making a quick one-line fix, the hook evaluates the conversation, determines no review is needed, and approves the stop instantly. You never even notice it's there. The 30-second timeout ensures that even if the evaluation takes a moment, it won't hang your session.
What the Reviewer Catches
The code-reviewer agent isn't doing a superficial lint check. It performs a comprehensive review covering:
- Structural issues: Components that are too tightly coupled, missing abstractions, or responsibilities in the wrong layer
- Scalability concerns: Patterns that work now but will break under growth—N+1 queries, unbounded loops, missing pagination
- Maintainability: Naming inconsistencies, duplicated logic, unclear interfaces that will confuse future developers
- Pattern adherence: Whether new code follows existing project conventions or introduces unnecessary divergence
In practice, I've found it catches things I would have noticed in a manual review the next day—but by then I've already committed and moved on. Getting that feedback immediately, while the context is fresh, means fixes are trivial instead of disruptive.
Beyond Code Review: Other Hook Patterns
Once you see how this works, other applications become obvious:
- Test verification: Block stopping after implementation until tests pass
- Documentation checks: Require README or changelog updates when public APIs change
- Security scanning: Flag sessions that touch authentication or authorization code for extra scrutiny
- Commit preparation: Automatically stage and format a commit message summary when implementation is complete
The hooks system turns Claude Code from a reactive tool into a proactive workflow partner that enforces your team's quality standards automatically.
Conclusion: Automate the Discipline
The best processes are the ones you don't have to remember to follow. By wiring code review into Claude Code's lifecycle, I've removed the decision of whether to review from the equation entirely. Every substantial implementation gets reviewed. Every time. No exceptions, no willpower required.
This hook has changed how I think about AI-assisted development. It's not just about generating code faster—it's about building guardrails that keep quality high even as velocity increases. Plan Mode ensures you build the right thing. The review hook ensures you build it well. Together, they create a development workflow where speed and quality aren't competing priorities.
If you're using Claude Code for anything beyond simple one-off tasks, I'd encourage you to explore hooks. Start with the code review gate described here, then layer on whatever quality checks matter most to your project. The few minutes of setup pay for themselves the first time the reviewer catches something you would have shipped.
