How to Implement Path-Scoped Coding Rules for Different Directories

Path-scoped coding rules are implemented by creating Markdown files with YAML front matter in .claude/rules/ that specify glob patterns in a paths array, which the system automatically enforces through PostToolUse hooks when files matching those patterns are written or edited.

Claude Code Game Studios uses a directory-specific enforcement system to ensure that gameplay code, engine core, UI components, and prototypes each follow distinct standards. By attaching rule definitions to specific path globs, the system automatically loads and validates relevant constraints whenever an agent modifies a file, eliminating the need for manual checklist verification.

Understanding the Path-Scoped Rule Architecture

The mechanism relies on three interconnected components that work together during the Write|Edit lifecycle.

Rule Files with YAML Front Matter

Individual rule definitions live in .claude/rules/*.md as Markdown files with YAML front matter. Each file declares its scope through a paths array containing glob patterns.

For example, .claude/rules/gameplay-code.md targets all files under src/gameplay/:

---
paths:
  - "src/gameplay/**"
  - "src/ai/**"
---

# Gameplay Code Rules

- No hard-coded balance values; use `BalanceData` resources
- All skill effects must implement `validate_skill_change()` hooks

Rules Reference Documentation

The .claude/docs/rules-reference.md file serves as the human-readable index and machine-accessible registry. It contains a table mapping each rule file to its path patterns and enforcement scope, which the engine uses to discover applicable rules quickly.

Settings and Hook Pipeline

The .claude/settings.json configures the validation trigger mechanism. It registers the PostToolUse hook pipeline that executes after file write operations:

{
  "hooks": {
    "PostToolUse": [
      ".claude/hooks/validate-assets.sh",
      ".claude/hooks/validate-skill-change.sh"
    ]
  }
}

When an agent writes a file, these scripts parse the relevant rule files and block the commit if violations exist.

Implementing a New Path-Scoped Rule

Follow these steps to create directory-specific enforcement for a new project section.

Step 1: Create the Rule File

Create a Markdown file in .claude/rules/ with a descriptive name. Start with YAML front matter defining the paths array using glob patterns:

---
paths:
  - "prototypes/**"
---

# Prototype Code Rules

- Every prototype must contain a top-level `README.md` describing the hypothesis
- Source files may use `print()` for debugging, but **must not** contain production `assert` statements
- All exported assets **must** be listed in `assets/manifest.json` with a version tag

Save this as .claude/rules/prototype-code.md.

Step 2: Document in Rules Reference

Add an entry to .claude/docs/rules-reference.md to maintain the human-readable index:

| Rule File | Path Pattern | Enforces |
|-----------|--------------|----------|
| `prototype-code.md` | `prototypes/**` | README presence, asset manifest, no production asserts |

Step 3: Verify Hook Activation

Confirm that .claude/settings.json includes the validation script in the PostToolUse array. The validate-assets.sh script automatically discovers new rule files by scanning .claude/rules/ and matching their paths globs against the modified file.

How Validation Works at Runtime

When an agent attempts to write prototypes/awesome/experiment.gd, the enforcement chain activates automatically:

1. Path Matching: The validate-assets.sh hook scans .claude/rules/ and identifies that prototype-code.md has a paths entry matching prototypes/**.

2. Rule Parsing: The script extracts the Markdown content below the YAML front matter, parsing bullet points into discrete checks.

3. Violation Detection: If prototypes/awesome/ lacks a README.md, the hook returns a blocking error:

   
   ❌ Violation: Prototype must contain a top-level README.md (see .claude/rules/prototype-code.md)
   

4. Agent Correction: The agent must create the missing README.md and re-execute the write operation before the system allows the edit to persist.

This "May I write?" enforcement pattern ensures that path-scoped rules are checked before every file modification, maintaining codebase consistency without requiring manual review.

Key Files and Their Roles

File	Purpose	Location
.claude/rules/*.md	Stores individual path-scoped rule definitions with paths front matter	.claude/rules/
.claude/docs/rules-reference.md	Human-readable index and machine registry of all rules	[.claude/docs/rules-reference.md](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/docs/rules-reference.md)
.claude/settings.json	Configures the PostToolUse hook pipeline that triggers validation	[.claude/settings.json](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/settings.json)
.claude/hooks/validate-assets.sh	Executable script that parses rule files and enforces standards on `Write	Edit` operations

Summary

• Path-scoped coding rules are defined in Markdown files with YAML front matter located in .claude/rules/.
• The paths array in the front matter uses glob patterns to determine which directories a rule governs.
• Automatic enforcement occurs through PostToolUse hooks configured in .claude/settings.json, specifically scripts like validate-assets.sh.
• The rules reference at .claude/docs/rules-reference.md maintains the human-readable index and machine registry.
• Agents must resolve violations before writes are permitted, ensuring consistent standards across gameplay, engine, UI, and prototype directories.

Frequently Asked Questions

How do path-scoped rules differ from global coding standards?

Path-scoped rules allow different standards for different project areas, whereas global standards apply uniformly. In Claude Code Game Studios, the paths array in rule files enables specific requirements for src/gameplay/** (no hard-coded values) while allowing relaxed debug rules for prototypes/** (print statements permitted). This granularity prevents boilerplate in experimental code while enforcing rigor in production systems.

What happens if a file matches multiple path patterns?

When a file matches multiple paths globs, the validation hook aggregates all applicable rules and enforces them collectively. For example, a file under src/gameplay/ai/ might match both src/gameplay/** and src/ai/** patterns, triggering validation against both rule sets. The agent must satisfy all constraints before the write operation succeeds.

Can I use regular expressions instead of glob patterns in the paths array?

The system uses standard glob patterns in the paths array, not regular expressions. Patterns like prototypes/** or src/**/*_test.gd follow glob syntax where * matches any characters within a segment and ** matches across directory boundaries. For complex matching needs, create multiple specific glob entries rather than regex patterns.

How do I test a new rule before committing it to the repository?

To test a rule locally, create the rule file in .claude/rules/ with the paths array targeting a test directory, then attempt to write a file that violates the rule. The validate-assets.sh hook will immediately report the violation and block the write. Verify that the rule correctly matches intended paths by testing files inside and outside the glob patterns, then document the rule in .claude/docs/rules-reference.md once satisfied.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}