Blog | Employees, technology, business, news, events | Mimacom

Don't Ask Your AI Assistant to Remember. Make It Comply.

Written by Raúl Avilés Saltos | Nov 18, 2026, 7:00:00 AM

AI coding assistants let anyone change a codebase, including people who have never seen the team’s conventions. Software Engineer Raúl Avilés Saltos explains why writing more instructions into CLAUDE.md doesn’t solve this, and how his team used Claude Code hooks and rules to make those conventions apply to every contributor, whether they know them or not.

Key takeaways

  • AI coding assistants mean more people can contribute to a codebase, but instructions in CLAUDE.md are context, not enforcement, so Claude follows them only some of the time.
  • On his current project, Raúl moved the team’s conventions into the repository: hooks run on every edit to lint files, block access to secrets, and enforce business limits, while rules give Claude the right conventions when it works on a matching file.
  • The result is fewer repeated PR comments: in the two months after the change, reviewer comments about conventions on the team’s frontend PRs dropped from 12 across 88 PRs to 3 across 110. Conventions now apply to every contributor, and safeguards for data, security, and money no longer depend on the model’s judgment.

It’s Monday morning, and a pull request comes in that isn’t from your team.

Maybe a backend developer needed a small fix in the frontend, or a new hire is in their first week, or a colleague from another team touched the code once and will never see it again. They all did the same thing: opened the repository, asked Claude to make the change, and pushed.

The code works, but the PR comes with unformatted files, a lint warning nobody ran, and a px where the team agreed on rem months ago. None of these issues is dramatic, but every one of them ends up with the reviewer.

This is the situation AI coding assistants have quietly created. Writing code is no longer limited to the people who know the project, because anyone with access and an assistant can contribute. That’s a real gain in speed, and also a real risk to consistency, because the conventions that keep a codebase healthy usually live in a wiki page nobody opens, the heads of two senior developers, and repeated PR comments.

Our project is an employee app for shift planning and time tracking in Swiss healthcare, built with Angular, Ionic, and Capacitor for web, iOS, and Android inside a larger Java/Spring monorepo. The app has around 275 components, and 13 people have committed to it in the last six months: frontend developers, backend developers who occasionally fix something in the frontend, and developers from other teams. That’s the Monday morning above, every week.

We addressed this with two Claude Code features: hooks and rules. This article explains what changed in practice, why the usual fix of writing more instructions doesn’t hold, and how a guardrail approach makes conventions apply to everyone, whether they know them or not.

 

The problem: Instructions are suggestions

The first instinct is always the same: if Claude doesn’t follow a convention, write it down. Add a line to CLAUDE.md, the file Claude Code reads at the start of every session:

Remember to format with Prettier, run ESLint, and check the types.

When that fails, people repeat it, and then they write it in capitals. Further down the file, after 200 lines of other instructions, you find something like this:

REMEMBER: NEVER DO X. SERIOUSLY, NEVER.

Writing it in caps doesn’t make it more mandatory; it just makes it louder. This isn’t a criticism of the model, but how the mechanism is designed. The Claude Code documentation is explicit: Claude treats CLAUDE.md files “as context, not enforced configuration,” and “to block an action regardless of what Claude decides, use a PreToolUse hook instead” (Claude Code docs, memory).

An instruction in a prompt competes with everything else in the context window, and in a long session, with a lot of code in between, its weight changes. Sometimes the assistant formats the file and sometimes it doesn’t, depending on the day, the context, and whether someone reminded it three messages ago. That’s probabilistic behavior, and for a team convention, you want deterministic behavior.

 

The change: A trigger in the agent’s lifecycle

To understand where hooks fit, it helps to look at what happens when you send a prompt to Claude Code. It’s not magic, just a loop: you write something, the agent decides whether it needs a tool (read a file, edit a file, run a command), uses it, looks at the result, and repeats until it can answer.

Two moments in that loop matter here: right before a tool runs and right after. Claude Code exposes both as events, PreToolUse and PostToolUse (Claude Code docs, hooks). If you’ve worked with a frontend framework, you already know the concept. It’s a lifecycle hook, like useEffect in React, mounted in Vue, or ngOnInit in Angular, applied to the agent’s lifecycle instead of the component’s.

A hook is a script with a trigger. You register it once in .claude/settings.json, which is committed with the project, and from then on it runs every time its event fires. It’s not a suggestion the model can weigh against other context; it’s code that executes. The difference between the two events matters: PreToolUse runs before the action, so it can block it, while PostToolUse runs after the action, so it can’t undo it, but it can fix the result or report on it.

 

The application: Three guardrails

We used the same four-step story for every case: the real pain, the usual attempt, the hook, and the outcome. One of the examples comes from our own project, and the other two show how the same pattern carries over to secrets and business rules.

 

Example 1: Automatic linting after every edit

The pain. Our team already had a checklist: format, lint, and check types. Everyone on the core team knew it well. The problem was never knowing the steps; it was that not everyone did them. When a new teammate joins and nobody hands them the process, or someone from another team fixes one bug, Prettier and ESLint get skipped and nobody runs the type check. The result is noisy PRs where reviewers can’t tell real changes from formatting changes.

The usual attempt. One more line in CLAUDE.md, which is easy to skip and easy to forget once the context gets long.

The hook. Instead, we registered a PostToolUse hook that fires every time Claude edits or creates a file:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/lint-check-changed-file.sh"
          }
        ]
      }
    ]
  }
}

The configuration has three parts and nothing else: the event (PostToolUse, after editing or creating), the matcher (Edit|Write, so it only fires for these tools), and the command, which points to a script in the project. The script receives the edited file path as JSON on standard input. It runs Prettier and eslint --fix on that file only, then runs tsc and filters the output down to errors in that file. If something can’t be fixed automatically, the report goes back to Claude, which corrects it in the same session.

The outcome. The same three checks now run after every edit, no matter who is typing, whether that’s the new hire, the contractor who touches the code once, or you on a Friday afternoon. Nobody has to remember anything, and that’s the whole point.

 

Example 2: Blocking access to secrets

The pain. Same story, different file. A contractor gets access for one PR, or a new hire is in their first week, and Claude reads the .env file while exploring the project, not even on purpose, because nobody told anyone it was off-limits.

The usual attempt. Ask nicely: “Please don’t read or edit the .env file.” But a request is not a wall. It’s an open door with a sticky note that says “keep out.”

The hook. Same structure, different event:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-env.sh"
          }
        ]
      }
    ]
  }
}

This time the event is PreToolUse, so the script runs before the action, and it can be very short:

#!/usr/bin/env bash
file_path="$(jq -r '.tool_input.file_path // empty')"

if [[ "$(basename "$file_path")" == .env* ]]; then
  echo "Access to .env files is blocked by project policy." >&2
  exit 2
fi

exit 0

The outcome. Exit code 2 blocks the tool call, so the read never happens, and the message on standard error goes back to Claude as the reason (Claude Code docs, hooks). Claude gets a clear explanation and moves on. For a simple path block, Claude Code also offers permissions.deny rules in settings. A hook becomes the better choice when the decision needs logic, as in the next example.

 

Example 3: The $100 wall

The context. Hooks aren’t limited to code style; the same pattern applies to business rules in any agent that calls tools. Imagine an agent that handles refunds for an online store. The business rule is simple: up to $100, the agent resolves the refund alone; above $100, a human signs off first.

The usual attempt. Put the rule in the agent’s prompt, then repeat it, then put it in capitals. It’s still a prompt, not a rule, and this time we’re talking about real money, not a px.

The hook. A PreToolUse hook on the refund tool. If the tool is exposed through an MCP server named shop, Claude Code names it mcp__shop__process_refund, and that’s what the matcher targets:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__shop__process_refund",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-refund.sh"
          }
        ]
      }
    ]
  }
}

The script decides; it doesn’t suggest:

#!/usr/bin/env bash
input="$(cat)"

if jq -e '.tool_input.amount > 100' >/dev/null <<<"$input"; then
  cat <<'EOF'
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Refunds above $100 require human review."
  }
}
EOF
fi

exit 0

The outcome. Below the threshold, the hook stays silent and the refund continues through the normal flow. Above it, the call is denied with a reason the agent can pass on to the customer and to the escalation process. Don’t politely ask the agent to stay on budget; put a wall at $100.

 

A practical rule for spotting the need for a hook

If you’ve written “IMPORTANT” twice in CLAUDE.md, that’s the signal. The capital letters mean you want determinism, not a more convincing prompt, so what you need is a hook, not another paragraph.

 

Rules: The conventions that used to live in someone’s head

Hooks enforce, but a lot of what makes a codebase consistent can’t be reduced to a script: naming, component architecture, API conventions, and design tokens. That knowledge needs to be explained at the right moment, and that’s what rules are for. A rule is a Markdown file in .claude/rules/. With a paths field in its frontmatter, it only loads into context when Claude works with a matching file (Claude Code docs, path-specific rules):

---
paths:
  - 'src/**/*.scss'
---

Use rem for width, height, font-size and other sizing properties.
Exceptions: border and box-shadow stay in px.
Use the styleguide color tokens instead of hardcoded hex values.

Unlike CLAUDE.md, a rule isn’t loaded at the start of every session. It appears when the file you’re touching matches the pattern, so the SCSS conventions show up when Claude opens a stylesheet, not when it’s writing a unit test.

Here’s a real example. When I joined the project, my first PR got a comment: “use rem, not px.” I fixed it, and on my second PR I got the same comment. The convention didn’t live in the project; it lived in the reviewer’s head. Once it became a rule, the comment stopped appearing. That wasn’t because I had learned it, but because it no longer depended on me remembering it. It’s a trivial example, but a real one.

The same mechanism extends to any convention. We now have separate rules for SCSS, TypeScript, and HTML templates, built partly from recurring PR comments and static-analysis findings, and each one only loads when it’s relevant. A developer from another team or a new hire won’t know these rules, but they follow them anyway, without an onboarding session or a wiki page. The rule lives in the repository, and the repository doesn’t forget.

One honest caveat: a rule is still context, not enforcement. It makes the right behavior far more likely by putting the convention in front of the model at the right time. When “far more likely” isn’t enough, that’s a job for a hook.

 

Synthesis: Rules explain, hooks enforce

The two mechanisms solve different halves of the same problem. Rules turn a convention into text Claude reads exactly when it matters, while hooks turn a convention into code that runs no matter what. Neither replaces the other. A useful way to decide: if breaking the convention is an inconvenience, a rule is usually enough. If breaking it costs money, leaks data, or blocks a release, it needs a hook.

The broader shift is where conventions live. They used to live in people: in reviewers, senior developers, and onboarding sessions. Now they live in the repository, versioned and reviewed like any other code. Teams made the same move years ago with CI pipelines and linters, and this applies it to a new kind of contributor.

 

What this means for teams

For developers, the day-to-day work changes in small but noticeable ways. You stop chasing the assistant to fix types, run the linter, and format the file, and reviews focus on logic instead of style. You also stop leaving the same PR comment for the fifth time.

For tech leads and architects, the question is no longer “how do we make sure everyone knows the conventions?” but “which conventions are encoded in the repo?” The second question is much easier to answer and audit. Guardrails are visible in .claude/, reviewed in PRs, and applied the same way to every contributor, internal or external.

For decision-makers, this is what makes opening a codebase to more contributors safe. AI assistants lower the barrier to contributing, which helps when teams share code across products or bring in temporary support. Hooks and rules make sure that lower barrier doesn’t come at the cost of quality, security, or business rules, because the rules that matter most aren’t left to the model’s judgment.

What’s changed in our project is less noise. The rules and hooks went into the repository together on August 26. In the 66 days before, reviewers left 12 comments about conventions on frontend PRs, such as px instead of rem, inject() instead of the constructor, naming, and folder structure. That was across 88 PRs, or about one every seven. In the 66 days after, they left 3 across 110 PRs, about one every 37. Comments from review bots aren’t counted. The sample is small and other things changed in the same period, including who was reviewing and the addition of an automated review bot, so this isn’t a controlled result. It does match what the team noticed: fewer repeated PR comments, conventions that no longer need explaining, and errors that never reach review because they never happen.

 

Where to start: Turn instructions into guardrails

The easiest place to start is your own CLAUDE.md. Every “NEVER” and “ALWAYS” in it is a candidate for a hook, because the capital letters show where you want a guarantee, not a reminder. A single PostToolUse hook that formats and lints the edited file is a low-risk first step. PreToolUse is the right event for anything that must not happen, such as reading secrets or exceeding a business threshold.

For the conventions that can’t be scripted, look at your PR comments. If you’ve written the same comment twice in a review, write it once as a path-scoped rule in .claude/rules/ instead. Then commit everything, because guardrails only work for every contributor if they live in the repository.

Don’t ask it to remember. Make it comply.