Sorting Five Rules into Five Mechanisms
A platform team is setting up a new monorepo and has collected five things they want Claude Code to "know" or respect:
- "The repo uses Bazel;
bazel build //...is the only supported build entry point — don't suggestmakeor raw compiler invocations even if you find leftover Makefiles." - Claude discovered, mid-session, that a particular flaky CI job
needs
--test_timeout=120or it spuriously fails, and this isn't written down anywhere in the repo. - "Every file under
services/payments/**must NOT be edited without a second engineer's explicit sign-off in the PR — this is a compliance requirement, not a style preference." - Frontend-specific conventions (component structure, CSS
approach) that only matter to the ~15 engineers who ever touch
apps/web/**, out of 200 engineers in the monorepo. - One engineer's personal habit of wanting commit messages formatted a specific way, across every project they touch, not just this one.
For each, name the single best-fit mechanism (CLAUDE.md, a
.claude/rules/ file, auto memory, settings.json permissions, a
hook, or "personal ~/.claude/CLAUDE.md") and justify it against the
others that might seem plausible.
1. Bazel-only build → root CLAUDE.md.
This is exactly the profile CLAUDE.md is for: a team-wide,
always-relevant fact that would surprise an agent (leftover
Makefiles are a real trap — a plausible wrong turn without this
instruction), applies regardless of which files are being touched,
and is authored by the team and reviewed like any other file. It
doesn't need enforcement-grade guarantees (worst case, Claude
suggests make once and gets corrected), so a hook would be
over-engineering for what's fundamentally a routing instruction, not
a safety-critical one.
2. The flaky-CI timeout discovery → auto memory (left as default behavior, not moved to CLAUDE.md yet).
This is a discovered, provisional fact, not a reviewed team decision — exactly auto memory's use case. Claude will save this on its own without being asked, since it's the kind of durable-but- minor insight auto memory exists to capture. It's reasonable for the team to later promote it to CLAUDE.md once it's confirmed durable and worth every engineer knowing without rediscovering it — but that promotion should be a deliberate, reviewed step, not the first landing place. Filing it straight into CLAUDE.md before it's been validated risks committing a workaround for what might turn out to be a one-off flake.
3. Payments sign-off requirement → a hook (PreToolUse or a CI/PR-level check), not CLAUDE.md alone.
This is explicitly framed as a compliance requirement, where the
cost of a miss is high and there's a mechanical check available
(does this PR touching services/payments/** have a second
approval). CLAUDE.md is advisory context; Claude "usually" respecting
a compliance rule isn't the guarantee compliance needs. The right
answer is a hook (or a repo-level branch protection / CI gate
outside Claude Code entirely, which is arguably even more
appropriate here since it's fundamentally a human-process
requirement) — with a CLAUDE.md note explaining why, so Claude's
first instinct is already correct rather than needing to be blocked
and redirected every time.
4. Frontend-only conventions for apps/web/** → .claude/rules/
with paths: frontmatter scoped to that directory.
This is genuinely CLAUDE.md-shaped content — team-authored,
reviewed, version-controlled — but it fails the "relevant to every
session" test that justifies the root file's always-loaded cost. Of
200 engineers, 185 would pay the context cost of these conventions
every session for zero benefit if they landed in the root CLAUDE.md.
A .claude/rules/frontend.md (or similar) with paths: ["apps/web/**"] loads only when Claude is actually working with
matching files, which is precisely the tradeoff path-scoped rules
exist to make in a large repo.
5. Personal commit-message formatting, across every project →
personal ~/.claude/CLAUDE.md (user-level, not project-level).
This is explicitly scoped to one engineer and explicitly meant to
apply everywhere, not just this monorepo — the definition of a
user-level instruction. Putting it in the project's ./CLAUDE.md
would impose one person's formatting habit on 200 engineers via a
file that's supposed to hold team-shared conventions; putting it in
auto memory would tie it to one repo's memory directory when the
whole point is that it should apply across every project this
engineer works in. ~/.claude/CLAUDE.md is loaded on every session
regardless of which project you're in, which matches the stated
requirement exactly.
Share this question