Load conventions when matching files need them

Learning objective

Configure .claude/rules/ YAML paths frontmatter for conditional rule matching.

Core idea

A convention for Terraform files does not need to enter every coding session. Put it in a Markdown rule under .claude/rules/ and give it YAML paths frontmatter. Claude Code uses the patterns to decide when to load the instruction body into context. This separates the loading condition from the convention itself.

A heading in the root CLAUDE.md can organize Terraform instructions, but it does not make them conditional. A rule file without paths also loads at launch. The condition is the recognized frontmatter field, not the filename, heading, or the author’s statement that a paragraph applies only to infrastructure.

See 3.1.3 for organizing standing conventions into topic files. This lesson adds the loading contract: what Claude Code parses, which file access activates a rule, and how a malformed configuration defeats the intended scope.

How it works

Put the condition in frontmatter

Project rules are Markdown files in .claude/rules/. Claude Code discovers .md files recursively, so a rule may live in a topic subdirectory. Each file should cover one topic and have a descriptive filename. For example, .claude/rules/infrastructure/terraform.md can hold the following illustrative team convention:

---
paths:
  - "terraform/**/*"
---

# Terraform conventions

- Use the team's resource naming convention.
- Preserve the required ownership tags when changing resources.

The YAML block sits at the top of the file between --- markers. paths accepts a YAML list or a comma-separated string. A flow-style YAML list, paths: ["terraform/**/*"], expresses the same single-pattern condition as the block list in the example. Prefer an explicit list when maintainers need to review several patterns separately.

paths is the only rule frontmatter field Claude Code reads. Other fields are ignored without an error. A field named files, scope, or include does not implement this condition. Claude Code removes the frontmatter before loading the rule into context; the model receives the instruction body rather than a YAML configuration it must interpret.

The rule’s storage path and its target path have different jobs. The infrastructure/ folder groups rule files for maintainers. The terraform/**/* pattern selects the project files whose access triggers loading. Do not infer the target from the rule’s folder name. See 3.3.2 for choosing glob patterns and 3.3.3 for deciding whether a directory instruction file is a better home.

Understand the activation trigger

A path-scoped rule loads when Claude uses Read, Write, or Edit on a matching file. It also loads when Claude views a matching file with a Bash command that counts as a read, such as cat or head on a single file. Loading can therefore happen during investigation before any modification.

For the example, access to terraform/main.tf activates the Terraform rule. Access to src/api/orders.ts does not match that pattern. A rule without paths is different: Claude Code loads it unconditionally at launch, with the same priority as .claude/CLAUDE.md.

This saves context space by deferring file-specific guidance until relevant file access. It does not establish that a loaded rule is removed whenever Claude changes files. Avoid treating the pattern as a continuously enforced filter on every later model response. It determines when instructions enter context.

Project rule discovery also depends on the session’s configuration. Project rules are skipped if project is excluded from --setting-sources. A correctly written paths field cannot compensate for a session that excludes the configuration source holding the rule.

Separate parsing failures from matching failures

If the YAML between the frontmatter markers does not parse, Claude Code ignores that frontmatter and loads the rule as if it had no paths. Run claude --debug to see the parse error. Malformed YAML can therefore broaden loading instead of merely preventing it.

A misspelled key has a similar practical result for a different reason. Valid YAML containing files: ["terraform/**/*"] parses, but files is ignored. The rule has no recognized paths, so it is unconditional. Correct the identifier rather than changing the convention’s wording.

A recognized paths field with a pattern that matches no intended files is a separate problem. The condition exists, but the selected set is wrong. Check representative target paths before concluding that Claude ignored the instruction body. See 3.1.4 for instruction-loading diagnostics.

A rule defers loading only when its frontmatter parses and contains a recognized paths field; otherwise it loads at launch.

Key distinctions and trade-offs

Conditional versus unconditional: paths defers a rule until matching file access. Omitting it is appropriate for instructions every task needs. It is a defect when a specialist convention is meant to stay out of unrelated work.

Loading versus enforcement: Rules supply instructions to the model. They are not permissions that prevent access outside the listed paths, and they do not guarantee strict compliance. The pattern controls the rule’s loading, not the tools’ authority.

Parse validity versus scope validity: Valid YAML establishes that the condition can be read. Representative matches establish that it selects the intended files. Neither proves the other.

Conditional rules reduce irrelevant startup context, but require maintainers to keep scope and file layout aligned. A small, explicit pattern is easier to inspect than an instruction that relies on the model to decide which part of a large global file applies.

Architecture / decision scenario

A developer-productivity team uses Claude Code for application changes and infrastructure reviews. Terraform naming guidance sits in the root CLAUDE.md, so application-only sessions receive it too. The team moves that guidance to .claude/rules/infrastructure/terraform.md with paths: ["terraform/**/*"] and leaves genuinely project-wide instructions at the root.

During a review, Claude reads terraform/network/main.tf. The rule loads at that access; an edit is not required first. The team checks loading evidence rather than assuming the absence of a file modification means the convention stayed unloaded. For this investigation (see 3.1.4), an InstructionsLoaded record can identify load_reason: "path_glob_match", the rule’s file_path, its globs, and the trigger_file_path. The event provides observability and cannot block or modify loading.

An unrelated API session unexpectedly receives the Terraform guidance at launch. The rule contains files instead of paths. The team restores the recognized field. If the YAML itself is malformed, it uses claude --debug to inspect the parse error. If no project rules load at all, it checks whether --setting-sources excludes project. These are configuration defects with different remedies; rewriting the naming guidance addresses none of them.

Common exam traps

• Treating a topic heading in CLAUDE.md as conditional loading.
• Assuming a subfolder under .claude/rules/ supplies the target scope.
• Using files instead of the recognized paths field.
• Expecting malformed YAML to keep a rule safely unloaded.
• Waiting for an edit when a matching read already activates the rule.
• Treating paths as a file-access permission or guaranteed enforcement.

Where the exam guide differs

What to remember

Put the loading condition in paths and the convention below the frontmatter. Missing or ignored fields make a rule unconditional; malformed YAML does too. Matching file access activates a scoped rule before an edit may occur. Verify the configuration source, parsing, and target match before changing the instruction text.

Knowledge check

References

• Anthropic, How Claude remembers your project
• Anthropic, Hooks reference
• Anthropic, Claude Certified Architect – Foundations Exam Guide