Reward
Make your AI agent keep clean architecture: the lint rule, the Stop hook and the one line
An eslint-plugin-boundaries config for your layers, a Claude Code Stop hook that runs it, the one line for CLAUDE.md, and a checklist to keep CI as the final gate.
A layer rule written in CLAUDE.md is a guideline, and Claude Code's docs say Claude is allowed to decide a guideline doesn't apply. So put the rule in a lint, run the lint in a hook, and keep CI as the final gate.
1. Write your layers as a lint rule
Install eslint-plugin-boundaries (v7.4.1 at the time of writing). Here ui may import services, services may import db, and anything else fails:
// eslint.config.js
import boundaries from "eslint-plugin-boundaries";
export default [{
plugins: { boundaries },
settings: {
"boundaries/elements": [
{ type: "ui", pattern: "src/ui/*" },
{ type: "services", pattern: "src/services/*" },
{ type: "db", pattern: "src/db/*" },
],
},
rules: {
"boundaries/dependencies": [2, {
default: "disallow",
policies: [
{ from: { element: { type: "ui" } }, allow: { to: { element: { type: "services" } } } },
{ from: { element: { type: "services" } }, allow: { to: { element: { type: "db" } } } },
],
}],
},
}];This is a simplified config. Element patterns are relative paths, so adjust them to your folders and check the quick start.
Prefer a separate tool? dependency-cruiser does the same with forbidden rules: npx dependency-cruiser --init, then npx dependency-cruiser src.
2. Run the lint in a Stop hook
A Stop hook runs when Claude tries to end its turn. Exit code 2 blocks the stop, and whatever the command wrote to stderr goes back to Claude as the reason. Add this to .claude/settings.json:
{
"hooks": {
"Stop": [
{ "hooks": [
{ "type": "command", "command": "npx eslint src 1>&2 || exit 2" }
] }
]
}
}1>&2 sends ESLint's output to stderr, so Claude reads the errors and fixes them before it can finish.
3. Give CLAUDE.md one line: the command
Keep CLAUDE.md short (Anthropic's guide says under 200 lines). Don't describe your architecture and file layout there: Claude reads the repo itself. Do give it the exact commands:
- Lint (checks layer imports): npx eslint srcThe same line works in AGENTS.md, which Codex, Cursor, Copilot's coding agent, Gemini CLI, Jules and others read. Those tools treat it as guidance, so nothing there promises the agent will run the command.
4. Keep CI as the final gate
- If the hook blocks 8 stops in a row with no tool call in between, Claude Code lets the turn end. (
CLAUDE_CODE_STOP_HOOK_BLOCK_CAPraises that cap.) - So run
npx eslint srcin CI too. The hook catches it early, and CI makes sure it never merges.
Checklist
0 / 7 done