Resume
← Blog

2026.11.08 · 6 min · claude-code · ai · agents · tooling

Give your AI agent a check, not a suggestion.

A layer rule in CLAUDE.md is a guideline the agent may decide doesn't apply. Written as a boundary lint and run by a Claude Code Stop hook, it becomes a red check the agent has to fix before it can finish. The lint config, the hook, the one line CLAUDE.md still needs, and where CI stays the final gate. As of 2026.11.

Agents write code faster than you can review it, and without a hard constraint they mix patterns: a React component that calls the database directly, three folders away from the service that should own the query. The usual fix is a paragraph in CLAUDE.md about your layers. That works most of the time. The fix that works every time is a lint rule the agent can't finish without passing.

Watch the 60-second version on Instagram.

Thoughtworks CTO Rachel Laycock made the same point on martinfowler.com on 2026.10.29, in Why are good developers so wary of agentic development?: tests and architecture checks are the "harness" for agents, and "a red build should mean something". This post is that harness for one rule: which layer may import which.

Guidelines can be skipped

Claude Code's best-practices page splits instructions into two kinds:

KindExamplesWho decides
Non-deterministicyour prompt, CLAUDE.md, skillsthe model, each time
Deterministichooks, deny rules, managed settingsthe harness, always

The page is blunt about it: "If something has to happen every time, make it a hook… CLAUDE.md is for guidelines, and Claude is allowed to decide a guideline doesn't apply." It also now lists "Describe your architecture and file layout in CLAUDE.md" as advice you can stop following, because Claude reads the repo itself.

So the layer rule doesn't belong in CLAUDE.md as prose. It belongs in a lint config, where breaking it is a failure, not a judgement call.

Write the layers as a lint rule

DBSERVICESUIUI→DB · FAILFIG. 01 / UI → SERVICES → DB

With eslint-plugin-boundaries (v7.4.1), you name each layer as an element and list the imports each one may make. default: "disallow" turns everything else into an error: ui may import services, services may import db, and ui importing db 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 simplified. Element patterns are relative paths, and a linter only checks the files its config matches, so make sure the patterns cover every folder you care about. A folder no pattern matches is a folder the rule never sees.

If you'd rather not touch ESLint, dependency-cruiser does the same through forbidden rules: npx dependency-cruiser --init, then npx dependency-cruiser src.

Make the lint the definition of done

A rule nobody runs is still a suggestion. Claude Code's Stop hook runs when Claude tries to end its turn. If the hook exits with code 2, the stop is blocked and whatever the hook wrote to stderr goes back to Claude as the reason. Pipe the lint output to stderr and the agent gets the exact file and import it has to fix:

.claude/settings.json
{ "hooks": { "Stop": [ { "hooks": [
  { "type": "command", "command": "npx eslint src 1>&2 || exit 2" } ] } ] } }
AGENTSTOP HOOKDONEESLINT · UI → DBEXIT 2 · STDERRFIX IMPORTDONELINT GREENEXIT 2 BLOCKS THE STOP · 8 IN A ROW, THEN IT ENDSFIG. 02 / FAILING LINT = NOT DONE

The agent says it's done, the lint fails on ui → db, the stop is blocked, the agent reroutes the call through services/, and only a green lint lets it finish. Factory describes the same move in Using Linters to Direct Agents: linters encode "architecture, boundaries", and "'lint green' becomes the definition of 'Done'".

There's a limit, and it matters. If the hook blocks 8 stops in a row with no tool call in between, Claude Code lets the turn end anyway (CLAUDE_CODE_STOP_HOOK_BLOCK_CAP raises the cap). The hook catches the mistake in the session; CI is still the final gate.

What CLAUDE.md is still for

Keep it short: the memory guide says under 200 lines. Fill it with the exact test, typecheck and lint commands, the spots in the repo that mislead, and decisions that aren't written down anywhere else. Anthropic's line for it: "The single most useful line… is the command that runs it." For this rule, that's one line:

CLAUDE.md
- Lint (checks layer imports): npx eslint src

The same goes for AGENTS.md, the cross-tool version read by Codex, Cursor, Copilot's coding agent, Gemini CLI, Jules and others, where the nearest file in the tree wins. Codex concatenates them root-first, up to 32 KiB by default (project_doc_max_bytes). But the AGENTS.md docs describe it as guidance the agent reads, and don't promise the agent runs the commands in it. Outside Claude Code's hooks, CI has to be the enforcer.

On a client project I'd put exactly one or two rules behind a hook, the ones with zero exceptions like layer imports, and leave every preference in CLAUDE.md where the agent is allowed to weigh it.

What people get wrong

  • "Just describe the architecture in CLAUDE.md." It works most of the time, not every time, and Anthropic now advises against describing the layout at all. The file holds the command; the rule goes in a lint; enforcement goes in a hook or CI.
  • "The hook means I can drop CI." The hook gives up after 8 blocks in a row. Keep the lint in CI.
  • "Put every rule in a hook." Keep the enforced set small: hooks are for rules with zero exceptions, and preferences stay in CLAUDE.md.
  • "The agent said all tests pass." Ask for evidence: the command it ran and its output.

Is any of this measurable? One study of 441 repos (A Few Pages of Markdown) found that agent-first repos with no committed AI config saw cognitive complexity rise 53%, against 27% for repos with one, and 1.7× more static-analysis warnings. It's observational, so it shows a correlation, not that the config file caused the difference.

The full config, the hook and a checklist are on the rewards page for this post.

The short version

  1. CLAUDE.md and AGENTS.md are guidelines; Claude is allowed to decide one doesn't apply. Hooks always run.
  2. Write your layers as a lint rule (eslint-plugin-boundaries or dependency-cruiser): ui → services → db, anything else fails.
  3. Run the lint in a Stop hook: exit code 2 blocks the stop and sends the errors back to the agent.
  4. Put only the lint command in CLAUDE.md, not a description of your architecture.
  5. Keep the lint in CI: the hook gives up after 8 blocks in a row.

Sources: Claude Code, Best practices · AGENTS.md · OpenAI Codex, AGENTS.md guide · eslint-plugin-boundaries quick start · dependency-cruiser · Factory, Using Linters to Direct Agents · Denisov-Blanch et al., A Few Pages of Markdown · Laycock, Why are good developers so wary of agentic development?