Path-specific rules

An agent can't follow an instruction it never sees, and a CLAUDE.md that holds every instruction about every file grows too long to follow. A path-specific rule puts an instruction in front of the agent when it works on the files the instruction is about.

Know path-specific rules already? Skip to In Terrarium.

---
paths:
  - "src/api/**/*.ts"
---
# API handlers

- Validate every request body before you use it.

In Terrarium

Terrarium gives each instruction one home, chosen by what it is about. An instruction about certain files is a RuleA short instruction in .claude/rules/ that reaches an agent on its own, at session start, when it works on the files the rule names, or when it runs the Skill the rule names.GLOSSARY.md in .claude/rules/ whose paths match those files. An instruction every session needs, or one tied to an action such as a commit or a PR, stays in CLAUDE.md. For example, .claude/rules/tenant-layers.md matches each Tenant layer's nuxt.config.ts, tenant.config.ts and app/ folder, so an agent editing a TenantOne site inside Terrarium, with its own components and content model, built as a Nuxt layer.GLOSSARY.md learns that a layer's CSS loads on every page:

1---
2paths:
3  - "nuxt.config.ts"
4  - "layers/*/nuxt.config.ts"
5  - "layers/*/tenant.config.ts"
6  - "layers/*/app/**"
7---
8# Tenant layers
⋯<!-- … -->
25- **A layer is not a sandbox.** Its `css:` loads on every page (scope it under
26  the wrapper class), its plugins and `nuxt.config` flags apply app-wide (keep
⋯<!-- … -->

Every ADRAn architecture decision record, a short file stating one decision, why it was made, and the alternatives it rejected. has a summary rule too, adr-NNNN.md. It gives the ADR's key parts as instructions and says when to read the whole ADR. Its paths list the files the ADR governs, so the decision arrives when an agent works on something it governs. Only a summary whose ADR is relevant to every session has no paths, and it loads at session start.

scripts/gate/validate-adr-rules.ts, part of pnpm validate:content and so of the GateThe fixed set of machine checks every change must pass before it merges. It runs locally and in CI, and the CI run decides.GLOSSARY.md, fails any rule other than an ADR summary that has no paths. How it also keeps each summary in step with its ADR is in Decision records.

Two hooks fill the gaps where Claude Code loads no rule. Running a SkillA folder of instructions for one repeatable job, committed with the code, that a session runs when the job comes up.GLOSSARY.md reads no file, so scripts/hooks/skill-rules-hint.ts adds the rules whose paths name that Skill's folder. A piped or chained shell command is not a simple read, so scripts/hooks/bash-rules-hint.ts adds the rules for the files such a command read. .claude/settings.json wires both in, and both fail open: an error adds nothing and never blocks the call.

Where next

• LessonCLAUDE.md
• LessonClaude Code Skills
• LessonProtected paths
• LessonDecision records