Paths Subjects Questions Quizzes Pricing Search
Advanced Open Free

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:

  1. "The repo uses Bazel; bazel build //... is the only supported build entry point — don't suggest make or raw compiler invocations even if you find leftover Makefiles."
  2. Claude discovered, mid-session, that a particular flaky CI job needs --test_timeout=120 or it spuriously fails, and this isn't written down anywhere in the repo.
  3. "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."
  4. 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.
  5. 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.

Solution

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

← Back to CLAUDE.md and Context Configuration practice

We use cookies for product analytics to improve OmniAtlas. See our Privacy Policy.