DEV Community: André Bremer

Developing with Claude Code? You should be using Checkmate!

André Bremer — Thu, 29 Jan 2026 04:37:29 +0000

You completed a long Claude Code session and are ready to commit everything. But wait! You still need to run all the pre-commit checks (linting, type-checking, formatting). Now you spend many iterations getting everything fixed, and it gets messy—you're also dealing with potential regressions from refactoring.

Well, no longer. Checkmate immediately checks Claude Code's work after each file modification. It uses your existing toolchain and configuration, forcing Claude Code to assess and correct issues immediately, so they don't accumulate, resulting in clean commits.

This simple tool is now a key foundation of my workflow and completely eliminated time-consuming and token-wasting clean-up work, which sometimes could take multiple iterations lasting minutes.

How it Works

Checkmate is a simple plugin that executes a script after each file modification. The script determines whether the modified file path matches the checkmate configuration in your project and runs all configured tools in order (for example: format check, linting, then type checking). If there are failures, the script reports a "block" back to Claude Code with all the diagnostics included, causing Claude Code to fix the issue immediately.

Setup

Setup is trivial. First install the plugin:

# From marketplace
/plugin marketplace add rcrsr/claude-plugins
/plugin install checkmate@rcrsr

Then configure your project with:

/checkmate:checkmate-init

The initialization skill will explore your codebase, identify your stack, and create a configuration for your project with all the tools correctly set up. It will even work with multi-lingual monorepos, automatically detecting your language and folder-specific environments:

During the flow, you can customize or add to your setup if anything was missed.

The configuration will be written to .claude/checkmate.json. You can always edit and adjust the configuration directly or use /checkmate:checkmate-refresh to apply any changes to your environment.

Usage

Now, every time Claude Code modifies your files, Checkmate will run any configured tests (or ignore excluded or skipped files) and report back any issues that Claude Code will fix in the next turn:

That's pretty much it! Your commits will be substantially cleaner after your next long session.

Advanced Configuration

Checkmate is smart about discovering your toolchain. During initialization, it scans your project for configuration files and package manifests, then sets up the appropriate checks automatically. A TypeScript project with Prettier gets tsc and prettier checks. A Python project using Ruff gets ruff check and ruff format. It even handles polyglot monorepos—detecting that your backend/ folder needs Python linting while frontend/ needs ESLint.

Beyond the common tools (ESLint, TypeScript, Prettier, Biome, Ruff, shellcheck, and others), you can add your own checks. Checkmate understands several output formats out of the box, or you can supply a custom regex for parsing errors. I prefer my custom checks to output JSONL—one JSON object per line with file, line, and message fields—which Checkmate parses natively.

Reviewer Subagents

If you use specialized subagents for implementation, you can configure reviewer subagents that trigger automatically after an agent completes. For example, you could have a code-reviewer triggered after a matching engineer task.

Try it on your next session and watch commit cleanups disappear! See the Checkmate GitHub repo for complete documentation.

Common Questions

Why am I getting "hook returned blocking errors" twice?

This is a Claude Code quirk. When a hook returns blocking errors, the message appears twice even though the hook was only invoked once. Just ignore the duplicate message.

Why not just use Claude Code's built-in LSP plugins?

The LSP plugins work the same, but they may not use your toolchain or your configuration. They are also limited to just type-checking. Checkmate provides a framework for customizations and extensions.

Why can't Checkmate apply fixes with "--fix"?

This would mess with Claude Code's internal state and also introduce unintended side effects. Sometimes, Claude Code may add code non-atomically, like adding a new import before adding the code that uses it. Auto-fixing would remove the import before Claude Code has the opportunity to add the new code.

How to Make Claude Code Work Reliably in Large Codebases

André Bremer — Sat, 01 Nov 2025 00:23:03 +0000

Claude Code writes Optional[str]. You want str | None. It catches exceptions with bare except Exception:. You require specific exception types. It uses List[str] from typing. You've standardized on built-in generics.

Claude Code is trained on millions of codebases with millions of conventions. Your codebase has one set of conventions: yours. And Claude Code doesn't know them unless you tell it.

The obvious solution is CLAUDE.md. Document your standards there, and Claude Code follows them. This works until your standards hit a few dozen lines. Beyond that, problems emerge. At 400 lines of Python conventions, architecture rules, and testing patterns, Claude Code starts missing details buried in the middle. Critical rules get overlooked.

Alignment Challenges at Scale

It only gets worse in large codebases and monorepos: multiple apps, packages, infrastructure, services, each with their own conventions. Your backend has Python standards. Your frontend has TypeScript conventions. Your data pipeline has its own architecture rules. You could organize these into folders with dedicated CLAUDE.md files, but domains don't always map cleanly to directories. A service might touch three domains. A shared library might have different rules than the applications consuming it. Standards sprawl across files, and Claude Code loads context it doesn't need while missing context it does.

The problem compounds when you start using subagents. These are specialized Claude Code instances you spawn for specific tasks. A common scenario is to use an engineer agent for implementation, a code reviewer for validation, and maybe a dedicated architect for design decisions. Each subagent runs in its own context, which is precisely why they're useful: they stay focused on their task with dedicated context and without the baggage of the entire conversation.

But that isolation creates coordination challenges. In a multi-domain codebase, you might have a core-engineer and core-reviewer for your shared libraries, a backend-engineer and backend-reviewer for your services, an infra-engineer for your deployment code. Each domain has its own conventions. Each engineer-reviewer pair needs to enforce the same standards so the engineer produces code that passes the reviewer's checks, and both need the right standards for their domain.

Keeping these agents in sync manually is a maintenance nightmare. Update a Python convention and you're touching six agent files. Miss one, and your backend-reviewer enforces rules your backend-engineer doesn't know about.

The fix isn't better documentation. It's compartmentalized rules that agents fetch on demand. Each agent gets exactly the standards it needs for its task, nothing more. Need-to-know context, guaranteed consistency.

Provide the Right Context When It's Needed

What if we could provide all the relevant context dynamically for each agent? Not stuffed into CLAUDE.md, not duplicated across files, but injected at the moment the agent starts, based on what that specific agent needs.

Claude Code makes this possible through hooks. Hooks are scripts that run automatically at specific points in Claude Code's lifecycle: before a tool executes, after a file changes, or when a subagent spawns. They let you intercept and augment Claude Code's behavior without modifying your prompts.

Here's how it works: when a subagent spawns, a hook scans the agent definition file for references to your standards. It finds those references, resolves them, and injects the relevant sections directly into the subagent's prompt. The agent receives its task instructions along with the exact policies it needs to follow. Think of it like handing an employee their assignment along with the relevant sections of the company handbook.

This works well because the context is strongly associated with the task. We don't have to rely on the agent discovering weakly associated system prompt or memory content.

Unambiguous Reference Notation

Here's what that looks like in practice. I came up with a notation system that unambiguously references sections in my standards documents. An agent definition includes a Required Policies section:

## Required Policies

["§PY", "§CORE"]

Before the agent starts, a hook invokes a policy server that scans the agent file for these special references. It resolves them against a set of well-maintained policy files, pulls the specific content, and appends it to the prompt starting the agent.

To align subagents, just have them reference the same policies. My engineer and code reviewer both include ["§PY", "§CORE"]. When the hook resolves these references, both agents receive identical policy content. No duplication, no drift, no conflicting interpretations.

The policy server handles the mechanical work: fetch the sections, resolve any cross-references, return exactly what's needed. Request §PY.2 (Runtime Safety), get that section plus any sections it references.

A Concrete Example

Policy files live in .claude/policies/. They're regular markdown with sections marked using § notation. The system scans all files in the folder, so you can organize standards however you like and files can reference each other. Here's a simplified example:

## {§PY.1} Python 3.14 Type Standards

All Python code MUST use Python 3.14 type syntax.

### {§PY.1.1} Built-in Generic Types

Use built-in generic types. NEVER import `List`, `Dict` from `typing`.

### {§PY.1.2} Union Types with Pipe Operator

Use `|` operator for union types. NEVER import `Optional` or `Union`.

## {§PY.2} Runtime Safety

### {§PY.2.1} Specific Exception Handling

Catch specific exceptions. NEVER use bare `except Exception:`.
See §PY.1 for type syntax in exception handlers.

For guidance on writing effective policies (structure, examples, what good and bad look like), see the §META policy standards, which is itself a good example of how policy files should be structured.

With the policy file in place, subagents can now reference sections by notation. You can cherry-pick what you need, or pull in entire sections or documents.

§PY fetches all Python policies (every §PY.* section)
§PY.1 fetches the entire Type Standards section with all subsections
§PY.2.1 fetches just the Specific Exception Handling subsection

Cross-references resolve automatically. When §PY.2.1 mentions §PY.1, both get included.

Setup

Setup is straightforward. Install the policies plugin:

/plugin marketplace add rcrsr/claude-plugins
/plugin install policies@rcrsr

Store your policy files in .claude/policies/ using § notation. Add a "Required Policies" section to your agent files with the references you need. Policies auto-inject when the agent runs.

The plugin also includes commands for generating policies from existing code patterns (/policies:create-policies) and auditing them against quality standards (/policies:review-policies).

For advanced configuration or alternative integration scenarios, see the mcp-policy-server project.

Why This Beats Semantic Search

This isn't RAG. There's no "find relevant content" step, no vector embeddings, no semantic matching.

Request §PY.1.1, get §PY.1.1. Exact lookup. Same input always produces the same output.

Your subagents fetch §PY.2.1 and get identical content about exception handling. Not "similar content about exceptions," but the exact same text. That's what creates alignment.

Summary

Subagent alignment isn't a prompt engineering problem. It's a shared context problem.

When subagents share the same policy sections, they enforce the same standards. When cross-references resolve automatically, nothing gets missed.

Same policies. Same standards. Predictable behavior.

Explore more:

This article was originally published October 2025 and revised January 2026 to reflect the evolution from MCP server integration to the hooks-based policies plugin, with updated examples focused on software engineering workflows.